Metadata-Version: 2.4
Name: ciphyrs
Version: 2.2.0
Summary: Official Ciphyrs SDK for Python — agent tracing, observability, and PII detection
Home-page: https://github.com/ciphyrs/ciphyrs-python
Author: Ciphyrs
Author-email: sdk@ciphyrs.com
Classifier: Development Status :: 3 - Alpha
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: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: langchain
Requires-Dist: langchain>=0.1.0; extra == "langchain"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Ciphyrs Python SDK

Official Python SDK for [Ciphyrs](https://ciphyrs.com) -- agent tracing, observability, and PII detection.

## Installation

```bash
pip install ciphyrs
```

With integrations:
```bash
pip install ciphyrs[openai]      # OpenAI auto-tracing
pip install ciphyrs[langchain]   # LangChain callback handler
```

## Quick Start

### Basic Tracing

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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
