Rosen Python SDK

The Python SDK for 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

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

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.

Explicit memory writes require the exported mode enum; scope only partitions records within the selected store:

ctx.memory.remember(
    "tenant-specific recovery procedure",
    scope="tenant-a",
    mode=rosen.MemoryMode.SEMANTIC,
)

ctx.model.run(...) selects MemoryMode.CONVERSATIONAL automatically when it persists conversation turns.

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.