Metadata-Version: 2.4
Name: czechfabric-sdk
Version: 0.2.6
Summary: Python SDK for Czech Intelligence Fabric (CzechFabric MCP)
Author-email: Abdulbasit Aliyu <ayindealiyu1@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/czechfabric/czechfabric-sdk
Project-URL: Repository, https://github.com/czechfabric/czechfabric-sdk
Project-URL: Issues, https://github.com/czechfabric/czechfabric-sdk/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: async-lru>=2.0
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

![PyPI](https://img.shields.io/pypi/v/czechfabric_sdk)
![License](https://img.shields.io/github/license/CzechFabric/czechfabric_sdk)
![Downloads](https://img.shields.io/pypi/dm/czechfabric_sdk)

# 🇨🇿 CzechFabric SDK

The official Python SDK for accessing the **Czech Intelligence Fabric (MCP)** - a unified API for Czech public services including transport, geolocation, and contextual AI tooling.

---

## 🚀 Features

- ✅ Plan public transport trips using OpenTripPlanner
- 🚏 Real-time departures from stop names or coordinates
- 🗺️ Geocode / Reverse-geocode locations
- 📍 Find nearby stops
- 📦 Fetch stop metadata and zone info
- 🧠 List available tools and generate LLM-friendly summaries
- 🔁 Built-in retry, caching, and error handling

---

## 📦 Installation

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

---

## ⚡ Quick Start

```python
from czechfabric_sdk.client import CzechFabricClient

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

# Example: Plan a trip
trip = await client.plan_trip("Florenc", "Karlovo náměstí", departure_time="in 15 minutes")
print(trip)
```

---

## 📚 Usage Examples

Explore detailed examples in [`examples.md`](./examples.md):

* 🚉 [Plan a trip](./examples.md#plan-a-trip)
* 📆 [Get departures](./examples.md#get-departures)
* 🧭 [Geocode / Reverse geocode](./examples.md#geocode-location)
* 📍 [Nearby stops](./examples.md#find-all-stops-near-coordinates)
* 🧾 [Stop metadata](./examples.md#get-stop-metadata)
* 📋 [List stops](./examples.md#list-all-stops)
* 🛠️ [List available tools](./examples.md#list-available-tools)
* 🤖 [Generate prompt summary](./examples.md#pretty-tool-summary-prompt-llm-style)

---

## 🧰 Tool Management

You can dynamically list tools exposed by the MCP server:

```python
tools = await client.get_tool_names()
prompt = await client.get_tool_prompt_summary()
print(prompt)
```

This is helpful for LLM-based assistants or debugging available capabilities.

---

## 🔐 Authentication

All requests require an API key:

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

You can generate your key from your CzechFabric user dashboard.

---

## ⚠️ Error Handling

The SDK provides structured exceptions:

* `NetworkError` – server unreachable or timed out
* `InvalidAPIKeyError` – auth failure
* `RateLimitExceededError` – too many requests
* `ToolExecutionError` – tool execution failed

---

## 🧪 Running Tests

```bash
pip install -r requirements-dev.txt
pytest tests/
```

---

## 📎 License

MIT © 2025 [Aliyu Abdulbasit Ayinde](mailto:ayindealiyu1@gmail.com)

---

## 🌐 Project Links

* 🧠 MCP Server: [https://mcp.czechfabric.cz](https://mcp.czechfabric.cz)
* 💬 Feedback & Issues: [GitHub Issues](https://github.com/czechfabric/czechfabric-sdk/issues)
