Skip to main content

CoSens Python SDK

CoSens records the tasks your application runs through an OpenAI client or an OpenAI Agents agent, and turns a confirmed result into a reusable Recipe.

Install

pip install cosens-sdk

For OpenAI Agents support: pip install 'cosens-sdk[agents]'. Requires Python 3.10+.

Configure

Variable Read by Value
COSENS_API_KEY SDK and your model client Your CoSens API Key
COSENS_REGION SDK us (default and only supported value)
COSENS_MODEL_BASE_URL Your model client https://llm.cosens.ai/v1

The SDK reads the process environment; load any .env file in your application. The model IDs you can use are listed in the CoSens documentation.

Wrap an OpenAI client

Build a standard OpenAI client for your model gateway and pass it to cosens(...):

import os

from openai import OpenAI
from cosens import cosens

model_client = OpenAI(base_url=os.environ["COSENS_MODEL_BASE_URL"], api_key=os.environ["COSENS_API_KEY"])
client = cosens(model_client, mode="auto")
result = client.responses.create(model="<public-model-id>", input="Produce a report")
turn_id = client.cosens.last_turn_id

The response is the native OpenAI result. AsyncOpenAI works the same way and exposes async CoSens calls.

In auto mode the SDK first makes a short structured decision call through your client (Chat Completions with a JSON schema response_format), so the model must support structured output. The model writes only {"activate": ..., "reason": ...}; the task objective is your user's text. The call is made once, without retries, with a 5-second timeout and a 1024-token output budget (reasoning included). If the decision or the read-only Recipe lookup fails or times out, your request still runs without CoSens capture, and the turn records why: client.cosens.get_turn(client.cosens.last_turn_id) has capture == "decision_failed" with decision["error_type"] and decision["error"] (for example a timeout, a gateway error, or output cut off at the token limit). A request without user text is skipped without a model call (capture == "no_user_text").

Option Default Effect
decision_timeout 5 Seconds allowed for the decision and Recipe-match calls
decision_max_output_tokens 1024 Output budget, reasoning included, for the decision and Recipe-match calls
decision_client the wrapped client Separate OpenAI / AsyncOpenAI client (matching the wrapped one) for those calls, e.g. a small fast model
decision_extra_body none Extra request body for those calls, e.g. {"enable_thinking": False}
max_context_chars 4000 Upper bound for the Recipe/Memory text added to a request or Agent instructions

Both models above reason before answering, which is why the budget is not smaller. Reasoning models that think longer can still hit the timeout or the token budget; the turn then records decision_failed with the cause. Use a small non-reasoning decision_model (or a separate decision_client), raise decision_timeout / decision_max_output_tokens, or switch reasoning off with decision_extra_body if your gateway accepts such a field (vLLM accepts {"chat_template_kwargs": {"enable_thinking": False}}; the LiteLLM gateway above rejects it with HTTP 500, which also records decision_failed).

Measured on 2026-11-06 with the SDK's own decision request (output tokens include reasoning):

Model (gateway) Decision tokens p50 / max With linked feedback, max Success at defaults Decision latency p50 / max
deepseek-flash (llm.cosens.ai) 50 / 139 294 24 / 24 1.6 s / 3.7 s
qwen3.8-27b (vLLM via LiteLLM) 189 / 469 337 23 / 24 (one 5 s timeout) 1.6 s / 5.0 s

The default budget leaves more than 3x headroom over the largest reply measured on the default model.

If the decision activates, a Recipe-match call picks a usable Recipe with the same limits. A match that times out or is cut off does not stop the capture: the turn is recorded without a Recipe and turn["recipe_match_error"] says why. With 20 usable Recipes, deepseek-flash matched within 5 s in 9 of 12 measured calls.

client = cosens(model_client, mode="auto", decision_model="<small-non-reasoning-model-id>")

When a usable Recipe matches, the SDK adds it as plain text: its title, when/when-not, numbered steps, related Memory text and, if room remains, lesson actions. The block never exceeds max_context_chars; a final line states what was omitted. A list with no usable Recipe is remembered for 60 seconds, so routine requests skip the lookup.

