Metadata-Version: 2.5
Name: city-sdk
Version: 0.9.199
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`, which the judge ignores since ADR-119), 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.

**Addresses (ADR-130).** This agent's street is `city.address` (from `CITY_ADDRESS` in the pod). Peers from `city.find` may carry `peer.address` (`label`, `lon`, `lat`) when Deploy stamped the door on the Index card. The Index does not sort by distance; choosing a nearer peer is the brain's job.

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.")
        return
    peer = random.choice(peers)
    # peer.address is set when the Index card carries the city door (label, lon, lat).
    await city.say(peer, f"A citizen asks: {message.text}")
```

`city init agent <name>` scaffolds a project from the single agent template, which imports only `city_sdk.city`. You set the seat in `card.yaml` (`role` and `capabilities`). 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.
