Metadata-Version: 2.1
Name: arkna
Version: 3.2.0
Summary: Official Python SDK for the ARKNA AI Agent Observability platform
License: MIT
Keywords: arkna,ai-agents,agent-observability,incident-intelligence,agent-replay,black-box-recorder
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2; extra == "autogen"
Provides-Extra: crewai
Requires-Dist: crewai>=0.1; extra == "crewai"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1; extra == "langchain"
Provides-Extra: sse
Requires-Dist: sseclient-py>=1.7; extra == "sse"

# arkna

Official Python SDK for [ARKNA](https://arkna.com.au) — AI agent observability and incident intelligence.

ARKNA records every run, step, and tool call your AI agents make, with full context and hash-chained integrity. When something goes wrong, replay the exact run and see what the agent knew at each step.

## Installation

```bash
pip install arkna
```

With framework extras:

```bash
pip install arkna[langchain]    # LangChain integration
pip install arkna[crewai]       # CrewAI integration
pip install arkna[autogen]      # AutoGen integration
```

## Quick Start

### Auto-instrumentation (recommended)

Two lines. All OpenAI and Anthropic calls are captured automatically.

```python
from arkna import init

init(api_key="ark_live_...", agent_name="my-agent")

# Your existing code — no changes needed
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)
# ^ This call is automatically recorded by ARKNA
```

Or via environment variables (no code changes at all):

```bash
export ARKNA_API_KEY=ark_live_...
export ARKNA_AGENT_NAME=my-agent
```

```python
from arkna import init
init()
```

### Manual instrumentation

For full control over what gets recorded:

```python
from arkna import ArknaClient

client = ArknaClient(api_key="ark_live_...", agent_name="my-agent")

run = client.start_run(trigger_type="api", input={"query": "refund policy"})

client.record_step(run["run_id"],
    step_type="reasoning",
    input="User asked about refund policy",
    output="Found 3 relevant documents",
)

client.record_tool_call(run["run_id"],
    tool_name="search_docs",
    input={"query": "refund"},
    output={"results": 3},
    status="success",
)

client.complete_run(run["run_id"], status="completed")
```

## Framework Integrations

### LangChain

```python
from arkna import init, ArknaLangChainHandler

init(api_key="ark_live_...", agent_name="my-langchain-agent")
handler = ArknaLangChainHandler()

# Pass as callback to any LangChain chain/agent
result = chain.invoke({"input": "hello"}, config={"callbacks": [handler]})
```

### CrewAI

```python
from arkna import init, ArknaCrewAIHandler

init(api_key="ark_live_...", agent_name="my-crew")
handler = ArknaCrewAIHandler()
```

### AutoGen

```python
from arkna import init, ArknaAutoGenHandler

init(api_key="ark_live_...", agent_name="my-autogen-team")
handler = ArknaAutoGenHandler()
```

## Configuration

| Environment Variable | Description |
|---------------------|-------------|
| `ARKNA_API_KEY` | API key (`ark_live_...`) |
| `ARKNA_AGENT_NAME` | Agent name for identification |
| `ARKNA_BASE_URL` | API endpoint (default: `https://api.arkna.com.au`) |

## Requirements

- Python >= 3.9
- `requests >= 2.28`

## License

MIT
