Metadata-Version: 2.4
Name: orkaia
Version: 0.3.0
Summary: Cost control for AI agents — loop detection, budget caps, audit trail
Project-URL: Homepage, https://orka.ia.br
Project-URL: Documentation, https://orka.ia.br/docs
Project-URL: Repository, https://github.com/mathhMadureira/orka
License: MIT
Keywords: agents,ai,audit,crewai,governance,langchain,monitoring,observability,openai
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Provides-Extra: all
Requires-Dist: langchain-core>=0.3.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: starlette>=0.38.0; extra == 'all'
Requires-Dist: uvicorn>=0.30.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: starlette>=0.38.0; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Provides-Extra: proxy
Requires-Dist: starlette>=0.38.0; extra == 'proxy'
Requires-Dist: uvicorn>=0.30.0; extra == 'proxy'
Description-Content-Type: text/markdown

# Orka

**Your AI agent burns money in a loop. Orka cuts it before the bill lands — and proves how much it saved.**

```bash
pip install orkaia
```

[![PyPI version](https://img.shields.io/pypi/v/orkaia.svg)](https://pypi.org/project/orkaia/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## What just happened

An OpenAI Operator agent bought a dozen eggs for $31 — its own safety protocol failed to trigger.
Replit's coding agent deleted a production database in 9 seconds, during a freeze meant to prevent exactly that.
A research agent burned $200 in a retry loop at 3am before anyone noticed.

There's no checkpoint between your agent's decision and the irreversible action. No cost cap. No loop detection. No audit trail.

**Orka sits in front of every action and decides: let it pass, flag it, or cut it.**

---

## Try it now — no API key, no signup

```python
import orka

orka.init(mode="local")  # no key, no network, runs offline

@orka.guard(agent_id="my-agent", task_type="web_search")
def search(query: str) -> str:
    return your_llm.call(query)

# Run your agent as usual...
for i in range(10):
    search(query="python tutorial")  # same query = loop detected

# See what Orka caught
orka.summary()
```

Output:
```
==================================================
  Orka Run Summary
==================================================
  Run:            a1b2c3d4...
  Actions:        10
  Interventions:  8
  Cost:           ~$0.0065
  Saved:          ~$0.0052
    [loop] web_search repeated 3+ times
==================================================
```

Your agent ran. Orka watched. You see exactly what it would have cut, and how much it would have saved. **Zero config, zero signup, zero network.**

Want it to actually cut? Add `enforce=True`:

```python
orka.init(mode="local", enforce=True)
# Now loops and budget overruns raise OrkaPolicyBlocked
```

---

## What Orka does

| Feature | What it does | How |
|---|---|---|
| **Loop guard** | Detects when your agent repeats the same action | Fingerprints tool+args, breaks at N repetitions |
| **Budget cap** | Stops a run before it blows past your cost limit | Configurable per-run USD ceiling |
| **Cost meter** | Tracks estimated spend per action | Token count × model price table |
| **Audit trail** | Records every action with cost, status, timestamps | Local SQLite or cloud ledger |
| **Savings report** | Shows exactly how much Orka prevented | `orka.summary()` or dashboard |
| **Human approval** | Pauses high-risk actions for human review | Cloud mode — approval flow in dashboard |
| **Policy engine** | Blocks actions by rule (task type, domain, quota) | Configurable policies per agent |

---

## Two modes

### Local (free, offline, no signup)

```python
orka.init(mode="local")                    # audit: observe only
orka.init(mode="local", enforce=True)      # enforce: actually cut
orka.init(mode="local", per_run_usd=2.0)   # budget cap at $2
orka.init(mode="local", loop_threshold=5)   # break after 5 repeats
```

Data stays in `~/.orka/local.db`. No network. No account.

### Cloud (team features, dashboard)

```python
orka.init(api_key="orka_...")  # get key at orka.ia.br
```

Adds: centralized ledger, team approval flows, cross-agent dashboard, org-level enforcement, real-time alerts.

---

## Works with any framework

### LangChain

```python
from orka.integrations.langchain import OrkaCallbackHandler

cb = OrkaCallbackHandler(agent_id="my-agent")
llm = ChatOpenAI(model="gpt-4o", callbacks=[cb])
```

### CrewAI / AutoGen / custom

```python
@orka.guard(agent_id="researcher", task_type="web_search")
def search_web(query: str) -> str:
    return firecrawl.scrape(query)
```

Works with `def` and `async def` — detected automatically.

---

## Handle blocks

```python
from orka import OrkaPolicyBlocked

@orka.guard(agent_id="agent", task_type="send_email", risk="HIGH")
def send_email(to: str, body: str) -> bool:
    return email_client.send(to, body)

try:
    send_email("user@example.com", "Report ready")
except OrkaPolicyBlocked as e:
    print(f"Blocked: {e.reason}")
    # In cloud mode: queued for human approval in dashboard
```

---

## Install

```bash
pip install orkaia                  # core
pip install "orkaia[langchain]"     # + LangChain callback
pip install "orkaia[openai]"        # + OpenAI adapter
```

Python 3.10+.

---

## Examples

| Demo | What it shows |
|------|---------------|
| [`local_audit_demo/`](examples/local_audit_demo/) | Agent in loop → Orka detects → shows savings (no key) |
| [`economy_loop_demo/`](examples/economy_loop_demo/) | Loop cut + dollar savings report |
| [`quickstart.py`](examples/quickstart.py) | Cloud mode in 30 lines |

---

## Links

- **Dashboard**: [orka.ia.br](https://orka.ia.br)
- **GitHub**: [github.com/mathhMadureira/orka](https://github.com/mathhMadureira/orka)
- **Contact**: contato@orka.ia.br

MIT License
