Python API

This page documents the Python API surface that is currently exported by the open-source khaos-agent SDK in this repository.

Install

Terminal
python3 -m pip install khaos-agent

python -c "import khaos; print(khaos.__version__)"

Top-Level Exports

The stable top-level package currently exposes agent decorators, registry helpers, output utilities, LLM telemetry hooks, and the testing framework.

Python
from khaos import (
    # Agent decorators and types
    khaosagent,
    khaos_agent,  # deprecated alias
    AgentConfig,
    AgentCategory,
    AgentTimeoutError,
    InvocationContext,
    StreamingResponse,
    AsyncStreamingResponse,
    ToolDefinition,
    get_current_context,

    # Registry/discovery helpers
    AgentMetadata,
    discover_agent_metadata,
    record_agent_run,
    list_local_agents,
    find_agent_record,

    # Output helpers
    extract_output_text,
    extract_input_text,
    normalize_agent_output,

    # LLM telemetry hooks
    emit_llm_call,
    observe_llm_call,

    # Testing framework
    khaostest,
    KhaosTestConfig,
    AgentTestClient,
    AgentResponse,

    # Runtime discovery toggle
    enable_runtime_discovery,
)

@khaosagent

Python
from khaos import khaosagent

@khaosagent(name="my-agent", version="1.0.0")
def handle(message: dict) -> dict:
    text = (message.get("payload") or {}).get("text", "")
    return {"payload": {"text": f"echo: {text}", "status": "ok"}}

See @khaosagent docs for supported decorator fields and framework patterns.

Testing API

khaos.testing currently exports the core testing primitives:khaostest, KhaosTestConfig, AgentTestClient, andAgentResponse.

Python
from khaos.testing import khaostest

@khaostest(agent="my-agent", tags=["smoke"])
def test_basic(agent):
    result = agent("What is 2+2?")
    assert result.success
    assert "4" in result.text

Run these with khaos test. See Testingfor the full workflow.

Configuration API

Python
from khaos.config import load_config, DEFAULT_CONFIG_PATH

cfg = load_config()
print(DEFAULT_CONFIG_PATH)
print(cfg)
Current Behavior
load_config() is a compatibility loader in the current stable release and currently returns an empty mapping. CLI behavior remains the source of truth for runtime settings.

Cost Utilities

Use khaos.costs to load rate tables and estimate cost from token counts.

Python
from khaos.costs import load_cost_table, estimate_cost_usd

rates = load_cost_table()

cost_usd, source = estimate_cost_usd(
    provider="openai",
    model="gpt-4o",
    prompt_tokens=1200,
    completion_tokens=300,
    table=rates,
)

print(cost_usd, source)  # e.g. 0.0123, "estimated"

Cloud Utilities

The stable cloud module exposes config/session helpers used by CLI sync flows.

Python
from khaos.cloud import (
    load_cloud_config,
    save_cloud_config,
    get_cloud_session,
    get_authenticated_client,
    validate_token,
    fetch_ingestion_status,
)

cfg = load_cloud_config()
session = get_cloud_session(cfg)
ok = validate_token(session.client, cfg)
print(ok)

Current Scope

Not in Stable Public API
High-level functions/classes such as run(), compare(),RunConfig, CompareConfig, khaos.runtime, andkhaos.scenarios are not part of the current stable public Python API in this repo. Use the CLI (khaos run, khaos ci, khaos compare) for those workflows.

Related Docs