Metadata-Version: 2.4
Name: cosmos-agent-sdk
Version: 0.0.1a0
Summary: Python client for the Auggie v2 SDK / RPC protocol
Author-email: Augment Code <support@augmentcode.com>
License-Expression: MIT
Project-URL: Homepage, https://augmentcode.com
Project-URL: Repository, https://github.com/augmentcode/cosmos-agent-sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: ws
Requires-Dist: websocket-client>=1.7.0; extra == "ws"
Provides-Extra: mongo
Requires-Dist: pymongo>=4.6.0; extra == "mongo"
Provides-Extra: cloud
Requires-Dist: httpx>=0.27.0; extra == "cloud"
Provides-Extra: dev
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: websocket-client>=1.7.0; extra == "dev"
Requires-Dist: pymongo>=4.6.0; extra == "dev"
Requires-Dist: mongomock>=4.1.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"

# cosmos-agent-sdk — Python client

RPC-first Python client for the Auggie v2 SDK / RPC protocol. It implements the
shared spec under [`../../spec`](../../spec) and passes the shared
[`../../conformance`](../../conformance) fixtures, in lockstep with the
TypeScript client.

## Layers

- **Transport** (`cosmos_agent_sdk.transport`) — JSONL framing, request/response
  correlation by `id`, protocol-version handshake, and message routing. Spawns
  `auggie-v2 --mode rpc` (`SubprocessTransport`); a `FakeTransport` replays
  canned wire messages through the same code paths for tests/conformance. Single
  session per process (multi-session = a client-side process pool).
- **Protocol** (`cosmos_agent_sdk.protocol`) — typed command / response / event /
  extension-UI models mirroring the four JSON Schemas. Deep external structures
  are forwarded verbatim as permissive objects (see the spec's "Permissiveness
  policy").
- **Facade** (`cosmos_agent_sdk.client.AgentClient`) — the ergonomic API:
  `prompt`, `wait_for_idle` (idle = the `agent_end` event), the full typed
  command surface, and bidirectional extension-UI round-trips (reply-expecting
  methods are answered; fire-and-forget methods are not).

```python
from cosmos_agent_sdk import AgentClient, SubprocessTransport

transport = SubprocessTransport("auggie-v2")
transport.start()
with AgentClient(transport) as client:
    client.prompt("List the files in this repo")
    client.wait_for_idle()
    print(client.get_last_assistant_text()["data"]["text"])
```

## Toolchain

- [uv](https://docs.astral.sh/uv/) for environment management and building.
- [ruff](https://docs.astral.sh/ruff/) for lint / format.
- [mypy](https://mypy-lang.org/) for type-checking.
- [pytest](https://docs.pytest.org/) for the unit suite.

## Commands

```bash
uv sync --extra dev          # create a venv and install dev dependencies
uv run ruff check .          # lint
uv run ruff format .         # format
uv run mypy cosmos_agent_sdk # type-check
uv run pytest                # unit tests
uv build                     # build the sdist + wheel
```

## Conformance

The cross-client conformance runner is JavaScript. The Python client binds to it
through a thin JS shim, [`conformance-adapter.mjs`](./conformance-adapter.mjs),
that shells out to the real Python client
(`python -m cosmos_agent_sdk.conformance`) driven over an in-memory fake
transport replaying the fixture wire messages through the real
parsing / correlation / extension-UI code paths (v0 does not spawn a real
`auggie-v2` binary).

```bash
# from clients/python/ — requires the conformance deps installed once:
( cd ../../conformance && npm install )
uv sync --extra dev
make conformance             # or: node conformance-adapter.mjs
```

Exits non-zero if any of the 40 shared vectors fails.
