ciphyrs 2.4.0

Official Ciphyrs SDK for Python — agent tracing, observability, and PII detection

Ciphyrs Python SDK

Official Python SDK for Ciphyrs -- agent tracing, observability, and PII detection.

Installation

pip install ciphyrs

With integrations:

pip install ciphyrs[openai]      # OpenAI auto-tracing
pip install ciphyrs[langchain]   # LangChain callback handler

Quick Start

Basic Tracing

import ciphyrs

# Initialize the SDK
client = ciphyrs.init(api_key="ck_your_key", project="my-project")

# Trace a pipeline with spans
with client.trace("research_pipeline") as t:
    t.trigger_input = "What is quantum computing?"

    with client.span("Researcher", kind="llm_call", model_name="gpt-4") as s:
        s.set_input("What is quantum computing?")
        result = "Quantum computing uses qubits..."
        s.set_output(result)
        s.set_tokens(prompt_tokens=50, completion_tokens=200)

    with client.span("Summarizer", kind="llm_call") as s:
        s.set_input(result)
        summary = "QC leverages quantum mechanics for computation."
        s.set_output(summary)

    t.final_output = summary

Decorator-Based Tracing

import ciphyrs

ciphyrs.init(api_key="ck_your_key", project="my-project")

@ciphyrs.trace(name="research_task")
def run_pipeline(query):
    result = research(query)
    return summarize(result)

@ciphyrs.span(agent_name="Researcher", kind="llm_call")
def research(query):
    return llm.complete(query)

@ciphyrs.span(agent_name="Summarizer", kind="llm_call")
def summarize(text):
    return llm.complete(f"Summarize: {text}")

run_pipeline("What is AI?")

OpenAI Auto-Tracing

import ciphyrs
from ciphyrs.integrations.openai import patch_openai
from openai import OpenAI

ciphyrs.init(api_key="ck_your_key", project="my-project")
patch_openai()

openai_client = OpenAI()

# All OpenAI calls inside a trace are automatically captured
with ciphyrs.get_client().trace("chat_pipeline"):
    response = openai_client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}]
    )

LangChain Integration

import ciphyrs
from ciphyrs.integrations.langchain import CiphyrsCallbackHandler

client = ciphyrs.init(api_key="ck_your_key", project="my-project")
handler = CiphyrsCallbackHandler(client=client, trace_name="langchain_run")

# Use with any LangChain chain
result = chain.invoke(
    {"input": "What is AI?"},
    config={"callbacks": [handler]}
)

handler.flush()  # Send the trace

Direct Ingestion

client = ciphyrs.CiphyrsClient(api_key="ck_your_key")

client.ingest(
    project={"name": "my-project", "framework": "custom"},
    trace={
        "trace_id": "abc-123",
        "name": "my-trace",
        "status": "completed",
    },
    spans=[
        {
            "span_id": "span-1",
            "agent_name": "MyAgent",
            "kind": "agent",
            "input": "hello",
            "output": "world",
            "duration_ms": 150,
            "status": "ok",
        }
    ],
)

Span Kinds

Kind	Description
agent	An autonomous agent step
llm_call	A call to an LLM (OpenAI, Anthropic, etc.)
tool_call	A tool/function invocation
retrieval	A vector DB or search query

Configuration

client = ciphyrs.CiphyrsClient(
    api_key="ck_your_key",
    base_url="https://api.ciphyrs.com",  # or self-hosted URL
    project="my-project",
    framework="langchain",
    max_buffer_size=10,    # flush after 10 traces
    flush_interval=30.0,   # auto-flush every 30 seconds
)

License

MIT