Metadata-Version: 2.2
Name: rosen-sdk
Version: 0.2.0
Summary: Rosen Python agent SDK
Author-email: Daniel Castanho <pypi@danielcastanho.com>
Project-URL: Homepage, https://codeberg.org/DanielCastanho/rosen
Project-URL: Repository, https://codeberg.org/DanielCastanho/rosen
Project-URL: Issues, https://codeberg.org/DanielCastanho/rosen/issues
Keywords: agents,llm,ai,kubernetes,mcp
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
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
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.40
Requires-Dist: mcp<2,>=1.27
Requires-Dist: redis>=5
Requires-Dist: faiss-cpu>=1.7
Requires-Dist: numpy>=1.25
Requires-Dist: psycopg[binary]>=3
Requires-Dist: pgvector>=0.2
Provides-Extra: dev
Requires-Dist: fakeredis>=2; extra == "dev"

# Rosen Python SDK

The Python SDK for [Rosen](https://codeberg.org/DanielCastanho/rosen), a
Kubernetes-style control plane for AI agents.

An agent is a function `handler(ctx) -> str`. The SDK gives that function a
model, tools, and memory, and handles the wire protocol so the Rosen control
plane can run it, either as a one-shot Job or a long-lived served Deployment.

## Install

```bash
pip install rosen-sdk
```

Every backend (OpenAI-compatible models, MCP tools, Redis, FAISS, pgvector) is
a required dependency, so there is nothing optional to pick.

## Write an agent

```python
import rosen

def handle(ctx: rosen.Context) -> str:
    return ctx.model.run(ctx.input)

if __name__ == "__main__":
    rosen.run(handle)
```

`ctx` carries everything the agent needs for one run:

- `ctx.input` is the request text.
- `ctx.model.run(prompt)` runs a tool-calling loop over the bound model.
- `ctx.tools` are the MCP tools the model can call.
- `ctx.memory` is conversational (Redis) and semantic (FAISS/pgvector) recall.
- `ctx.conversation_id`, `ctx.trace_id`, `ctx.agent`, `ctx.namespace`.
- `ctx.log(msg)` traces to stderr, since stdout is the result channel.

## Run modes

- `rosen.run(handle)` runs the agent once: it reads a JSON request, invokes the
  handler, and writes the result. The control plane uses this for one-shot Jobs.
- `rosen.serve(handle)` starts an HTTP server (`POST /invoke`) that answers many
  requests over one process, so memory and connections are built once. The
  control plane uses this for served Deployments with replicas.

The model, tools, and memory are configured with Rosen resources
(`ModelEndpoint`, `Tool`, `Memory`) and injected by the control plane. The agent
code is the same whether it runs as a Job or a served Deployment.

## License

AGPL-3.0-or-later. See [LICENSE](LICENSE).
