orkaia 0.4.0

Cost control for AI agents — loop detection, budget caps, audit trail

Orka

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

---

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.

---

Installation

One-line (Linux / macOS)

curl -fsSL https://orka.ia.br/install.sh | bash

Windows (PowerShell)

irm https://orka.ia.br/install.ps1 | iex

Homebrew (macOS / Linux)

brew tap mathhMadureira/orka https://github.com/mathhMadureira/orka
brew install mathhMadureira/orka/orka

Winget (Windows)

winget install Orka.Orka

pip (Python SDK)

pip install orkaia
# with proxy support:
pip install "orkaia[proxy]"
# everything:
pip install "orkaia[all]"

npm (TypeScript / Node.js SDK)

npm install orkaia-js

Docker

docker run --rm -it ghcr.io/mathhmadureira/orka:latest orka version

---

Quick start — no API key, no signup

import orka

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

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

# Same query repeated = loop detected
for i in range(10):
    search(query="python tutorial")

# See what Orka caught
orka.summary()

Output:

==================================================
  Orka Run Summary
==================================================
  Actions:       10
  Interventions: 1
  Cost:          ~$0.0230
  Saved:         ~$0.1610   ← 7× your cost
==================================================
  [loop_guard] Identical action repeated 3× — halted
==================================================

---

CLI

orka <command> [options]

Commands:
  init          Interactive first-time setup
  login         Save an API key to local config
  config        Read or write config values
  doctor        Diagnose environment and connectivity
  version       Show installed version
  update        Upgrade to the latest version
  wrap          Run any process wrapped by the Orka proxy
  report        Show local audit report
  mcp           Start the MCP stdio server
  run           Run an agent action via Orka cloud API

Examples

# First time setup
orka init

# Save API key
orka login

# Wrap any LLM process — intercepts OpenAI/Anthropic calls automatically
orka wrap --budget 2.00 --enforce -- python my_agent.py

# View audit report
orka report

# Check for updates
orka version --check
orka update

# Diagnose your environment
orka doctor

---

Wrap mode (proxy interceptor)

orka wrap starts a local HTTP proxy that intercepts OpenAI-compatible and Anthropic API calls made by any subprocess. No code changes needed.

orka wrap \
  --budget 5.00 \
  --loop-threshold 3 \
  --enforce \
  -- python agent.py

Flag	Default	Description
--budget	5.00	Max spend in USD per run
--loop-threshold	3	Halt after N identical consecutive actions
--enforce	off	Block (not just observe) when limits exceeded
--upstream	OpenAI	Upstream provider URL

---

Python SDK — decorator pattern

import orka

# Cloud mode (full governance + audit)
client = orka.init(api_key="orka_...")

@orka.guard(agent_id="summarizer-v1", task_type="summarize")
def summarize(text: str) -> str:
    return openai_client.chat(text)

result = summarize("long article...")

Python SDK — economy module

import orka

economy = orka.economy(
    per_run_usd=2.00,        # hard budget per run
    loop_threshold=3,        # stop after 3 identical actions
    on_exceed="pause",       # "pause" | "block"
)

with economy.run():
    agent.run(task)

print(economy.summary())

TypeScript SDK

import orka from "orkaia-js";

const client = orka.init("orka_YOUR_KEY");

const summarize = orka.guard(
  async (text: string) => openai.chat(text),
  { agentId: "summarizer", taskType: "summarize" }
);

await summarize("long article...");

---

Local mode vs Cloud mode

Feature	Local (free, offline)	Cloud
Loop detection	✓	✓
Budget caps	✓	✓
Audit trail	SQLite ~/.orka/local.db	PostgreSQL
Human approvals	—	✓
Multi-agent	—	✓
Policy enforcement	—	✓
Team dashboard	—	✓
Retention	Local disk	7–14 days

---

MCP server

# Add to your MCP client config (Claude, Cursor, etc.)
orka mcp

Exposes read-only tools: list_actions, list_interventions, get_summary.

---

Building from source

git clone https://github.com/mathhMadureira/orka
cd orka/sdk/python

pip install -e ".[dev]"
pytest tests/ -v

# Build standalone binary
pip install pyinstaller
pyinstaller orka.spec
./dist/orka version

---

Contributing

git clone https://github.com/mathhMadureira/orka
cd orka/sdk/python
pip install -e ".[dev]"

# Lint
ruff check orka/

# Type check
mypy orka/ --ignore-missing-imports

# Tests
pytest tests/ -v

---

Releases

Releases are triggered by pushing a version tag:

git tag v1.0.0
git push origin v1.0.0

This automatically:

1. Runs all tests (Python 3.10, 3.11, 3.12 + TypeScript)
2. Builds binaries for Windows x64, Linux x64, Linux ARM64, macOS Intel, macOS Apple Silicon
3. Creates a GitHub Release with all binaries attached
4. Publishes orkaia to PyPI
5. Publishes orkaia-js to npm
6. Updates the Homebrew formula

---

License

MIT — see LICENSE

---

orka.ia.br · Docs · Issues