Metadata-Version: 2.5
Name: ciphyrs
Version: 3.5.0
Summary: Ciphyrs SDK: AI-agent observability and tool-call enforcement, built on OpenTelemetry
Project-URL: Homepage, https://www.ciphyrs.com
Project-URL: Documentation, https://www.ciphyrs.com/docs
Project-URL: Repository, https://github.com/praveen190/Ciphyrs
Project-URL: Changelog, https://github.com/praveen190/Ciphyrs/releases
Author-email: Ciphyrs <support@ciphyrs.com>
License-Expression: MIT
Keywords: ai-agents,ciphyrs,guardrails,observability,opentelemetry,pii
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Python :: Free Threading :: 3 - Stable
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0
Requires-Dist: opentelemetry-sdk>=1.20.0
Provides-Extra: opentelemetry
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'opentelemetry'
Description-Content-Type: text/markdown

# Ciphyrs — observability for AI agents

[![PyPI](https://img.shields.io/pypi/v/ciphyrs)](https://pypi.org/project/ciphyrs/)
[![Python](https://img.shields.io/pypi/pyversions/ciphyrs)](https://pypi.org/project/ciphyrs/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

See every agent, tool call and model call your application makes, as one
connected graph. Built on OpenTelemetry, so the spans are standard OTLP and
sit beside whatever tracing you already have — and your model calls stay
yours, made directly against your provider.

## Install

```bash
pip install ciphyrs
```

One command. OpenTelemetry and `httpx` come with it. **Python 3.9 through
3.14**, including the free-threaded 3.14 build (PEP 703).

No framework-specific install, and none exists. `@agent` and `@tool` wrap
plain **functions**, so they work with any agent framework, or none.

## Monitor your agents

```python
import ciphyrs

ciphyrs.init(api_key="cyp_live_...", project="customer-support")

@ciphyrs.tool
def issue_refund(order: str, amount: float) -> dict:
    return payments.refund(order, amount)   # traced, and checked against policy

@ciphyrs.agent("BillingAgent", role="worker")
def billing(question: str) -> str:
    answer = my_model.generate(question)      # your model call, unchanged
    issue_refund(order="A-1041", amount=12.0)
    return answer

@ciphyrs.agent("RouterAgent", role="router")
def router(message: str) -> str:
    return billing(message)      # called INSIDE router -> a RouterAgent→BillingAgent edge

with ciphyrs.session("conv-7f3a"):            # ties one conversation together
    router("I was charged twice for order A-1041")

ciphyrs.shutdown()                            # flush; short-lived scripts only
```

That is the whole integration. Nesting **is** the topology: because `billing`
was called inside `router`, the dashboard draws the edge. Both agents appear
in the fleet at start-up — decorators register themselves, before any traffic.

| | |
|---|---|
| `init()` | Configures an OTLP exporter to Ciphyrs, or attaches to a `TracerProvider` you already have and leaves your exporters alone. Falls back to `CIPHYRS_API_KEY`, `CIPHYRS_PROJECT`, `CIPHYRS_BASE_URL`. |
| `@agent` | One span per call, named for the agent. Everything it calls nests underneath. |
| `@tool` | One span per tool call, with arguments and result. Also checked against policy before it runs — `enforce` inherits `init(enforce=True)`, so a `block` verdict raises `ToolBlocked` and the function never executes. Pass `enforce=False` to trace only. |
| `session()` | Tags every span inside with `session.id`. |
| `init(agents=...)` | Declares the roster and the designed peer graph at boot, so the fleet is complete before the first request. Starts a heartbeat (default 60 s) so idle and dead are distinguishable. |

Async is automatic — declare the function `async def` and the decorators
install async wrappers. Every platform call they make runs off your event
loop.

### See the inputs and outputs

On by default. Pass `capture_io=False` to an individual `@agent` or `@tool`
whose arguments must not be recorded; its spans still carry timing, nesting
and errors.

### Agents in separate processes

Already on. Outgoing HTTP requests carry the trace context, so an agent that
calls another service shows up as one connected graph rather than two
disconnected fleets. `init(propagate=False)` turns it off.

### Model and framework internals

Ciphyrs is not in the path of your model call and does not want to be. For
spans *inside* a framework or provider — retriever calls, per-node detail —
add that framework's own OpenTelemetry instrumentation (OpenInference or
OpenLLMetry). Its spans travel through the exporter `init()` already installed
and nest inside your agent spans.

### Is it actually on?

```python
state = ciphyrs.selfcheck()
if state["problems"]:
    log.error("Ciphyrs is not live in this process: %s", state["problems"])
```

Reports what is genuinely running and names each problem in words. Makes no
network call, so it is safe in a readiness probe.

## Beyond tracing

The platform also enforces policy on agent messages, masks PII, and can
quarantine a misbehaving agent from the dashboard. **Tool checks, message
checks and PII masking are all on by default** once `init()` has an API key,
which means text leaves your process to be evaluated. The documentation says
what each one sends and how to turn it off (`enforce=`, `guard_input=`,
`guard_output=`, `pii=`).

- [Documentation](https://www.ciphyrs.com/docs)
- [Website](https://www.ciphyrs.com)
- [Dashboard](https://www.ciphyrs.com/dashboard)
