orkaia 0.3.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.

pip install orkaia

---

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

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:

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)

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)

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

from orka.integrations.langchain import OrkaCallbackHandler

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

CrewAI / AutoGen / custom

@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

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("[e-mail]", "Report ready")
except OrkaPolicyBlocked as e:
    print(f"Blocked: {e.reason}")
    # In cloud mode: queued for human approval in dashboard

---

Install

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/	Agent in loop → Orka detects → shows savings (no key)
economy_loop_demo/	Loop cut + dollar savings report
quickstart.py	Cloud mode in 30 lines

---

Links

• Dashboard: orka.ia.br
• GitHub: github.com/mathhMadureira/orka
• Contact: [e-mail]

MIT License