Generate a Recipe after confirmation

Check that the turn has a submitted Revision before offering Recipe generation. After your application obtains user confirmation of that artifact, call from its confirmation handler:

turn = client.cosens.get_turn(turn_id) if turn_id else None
if turn and turn.get("revision_id"):
    receipt = client.cosens.generate_recipe(turn_id, request_key="confirmed-report-1")

This is the only generation action. It creates the first Recipe version or updates the associated Recipe, always reads relevant Memory, and performs feedback attribution internally. feedback records feedback; it does not update a Recipe.

client.cosens.wait_learning(turn_id) raises cosens.RSICandidateFailed when generation fails. The error has code, phase, retryable, upstream_status, upstream_code, candidate_id and request_id. When retryable is true, client.cosens.resume_learning(turn_id) retries the same candidate. Older servers report only code; retryable is then None.

Run an OpenAI Agents agent

import os

from agents import Agent, set_default_openai_client
from openai import AsyncOpenAI
from cosens import cosens

set_default_openai_client(AsyncOpenAI(base_url=os.environ["COSENS_MODEL_BASE_URL"], api_key=os.environ["COSENS_API_KEY"]))
agent = Agent(name="assistant", instructions="Complete the requested task.", model="<public-model-id>")
client = cosens(agent, mode="auto")
result = await client.run(agent, "Produce a report")

Run RSI locally

Local RSI keeps Tasks, traces, feedback and Recipe versions on your machine and generates Recipes with your own model quota. CoSens is used only as Memory; pass memory=None to run without it. Python only for now.

pip install 'cosens-sdk[local]'
from openai import AsyncOpenAI
from cosens import CoSensClient
from cosens.local import ChatCompletionsModel, CodexCLIModel, LocalRSI

rsi = LocalRSI(memory=CoSensClient(), model=ChatCompletionsModel(AsyncOpenAI(base_url=..., api_key=...), "model-id"))
# Or use your Codex login: LocalRSI(memory=CoSensClient(), model=CodexCLIModel())

LocalRSI has the workflow methods of client.atoms. Generation runs inside wait_workflow_job, so always wait for a candidate. See examples/04_local_rsi.py.

Atomic operations

CoSensClient().atoms (async) and .sync_atoms (sync) expose Task, Execution, Revision, feedback, Recipe, Session and Memory operations directly. Keep stable idempotency keys across retries.

  • Returned JSON objects are dicts with a request_id attribute holding the response's x-request-id, for support requests.
  • start_recipe_candidate(task_id, revision_id=...) may omit key; the default is derived from the task, revision and max_completion_tokens, so repeating the call returns the same candidate.
  • wait_workflow_job("recipe_candidate", id) raises RSICandidateFailed when the candidate failed.

More

Metadata

Release files for cosens-sdk 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cosens-sdk 0.6.0
File Size Uploaded Provenance Actions
cosens_sdk-0.6.0.tar.gz 73.1 kB With provenance Details for cosens_sdk-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cosens-sdk 0.6.0
File Interpreter ABI Platform Actions
cosens_sdk-0.6.0-py3-none-any.whl Python 3 none any Details for cosens_sdk-0.6.0-py3-none-any.whl

Total release size: 159.8 kB

Release files / cosens_sdk-0.6.0.tar.gz

Download URL cosens_sdk-0.6.0.tar.gz
Size 73.1 kB
Tags Source
SHA-256 checksum
How to use checksums
811f32d1484d31da88e2363665647a9c253637d4f364434548b3f18594e9e11d
BLAKE2b-256 checksum
How to use checksums
2a6b12e3c645c0fde33e4c50ec3480a8e57e02f077874af3f156ed057878def1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / cosens_sdk-0.6.0-py3-none-any.whl

Download URL cosens_sdk-0.6.0-py3-none-any.whl
Size 86.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e65a33a77264aff03286b88f7be9e1250c67fe8b1a6aa55a73d86789f7fe91be
BLAKE2b-256 checksum
How to use checksums
650986260c9547152ec264148fcd688935537ce72b4e8b90824b972ffab1909e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for cosens-sdk 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cosens_sdk-0.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page