# meshpocalypse-semantic — Python SDK

Python SDK for the [Meshpocalypse Semantic](https://github.com/one137th/Meshpocalypse-Semantic) mesh layer.

Provides async Python access to:
- **NATS messaging** via `MeshNode` async context manager
- **SPARQL queries** against the mesh RDF graph via `SparqlClient`
- **ATF trust checks** via `ATFClient`

## Install

```bash
pip install meshpocalypse-semantic
```

## Quick Start

```python
import asyncio
from meshpocalypse_semantic import MeshNode, ATFLevel

async def main():
    async with MeshNode("nats://localhost:4222") as mesh:
        # Publish a message
        await mesh.publish("mesh.events.my-agent", b"hello mesh")

        # Run a SPARQL query
        rows = await mesh.sparql.query(
            "SELECT ?agent WHERE { ?agent a <https://meshpocalypse.dev/ontology#Agent> }"
        )
        for row in rows:
            print(row["agent"]["value"])

        # Check ATF trust level
        level = await mesh.atf.get_trust_level("did:mesh:my-agent")
        if level >= ATFLevel.SENIOR:
            print("Agent has operational access")

asyncio.run(main())
```

## Requirements

- Python ≥ 3.10
- NATS server running (e.g. `docker run -p 4222:4222 nats:latest`)
- `nats-py >= 2.8.0`, `rdflib >= 7.0`, `protobuf >= 4.0`

## Development

```bash
cd python-sdk
pip install -e ".[dev]"
pytest
```

## Notes

- **BYOK**: Bring your own NATS URL and LLM API keys — the SDK does not manage credentials.
- `MeshNode` must be used as an `async with` context manager; calling methods outside raises `RuntimeError`.
- `SparqlClient` requires a running Meshpocalypse SPARQL bridge on the NATS subject `mesh.sparql.query`.
- `ATFClient` requires the TypeScript ATF service on `mesh.atf.trust.check`.

See [docs/integrations/python.md](../docs/integrations/python.md) for the full usage guide.
