Metadata-Version: 2.4
Name: nirmi-events-sdk
Version: 1.3.1
Summary: Python SDK for Nirmi Events API - No API keys needed, connects to your Nirmi backend
Home-page: https://github.com/narmiAI/nirmi-events-sdk
Author: Nirmi
Author-email: Nirmi <support@nirmi.ai>
Project-URL: Homepage, https://github.com/narmiAI/nirmi-events-sdk
Project-URL: Documentation, https://github.com/narmiAI/nirmi-events-sdk#readme
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: pydantic>=2.6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# Nirmi Events SDK

A Python SDK for accessing Nirmi's event, place, and weather data services. This SDK connects to your Nirmi backend API, which manages all API keys - you don't need any API keys to use this SDK.

## Installation

```bash
pip install nirmi-events-sdk
```

Or install from source:

```bash
git clone https://github.com/nirmi/nirmi-events-sdk.git
cd nirmi-events-sdk
pip install -e .
```

## Quick Start

```python
from nirmi_events_sdk import Client
from datetime import datetime, timedelta

# Initialize the client with your Nirmi backend URL
# The backend has all API keys - you don't need any!
client = Client(
    api_base_url="https://api.nirmi.ai"  # Your Nirmi backend URL
)

# Get events near a location
events = client.get_events(
    latitude=41.3851,  # Barcelona
    longitude=2.1734,
    radius_km=5,
    start_time=datetime.now(),
    end_time=datetime.now() + timedelta(days=7)
)

# Chat with AI concierge
response = client.chat(
    message="What's happening tonight?",
    latitude=41.3851,
    longitude=2.1734
)

print(response["response"])
```

## No API Keys Needed!

This SDK connects to **your Nirmi backend API**, which manages all API keys:
- ✅ Google Places API (managed by Nirmi)
- ✅ Ticketmaster API (managed by Nirmi)
- ✅ Eventbrite API (managed by Nirmi)
- ✅ OpenWeather API (managed by Nirmi)
- ✅ OpenAI API (managed by Nirmi)

You just need the URL of your Nirmi backend API.

## Features

### Events

- ✅ **Eventbrite Integration**: Fetch events from Eventbrite
- ✅ **Ticketmaster Integration**: Fetch events from Ticketmaster
- ✅ **Location-based Search**: Search events by coordinates and radius
- ✅ **Date Filtering**: Filter events by start/end time
- ✅ **Automatic Deduplication**: Events from multiple sources are automatically deduplicated

### AI Concierge

- ✅ **Natural Language Chat**: Ask questions in natural language
- ✅ **Context-aware**: Understands location and conversation history
- ✅ **Multi-source Integration**: Combines events, places, and weather data

## Usage Examples

### Get Events

```python
from nirmi_events_sdk import Client
from datetime import datetime, timedelta

client = Client(api_base_url="https://api.nirmi.ai")

# Get events in the next week
events = client.get_events(
    latitude=41.3851,
    longitude=2.1734,
    start_time=datetime.now(),
    end_time=datetime.now() + timedelta(days=7),
    radius_km=10
)

for event in events:
    print(f"{event['name']} at {event['venue_name']} - {event['start_time']}")
```

### Chat with AI Concierge

```python
# Simple query
response = client.chat(
    message="What's happening tonight?",
    latitude=41.3851,
    longitude=2.1734
)
print(response["response"])

# With conversation history
conversation = [
    {"user": "What restaurants are nearby?", "assistant": "Here are some great restaurants..."}
]

response = client.chat(
    message="What about Italian restaurants?",
    latitude=41.3851,
    longitude=2.1734,
    conversation_history=conversation
)
print(response["response"])
```

## Configuration

### Backend URL

Set your Nirmi backend URL:

```python
client = Client(api_base_url="https://api.nirmi.ai")
```

For local development:
```python
client = Client(api_base_url="http://localhost:8000")
```

### Authentication (Optional)

If your backend requires authentication:

```python
client = Client(
    api_base_url="https://api.nirmi.ai",
    api_key="your-api-key"
)
```

## Response Formats

### Events

Each event contains:
- `id`: Event ID
- `name`: Event name
- `description`: Event description
- `start_time`: Formatted start time
- `end_time`: Formatted end time (if available)
- `url`: Event URL
- `venue_name`: Venue name
- `venue_address`: Venue address
- `venue_latitude`: Venue latitude
- `venue_longitude`: Venue longitude
- `source`: Source ("eventbrite" or "ticketmaster")

### Chat Response

```python
{
    "response": "AI-generated response text",
    "context_used": {
        "weather": {...},
        "places_found": 5,
        "events_found": 10
    }
}
```

## Error Handling

The SDK gracefully handles errors:
- If the backend is unavailable, returns empty results or error messages
- All errors are logged for debugging
- Network timeouts are handled with 30-second default timeout

## Requirements

- Python 3.8+
- requests >= 2.28.0
- pydantic >= 2.6.0

## Backend Setup

Your Nirmi backend should be running and accessible. The backend:
- Manages all API keys (Google, Ticketmaster, Eventbrite, OpenWeather, OpenAI)
- Provides `/events` and `/chat` endpoints
- Handles all third-party API calls

See the `nirmi-concierge-demo` for the backend implementation.

## License

MIT License

## Support

For issues and questions, please contact support@nirmi.ai
