Metadata-Version: 2.4
Name: pythia-edc
Version: 0.1.1
Summary: Ask your Gaia-X data space in plain language. MCP-native Python SDK for Eclipse EDC.
Project-URL: Homepage, https://github.com/pareo-ai/pythia-edc
Project-URL: Repository, https://gitlab.com/gaia-x/gaia-x-community/gx-hackathon/gaia-x-hackathon-9/pythia-ask-your-dataspace
Author-email: Jonathan Kaleve <jonathan@pareo.ai>
License: MIT
Keywords: dataspace,eclipse-edc,edc,gaia-x,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: anyio>=4.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Provides-Extra: all
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: sentence-transformers>=3.0; extra == 'all'
Provides-Extra: ask
Requires-Dist: sentence-transformers>=3.0; extra == 'ask'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Pythia: Ask Your Dataspace

**Team Lead**: [Jonathan Kaleve](mailto:jonathan@pareo.ai) — [Pareo](https://pareo.ai)

---

Pythia was the Oracle at Delphi: you asked a question in plain language, and she answered. That’s the interface Gaia-X data spaces have been missing.

Today, accessing a data space means knowing provider URLs, asset IDs, ODRL policy structures, and the EDC negotiation state machine. The two existing Python clients are broken in practice — one requires RabbitMQ, the other doesn’t work against current EDC versions. There is no natural language interface. No AI agent integration.

Pythia changes this:

```python
from pythia import DataSpace

ds = DataSpace(
    management_url="http://consumer:29193/management",
    providers=[{"dsp": "http://provider:19194/protocol/2025-1", "id": "provider"}],
)

# Natural language query — Pythia negotiates the contract and retrieves data
data = await ds.ask("CO2 emissions data for German automotive suppliers 2023")
```

For AI agents, Pythia ships as an **MCP server** — making Gaia-X data spaces a native tool for Claude, GPT, or any MCP-compatible agent.

## What we built

| Layer | Component |
|---|---|
| 1 — Core client | Async `httpx` EDC client, full DSP state machine, typed errors, no RabbitMQ |
| 2 — NL interface | `ds.ask()` — parallel catalog fan-out + offline `all-MiniLM-L6-v2` ranking + auto-negotiate |
| 3 — MCP server | `pythia-mcp` — wraps `ds.ask()` as MCP tools for Claude / GPT / any agent |

## Install

```bash
pip install ‘pythia-edc[all]’
```

## Usage

```python
# Low-level
catalog = await ds.catalog.query(provider_dsp="...", provider_id="...")
agreement_id = await ds.negotiate(provider_dsp="...", provider_id="...",
                                  offer_id=offer.id, asset_id=asset.id)
data = await ds.fetch(provider_dsp="...", provider_id="...",
                      agreement_id=agreement_id, asset_id=asset.id)

# Natural language
data = await ds.ask("quarterly SVHC substance reports from EU chemical suppliers")
```

## MCP server

```bash
export PYTHIA_MANAGEMENT_URL="http://localhost:29193/management"
export PYTHIA_PROVIDERS=’[{"dsp": "http://localhost:19194/protocol/2025-1", "id": "provider"}]’
pythia-mcp
```

## Gaia-X standards

| Standard | Usage |
|---|---|
| DSP `dataspace-protocol-http:2025-1` | Full state machine: catalog → negotiate → transfer → EDR |
| DCAT | Catalog parsing, asset/offer extraction |
| ODRL | Policy offer construction with correct context |
| MCP (Model Context Protocol) | AI agent integration (`pythia-mcp` server) |

**Roadmap:** Gaia-X Meta Registry auto-discovery (providers: `[]` = discover from registry), GXDCH credential verification.

## Prerequisites

- Python 3.11+, running EDC consumer + provider connectors
- `sentence-transformers` for `ds.ask()` (offline, `BAAI/bge-small-en-v1.5`, ~130MB)

---

*Built at Gaia-X Tech-X 2026 / Hackathon #9 — Athens, 28–29 May 2026*