Configure the cost guard budget.

Args: weekly_budget_usd: Maximum spend per week in USD. alert_at_pct: Warn when spend reaches this percentage (0.0-1.0). dry_run: If true, all calls raise BudgetExceededError (safe for testing).

Check current budget spend — how much is left, percentage used, call details.

Pre-check if a model call is within budget. Returns safe/blocked status.

Args: model: Model identifier (e.g. "anthropic/claude-haiku-4-5-20251001", "openai/gpt-4o"). estimated_input_tokens: Expected input token count. estimated_output_tokens: Expected output token count.

Record a completed LLM call's token usage and cost.

Args: model: Model identifier used for the call. input_tokens: Actual input tokens consumed. output_tokens: Actual output tokens consumed. purpose: Optional label for this call (e.g. "summarizer", "classifier").

List all supported models with their per-token pricing.

Scan text for prompt injection patterns. Returns risk assessment without blocking.

Args: text: The text to scan for injection attempts. threshold: Sensitivity level — "LOW", "MEDIUM", "HIGH", or "CRITICAL".

Scan text and block if injection is detected above threshold.

Args: text: The text to check for injection attempts. threshold: Block at this severity or above — "LOW", "MEDIUM", "HIGH", "CRITICAL".

List all built-in injection detection patterns with categories and weights.

Start a new trace session for an AI agent.

Args: agent: Agent name (used in filenames). trace_dir: Directory to save trace files. model: Optional model name to attach as metadata.

Log a decision step in the current trace session.

Args: name: Step name (e.g. "analyze_signal", "classify_intent"). decision: What the agent decided. confidence: Confidence score (0.0-1.0). input_data: What the agent saw (brief description). reason: Why this decision was made. outcome: "ok" or "error".

Get a summary of the current trace session — step count, errors, timing.

Save the current trace to disk as JSON and Markdown files.

Generate an Ed25519 keypair for signing agent identity cards.

Args: name: Key name (default "mcp-session"). Keys stored at ~/.kya/keys/

Create a KYA (Know Your Agent) identity card for an agent.

Args: agent_id: Unique ID in format "org/agent-name" (e.g. "luciferforge/research-bot"). name: Human-readable agent name. purpose: What this agent does (min 10 chars for validity). capabilities: Comma-separated list of capabilities (e.g. "text_generation,web_search"). owner_name: Owner/organization name. version: Agent version string.

Sign an existing KYA card with the session's Ed25519 private key.

Args: agent_id: The agent_id of the card to sign. Must call kya_create_card first.

Verify a KYA identity card — check structure, completeness, and signature.

Args: agent_id: Look up a card created in this session by agent_id. card_json: Or pass raw card JSON to verify an external card.

Run a unified safety check: injection scan + cost check + trace step.

This is the recommended single tool for pre-flight safety. It runs injection scanning, checks the cost budget, and logs the decision.

Args: text: The input text to scan for injections. model: Model identifier for cost checking (optional). estimated_input_tokens: Expected input tokens for cost check. estimated_output_tokens: Expected output tokens for cost check. step_name: Name for the trace step.