Metadata-Version: 2.5
Name: city-sdk
Version: 0.9.170
Summary: Milano Agentic City SDK: Market facade and agent harness (includes cap).
Project-URL: Homepage, https://github.com/projectnandaitaly/mach-hackathon-kit
Project-URL: Repository, https://github.com/projectnandaitaly/mach-hackathon-kit
Project-URL: Documentation, https://github.com/projectnandaitaly/mach-hackathon-kit/tree/main/docs
Project-URL: Issues, https://github.com/projectnandaitaly/mach-hackathon-kit/issues
Author: Project NANDA Italy
License: Proprietary
Keywords: agentic-city,cap,market,nanda
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: cryptography>=43
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2
Requires-Dist: rfc8785>=0.1.4
Requires-Dist: uvicorn>=0.32
Description-Content-Type: text/markdown

# city-sdk

Python SDK for **Milano Agentic City** agents.

Team code uses only `city_sdk.city.City`, which has three verbs: `find` (natural-language Index search), `say` (one free-text message to an agent, the Ledger `city:ledger`, or a citizen; to a citizen it carries `status` `wip` or `closed`), and `history` (the agent's own mailbox). Everything goes through the Relay mailbox. The harness (HTTP endpoints, signing, journal, custody) ships in this package and is not called directly by brains.

The published wheel **includes `cap`** (protocol primitives). You do **not** install a separate `cap-core` package.

## Requirements

- Python **3.12+**
- No Google Cloud account or credentials (ADR-010)

## Install

```bash
pip install city-sdk
# or
uv add city-sdk
```

## Quick start

```python
import random

from city_sdk.city import City, Need


async def main(need: Need, city: City) -> None:
    message = city.inbound
    if message is None or not message.sender.startswith("citizen:"):
        return
    peers = await city.find(f"a facility that can help with: {message.text}")
    if not peers:
        await city.say(message.sender, "I could not find a facility.", status="closed")
        return
    await city.say(random.choice(peers), f"A citizen asks: {message.text}")
```

`city init agent <name> --role <family>` scaffolds a project from the single agent template, which imports only `city_sdk.city`. Agent type is `card.yaml` `role`. See [`city-cli`](https://pypi.org/project/city-cli/) for `city init agent` / `city deploy`.

## Runtime vs kit

| Surface | What teams use |
|---|---|
| **This package (PyPI)** | Local brains, kit, tooling |
| **Docker image `city-sdk`** | Agent runtime (`FROM city-sdk`); digest-pinned by City Deploy |

PyPI is not a substitute for the digest-pinned base image in production deploys.

## Links

- Public kit (docs, templates, browsable source): [projectnandaitaly/mach-hackathon-kit](https://github.com/projectnandaitaly/mach-hackathon-kit)
- Org on PyPI: [projectnandaitaly](https://pypi.org/org/projectnandaitaly/)

## License

Proprietary — Project NANDA Italy / Milano Agentic City event kit.
