czechfabric-sdk 2.0.2
Complete Python SDK for CzechFabric MCP - Perfect mirror of backend with all 13 tools, type-safe models, and TONE format support
Requires Python: <4.0,>=3.9
Keywords: czechfabric, mcp, transport, air-quality, prague, czech-republic, public-transport, geocoding, routing, tone-format

# CzechFabric SDK

**Complete Python SDK for CzechFabric MCP - Perfect mirror of backend system**

[![PyPI version](https://badge.fury.io/py/czechfabric-sdk.svg)](https://pypi.org/project/czechfabric-sdk/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/czechfabric/czechfabric-sdk/workflows/Test/badge.svg)](https://github.com/czechfabric/czechfabric-sdk/actions)
[![Lint](https://github.com/czechfabric/czechfabric-sdk/workflows/Lint/badge.svg)](https://github.com/czechfabric/czechfabric-sdk/actions)
[![Parity Check](https://img.shields.io/badge/parity-PASS-green.svg)](https://github.com/czechfabric/czechfabric-sdk/actions)
[![Documentation](https://img.shields.io/badge/docs-available-blue.svg)](https://czechfabric.cz/docs/sdk)
[![PyPI downloads](https://img.shields.io/pypi/dm/czechfabric-sdk)](https://pypi.org/project/czechfabric-sdk/)

The CzechFabric SDK provides a complete, type-safe interface to all CzechFabric backend tools. All 13 tools are implemented with exact parameter and schema matching.

## Features

- ✅ **13 Tools** - Complete coverage of all backend tools
- ✅ **Type-Safe** - Full Pydantic models matching backend exactly
- ✅ **Format Support** - TONE (40-60% token savings), JSON, and both formats
- ✅ **Async & Sync** - Use async/await or synchronous wrappers
- ✅ **Validation** - Input validation before API calls
- ✅ **Error Handling** - Comprehensive exception types
- ✅ **Version Checking** - Automatic compatibility checks
- ✅ **Production Ready** - Comprehensive testing and documentation

## Installation

```bash
pip install czechfabric-sdk
```

## Quick Start

### Async Usage

```python
import asyncio
from czechfabric_sdk import CzechFabricClient, TransportMode

async def main():
    client = CzechFabricClient(
        api_key="your-api-key",
        base_url="https://mcp.czechfabric.cz"
    )
    
    # Get departures
    result = await client.get_departures(
        stop_name="Anděl",
        mode=TransportMode.METRO,
        max_results=10,
        format="json"
    )
    print(result)

asyncio.run(main())
```

### Sync Usage

```python
from czechfabric_sdk import SyncCzechFabricClient, TransportMode

client = SyncCzechFabricClient(
    api_key="your-api-key",
    base_url="https://mcp.czechfabric.cz"
)

# Get departures
result = client.get_departures(
    stop_name="Anděl",
    mode=TransportMode.METRO,
    max_results=10
)
print(result)
```

### Helper Methods

```python
# Domain-organized helpers
await client.tools.transport.get_departures("Anděl")
await client.tools.air_quality.current("Karlovo náměstí")
await client.tools.routing.plan_route("A", "B")
```

## Tools

### Transport (9 tools)

- **Departures**: `get_departures()`, `departures_by_coordinates()`, `suggest_departure_stops_nearby()`
- **Geocoding**: `geocode()`, `reverse_geocode()`
- **Stops**: `find_all_stops_near()`, `get_stop_metadata()`, `list_all_stops()`
- **Routing**: `plan_route_mapycz()`

### Air Quality (4 tools)

- `get_air_quality_near_location()` - Current air quality near location
- `get_air_quality_by_district()` - Air quality by district
- `get_air_quality_history()` - Historical data
- `list_air_quality_components()` - List all pollutants

## Response Formats

All tools support three response formats:

- **`tone`** (default) - Token-efficient TONE format string
- **`json`** - Standard JSON dict
- **`both`** - Full Pydantic model with both formats

## Error Handling

```python
from czechfabric_sdk.exceptions import (
    InvalidAPIKeyError,
    RateLimitExceededError,
    ValidationError,
    NetworkError
)

try:
    result = await client.get_departures("Anděl")
except InvalidAPIKeyError:
    print("Invalid API key")
except RateLimitExceededError:
    print("Rate limit exceeded")
except ValidationError as e:
    print(f"Validation error: {e}")
except NetworkError as e:
    print(f"Network error: {e}")
```

## Version Compatibility

The SDK automatically checks backend compatibility:

```python
# Strict mode - fails on version mismatch
client = CzechFabricClient(
    api_key="key",
    base_url="https://mcp.czechfabric.cz",
    strict_mode=True  # Raises error on mismatch
)

# Normal mode - warns on mismatch
client = CzechFabricClient(
    api_key="key",
    base_url="https://mcp.czechfabric.cz",
    check_version=True  # Warns on mismatch (default)
)
```

## Documentation

- **Full Documentation**: https://czechfabric.cz/docs/sdk
- **API Reference**: See `docs/` directory
- **Examples**: See `examples.md`
- **Changelog**: See `CHANGELOG.md`

## Requirements

- Python 3.9 or higher
- Valid CzechFabric API key
- Internet connection

## Development

```bash
# Clone repository
git clone https://github.com/czechfabric/czechfabric-sdk.git
cd czechfabric-sdk

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run linting
ruff check czechfabric_sdk

# Run type checking
mypy czechfabric_sdk
```

## License

MIT License - see [LICENSE](LICENSE) file.

## Support

- **GitHub Issues**: https://github.com/czechfabric/czechfabric-sdk/issues
- **Email**: support@czechfabric.cz
- **Documentation**: https://czechfabric.cz/docs/sdk

## Contributing

Contributions welcome! Please see our contributing guidelines.

---

**Made with ❤️ for the Czech Republic**