# Camino AI Python SDK
The official Python SDK for [Camino AI](https://getcamino.ai) - Guide your AI agents through the real world with location intelligence, spatial reasoning, and route planning.
## Features
- 🌍 **Natural Language Queries**: Search for places using natural language
- 📍 **Spatial Relationships**: Calculate distances, bearings, and spatial relationships
- 🗺️ **Location Context**: Get rich contextual information about any location
- 🧭 **Journey Planning**: Multi-waypoint journey optimization
- 🛤️ **Routing**: Point-to-point routing with multiple transport modes
- ⚡ **Async Support**: Full async/await support for all operations
- 🔄 **Auto Retry**: Built-in retry logic with exponential backoff
- 📝 **Type Hints**: Full type annotations for better IDE support
- 🛡️ **Error Handling**: Comprehensive error handling with custom exceptions
## Installation
```bash
pip install camino-ai-sdk
```
## Quick Start
```python
from camino_ai import CaminoAI
# Initialize the client
client = CaminoAI(api_key="your-api-key")
# Search for coffee shops
response = client.query("coffee shops near Central Park")
for result in response.results:
print(f"{result.name}: {result.address}")
# Calculate spatial relationship
from camino_ai import RelationshipRequest, Coordinate
relationship = client.relationship(RelationshipRequest(
from_location=Coordinate(lat=40.7831, lng=-73.9712), # Central Park
to_location=Coordinate(lat=40.7589, lng=-73.9851) # Times Square
))
print(f"Distance: {relationship.distance}m")
```
## Async Usage
```python
import asyncio
from camino_ai import CaminoAI
async def main():
async with CaminoAI(api_key="your-api-key") as client:
response = await client.query_async("restaurants in Brooklyn")
print(f"Found {len(response.results)} restaurants")
asyncio.run(main())
```
## API Reference
### Client Initialization
```python
client = CaminoAI(
api_key="your-api-key",
base_url="https://api.getcamino.ai", # Optional
timeout=30.0, # Optional
max_retries=3, # Optional
retry_backoff=1.0 # Optional
)
```
### Query
Search for points of interest using natural language:
```python
# Simple string query
response = client.query("pizza places in Manhattan")
# Advanced query with parameters
from camino_ai import QueryRequest, Coordinate
request = QueryRequest(
query="coffee shops",
location=Coordinate(lat=40.7831, lng=-73.9712),
radius=1000, # meters
limit=10
)
response = client.query(request)
```
### Relationships
Calculate spatial relationships between locations:
```python
from camino_ai import RelationshipRequest, Coordinate
request = RelationshipRequest(
from_location=Coordinate(lat=40.7831, lng=-73.9712),
to_location=Coordinate(lat=40.7589, lng=-73.9851),
relationship_type="distance_and_bearing"
)
response = client.relationship(request)
print(f"Distance: {response.distance}m, Bearing: {response.bearing}°")
```
### Context
Get contextual information about a location:
```python
from camino_ai import ContextRequest, Coordinate
request = ContextRequest(
location=Coordinate(lat=40.7831, lng=-73.9712),
radius=500,
categories=["restaurant", "entertainment"]
)
response = client.context(request)
print(f"Context: {response.context}")
```
### Journey Planning
Plan optimized multi-waypoint journeys:
```python
from camino_ai import JourneyRequest, Waypoint, JourneyConstraints, TransportMode
request = JourneyRequest(
waypoints=[
Waypoint(location=Coordinate(lat=40.7831, lng=-73.9712)),
Waypoint(location=Coordinate(lat=40.7589, lng=-73.9851)),
Waypoint(location=Coordinate(lat=40.7505, lng=-73.9934))
],
constraints=JourneyConstraints(
transport_mode=TransportMode.DRIVING,
avoid_tolls=True
),
optimize=True
)
response = client.journey(request)
print(f"Total distance: {response.total_distance}m")
print(f"Total duration: {response.total_duration}s")
```
### Routing
Calculate routes between two points:
```python
from camino_ai import RouteRequest, Coordinate, TransportMode
request = RouteRequest(
start=Coordinate(lat=40.7831, lng=-73.9712),
end=Coordinate(lat=40.7589, lng=-73.9851),
transport_mode=TransportMode.WALKING,
avoid_highways=True
)
response = client.route(request)
print(f"Route distance: {response.distance}m")
print(f"Route duration: {response.duration}s")
```
## Error Handling
The SDK provides specific exception types for different error conditions:
```python
from camino_ai import CaminoAI, APIError, AuthenticationError, RateLimitError
try:
client = CaminoAI(api_key="invalid-key")
response = client.query("coffee shops")
except AuthenticationError as e:
print(f"Authentication failed: {e.message}")
except RateLimitError as e:
print(f"Rate limit exceeded. Retry after: {e.retry_after}s")
except APIError as e:
print(f"API error: {e.message} (status: {e.status_code})")
```
## Transport Modes
Available transport modes for routing and journey planning:
- `TransportMode.DRIVING` - Car/driving directions
- `TransportMode.WALKING` - Walking directions
- `TransportMode.CYCLING` - Bicycle directions
- `TransportMode.TRANSIT` - Public transportation
## Development
### Setup
```bash
# Clone the repository
git clone https://github.com/camino-ai/camino-sdks.git
cd camino-sdks/python
# Install dependencies
poetry install
# Install pre-commit hooks
pre-commit install
```
### Testing
```bash
# Run tests
poetry run pytest
# Run tests with coverage
poetry run pytest --cov=camino_ai
# Run type checking
poetry run mypy camino_ai
```
### Formatting
```bash
# Format code
poetry run black camino_ai tests
poetry run isort camino_ai tests
# Lint code
poetry run flake8 camino_ai tests
```
## License
This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.
## Support
- 📧 Email: support@getcamino.ai
- 🐛 Issues: [GitHub Issues](https://github.com/camino-ai/camino-sdks/issues)
- 📖 Documentation: [docs.getcamino.ai](https://docs.getcamino.ai)
Raw data
{
"_id": null,
"home_page": "https://github.com/camino-ai/camino-sdks",
"name": "camino-ai-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "camino, ai, geospatial, location, routing, sdk",
"author": "Camino AI",
"author_email": "support@getcamino.ai",
"download_url": "https://files.pythonhosted.org/packages/17/25/39a5151024865c89333d8e930e8cc104b2eb9854812e6944dbdf8163c8d5/camino_ai_sdk-0.3.0.tar.gz",
"platform": null,
"description": "# Camino AI Python SDK\n\nThe official Python SDK for [Camino AI](https://getcamino.ai) - Guide your AI agents through the real world with location intelligence, spatial reasoning, and route planning.\n\n## Features\n\n- \ud83c\udf0d **Natural Language Queries**: Search for places using natural language\n- \ud83d\udccd **Spatial Relationships**: Calculate distances, bearings, and spatial relationships\n- \ud83d\uddfa\ufe0f **Location Context**: Get rich contextual information about any location\n- \ud83e\udded **Journey Planning**: Multi-waypoint journey optimization\n- \ud83d\udee4\ufe0f **Routing**: Point-to-point routing with multiple transport modes\n- \u26a1 **Async Support**: Full async/await support for all operations\n- \ud83d\udd04 **Auto Retry**: Built-in retry logic with exponential backoff\n- \ud83d\udcdd **Type Hints**: Full type annotations for better IDE support\n- \ud83d\udee1\ufe0f **Error Handling**: Comprehensive error handling with custom exceptions\n\n## Installation\n\n```bash\npip install camino-ai-sdk\n```\n\n## Quick Start\n\n```python\nfrom camino_ai import CaminoAI\n\n# Initialize the client\nclient = CaminoAI(api_key=\"your-api-key\")\n\n# Search for coffee shops\nresponse = client.query(\"coffee shops near Central Park\")\nfor result in response.results:\n print(f\"{result.name}: {result.address}\")\n\n# Calculate spatial relationship\nfrom camino_ai import RelationshipRequest, Coordinate\n\nrelationship = client.relationship(RelationshipRequest(\n from_location=Coordinate(lat=40.7831, lng=-73.9712), # Central Park\n to_location=Coordinate(lat=40.7589, lng=-73.9851) # Times Square\n))\nprint(f\"Distance: {relationship.distance}m\")\n```\n\n## Async Usage\n\n```python\nimport asyncio\nfrom camino_ai import CaminoAI\n\nasync def main():\n async with CaminoAI(api_key=\"your-api-key\") as client:\n response = await client.query_async(\"restaurants in Brooklyn\")\n print(f\"Found {len(response.results)} restaurants\")\n\nasyncio.run(main())\n```\n\n## API Reference\n\n### Client Initialization\n\n```python\nclient = CaminoAI(\n api_key=\"your-api-key\",\n base_url=\"https://api.getcamino.ai\", # Optional\n timeout=30.0, # Optional\n max_retries=3, # Optional\n retry_backoff=1.0 # Optional\n)\n```\n\n### Query\n\nSearch for points of interest using natural language:\n\n```python\n# Simple string query\nresponse = client.query(\"pizza places in Manhattan\")\n\n# Advanced query with parameters\nfrom camino_ai import QueryRequest, Coordinate\n\nrequest = QueryRequest(\n query=\"coffee shops\",\n location=Coordinate(lat=40.7831, lng=-73.9712),\n radius=1000, # meters\n limit=10\n)\nresponse = client.query(request)\n```\n\n### Relationships\n\nCalculate spatial relationships between locations:\n\n```python\nfrom camino_ai import RelationshipRequest, Coordinate\n\nrequest = RelationshipRequest(\n from_location=Coordinate(lat=40.7831, lng=-73.9712),\n to_location=Coordinate(lat=40.7589, lng=-73.9851),\n relationship_type=\"distance_and_bearing\"\n)\nresponse = client.relationship(request)\nprint(f\"Distance: {response.distance}m, Bearing: {response.bearing}\u00b0\")\n```\n\n### Context\n\nGet contextual information about a location:\n\n```python\nfrom camino_ai import ContextRequest, Coordinate\n\nrequest = ContextRequest(\n location=Coordinate(lat=40.7831, lng=-73.9712),\n radius=500,\n categories=[\"restaurant\", \"entertainment\"]\n)\nresponse = client.context(request)\nprint(f\"Context: {response.context}\")\n```\n\n### Journey Planning\n\nPlan optimized multi-waypoint journeys:\n\n```python\nfrom camino_ai import JourneyRequest, Waypoint, JourneyConstraints, TransportMode\n\nrequest = JourneyRequest(\n waypoints=[\n Waypoint(location=Coordinate(lat=40.7831, lng=-73.9712)),\n Waypoint(location=Coordinate(lat=40.7589, lng=-73.9851)),\n Waypoint(location=Coordinate(lat=40.7505, lng=-73.9934))\n ],\n constraints=JourneyConstraints(\n transport_mode=TransportMode.DRIVING,\n avoid_tolls=True\n ),\n optimize=True\n)\nresponse = client.journey(request)\nprint(f\"Total distance: {response.total_distance}m\")\nprint(f\"Total duration: {response.total_duration}s\")\n```\n\n### Routing\n\nCalculate routes between two points:\n\n```python\nfrom camino_ai import RouteRequest, Coordinate, TransportMode\n\nrequest = RouteRequest(\n start=Coordinate(lat=40.7831, lng=-73.9712),\n end=Coordinate(lat=40.7589, lng=-73.9851),\n transport_mode=TransportMode.WALKING,\n avoid_highways=True\n)\nresponse = client.route(request)\nprint(f\"Route distance: {response.distance}m\")\nprint(f\"Route duration: {response.duration}s\")\n```\n\n## Error Handling\n\nThe SDK provides specific exception types for different error conditions:\n\n```python\nfrom camino_ai import CaminoAI, APIError, AuthenticationError, RateLimitError\n\ntry:\n client = CaminoAI(api_key=\"invalid-key\")\n response = client.query(\"coffee shops\")\nexcept AuthenticationError as e:\n print(f\"Authentication failed: {e.message}\")\nexcept RateLimitError as e:\n print(f\"Rate limit exceeded. Retry after: {e.retry_after}s\")\nexcept APIError as e:\n print(f\"API error: {e.message} (status: {e.status_code})\")\n```\n\n## Transport Modes\n\nAvailable transport modes for routing and journey planning:\n\n- `TransportMode.DRIVING` - Car/driving directions\n- `TransportMode.WALKING` - Walking directions \n- `TransportMode.CYCLING` - Bicycle directions\n- `TransportMode.TRANSIT` - Public transportation\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/camino-ai/camino-sdks.git\ncd camino-sdks/python\n\n# Install dependencies\npoetry install\n\n# Install pre-commit hooks\npre-commit install\n```\n\n### Testing\n\n```bash\n# Run tests\npoetry run pytest\n\n# Run tests with coverage\npoetry run pytest --cov=camino_ai\n\n# Run type checking\npoetry run mypy camino_ai\n```\n\n### Formatting\n\n```bash\n# Format code\npoetry run black camino_ai tests\npoetry run isort camino_ai tests\n\n# Lint code\npoetry run flake8 camino_ai tests\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.\n\n## Support\n\n- \ud83d\udce7 Email: support@getcamino.ai\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/camino-ai/camino-sdks/issues)\n- \ud83d\udcd6 Documentation: [docs.getcamino.ai](https://docs.getcamino.ai)",
"bugtrack_url": null,
"license": "MIT",
"summary": "Camino AI Python SDK for location intelligence and spatial reasoning",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://docs.getcamino.ai",
"Homepage": "https://github.com/camino-ai/camino-sdks",
"Repository": "https://github.com/camino-ai/camino-sdks"
},
"split_keywords": [
"camino",
" ai",
" geospatial",
" location",
" routing",
" sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3c184f7d23575c68ba4bec72e9a1f7aa7664331eaf23ab772cf21b48c1691cda",
"md5": "a2d78b2a63ae6bdc6ec428bef0a554a2",
"sha256": "3de30e6d15b9d54a6176208a23c491eb1821cfdb7de05a02dc1be0b9e7f7af2b"
},
"downloads": -1,
"filename": "camino_ai_sdk-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a2d78b2a63ae6bdc6ec428bef0a554a2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 13594,
"upload_time": "2025-08-29T15:30:24",
"upload_time_iso_8601": "2025-08-29T15:30:24.770458Z",
"url": "https://files.pythonhosted.org/packages/3c/18/4f7d23575c68ba4bec72e9a1f7aa7664331eaf23ab772cf21b48c1691cda/camino_ai_sdk-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "172539a5151024865c89333d8e930e8cc104b2eb9854812e6944dbdf8163c8d5",
"md5": "3e735bc59d0647219b1cc9d96c34cc89",
"sha256": "341ce7908ffc1e0d7f6e50ba0cde119a85ead9fd95f3a1d32139166d60bc3bca"
},
"downloads": -1,
"filename": "camino_ai_sdk-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "3e735bc59d0647219b1cc9d96c34cc89",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 12069,
"upload_time": "2025-08-29T15:30:25",
"upload_time_iso_8601": "2025-08-29T15:30:25.904329Z",
"url": "https://files.pythonhosted.org/packages/17/25/39a5151024865c89333d8e930e8cc104b2eb9854812e6944dbdf8163c8d5/camino_ai_sdk-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-29 15:30:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "camino-ai",
"github_project": "camino-sdks",
"github_not_found": true,
"lcname": "camino-ai-sdk"
}
JSON
