camino-ai-sdk 0.5.0

Camino AI Python SDK for location intelligence and spatial reasoning

Camino AI Python SDK

The official Python SDK for Camino 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
• 🌐 Web Enrichment: Real-time verification from Yelp, TripAdvisor, and other authoritative sources
• 📍 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

pip install camino-ai-sdk

Quick Start

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

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

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:

# 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",
    lat=40.7831,
    lon=-73.9712,
    radius=1000,  # meters
    limit=10
)
response = client.query(request)

# Access web enrichment data (if available)
for result in response.results:
    print(f"{result.name}")

    # Check web verification
    if result.web_enrichment and result.web_enrichment.web_verified:
        sources = [s['domain'] for s in result.web_enrichment.verification_sources]
        print(f"  Found on: {', '.join(sources)}")

        # Check operational status
        if result.web_enrichment.appears_operational is True:
            print(f"  ✅ Appears open (confidence: {result.web_enrichment.confidence})")
        elif result.web_enrichment.appears_operational is False:
            print(f"  ⚠️  May be closed (confidence: {result.web_enrichment.confidence})")

Query Modes

Control which features are enabled with the mode parameter:

# Basic mode (default) - Open data only
response = client.query(QueryRequest(
    query="coffee shops in Paris",
    lat=48.8566,
    lon=2.3522,
    mode="basic"  # No web enrichment, no AWS fallback
))

# Advanced mode - Additional data sources enabled
response = client.query(QueryRequest(
    query="coffee shops in Paris",
    lat=48.8566,
    lon=2.3522,
    mode="advanced"  # Includes web enrichment + AWS Location fallback
))

Mode options:

• mode="basic" (default): OpenStreetMap data only (no additional data sources)
• mode="advanced": Additional paid data sources enabled:
  • Tavily web enrichment: Real-time verification from authoritative sources (Yelp, TripAdvisor, etc.)
  • AWS Location Service fallback: When OSM has no results, fall back to AWS for better coverage

Cost consideration: Only use mode="advanced" when you need real-time web verification or improved coverage. Basic mode uses only open data and is suitable for most location queries.

Search

Search for places using free-form or structured queries via Nominatim:

from camino_ai import SearchRequest

# Free-form search
response = client.search("Eiffel Tower")

# Structured search with address components
response = client.search(SearchRequest(
    amenity="restaurant",
    city="Paris",
    country="France",
    limit=10,
    mode="basic"  # or "advanced" for web enrichment
))

# Access results
for result in response.results:
    print(f"{result.display_name}")
    print(f"  Location: {result.lat}, {result.lon}")
    print(f"  Type: {result.type}")

    # Check for web enrichment (only in advanced mode)
    if result.web_enrichment and result.web_enrichment.web_verified:
        print(f"  ✓ Web verified")

Mode parameter:

• mode="basic" (default): Nominatim search with open data only
• mode="advanced": Includes web enrichment for search results

Relationships

Calculate spatial relationships between locations:

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:

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:

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:

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:

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})")

Web Enrichment

Web enrichment provides real-time verification from authoritative web sources like Yelp, TripAdvisor, and official websites. This feature is only available in advanced mode (mode="advanced").

Features

• Web Verification: Confirms the place exists on authoritative sources
• Operational Status: Detects if a place appears open or closed based on recent web mentions
• Verification Sources: Lists which websites mention the location
• Recent Mentions: Provides snippets from recent web content

Usage

# Enable web enrichment by using advanced mode
response = client.query(QueryRequest(
    query="coffee shops near me",
    lat=40.7589,
    lon=-73.9851,
    mode="advanced"  # Required for web enrichment
))

result = response.results[0]

if result.web_enrichment:
    # Check if verified on the web
    if result.web_enrichment.web_verified:
        print("✓ Verified on the web")

    # Get verification sources
    for source in result.web_enrichment.verification_sources:
        print(f"  - {source['domain']}: {source['title']}")

    # Check operational status
    if result.web_enrichment.appears_operational is True:
        print(f"Likely OPEN (confidence: {result.web_enrichment.confidence})")
    elif result.web_enrichment.appears_operational is False:
        print(f"Likely CLOSED (confidence: {result.web_enrichment.confidence})")

    # Read recent mentions
    for mention in result.web_enrichment.recent_mentions:
        print(f"  {mention['snippet']}")
        print(f"  Source: {mention['url']}")

Requirements:

• Must use mode="advanced" in your query
• API must have TAVILY_API_KEY configured
• The place must be found in web search results

Note: Web enrichment incurs additional costs through Tavily. Use mode="basic" when web verification is not needed.

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

# 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

# Run tests
poetry run pytest

# Run tests with coverage
poetry run pytest --cov=camino_ai

# Run type checking
poetry run mypy camino_ai

Formatting

# Format code
poetry run black camino_ai tests
poetry run isort camino_ai tests

# Lint code
poetry run ruff check camino_ai tests

# Auto-fix linting issues
poetry run ruff check --fix camino_ai tests

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: docs.getcamino.ai