Ghemud AgentKit

A secure, provider-agnostic runtime for AI agents to discover and execute tools — with explicit permissions, budgets, retries, approvals, and a tamper-evident audit trail.

Created and maintained by Yashraj Sachin Ghemud, Ghemud AgentKit is the runtime boundary between an AI agent decision and a real-world side effect. It validates model output as untrusted input, checks capabilities before execution, and records an observable, bounded, auditable invocation lifecycle.

Built for Python developers who need secure AI-agent tool execution. Ghemud AgentKit brings permissions, approvals, budgets, retries, redaction, and auditability into a provider-agnostic runtime.

from ghemud_agentkit import ToolRegistry, ToolRuntime, tool

@tool(description="Add two integers")
def add(a: int, b: int) -> int:
    """Add a and b."""
    return a + b

registry = ToolRegistry()
registry.register(add)
runtime = ToolRuntime(registry)   # conservative defaults

result = await runtime.run("add", {"a": 2, "b": 3})
assert result.content == 5

Why Ghemud AgentKit

The 30-second tour

import asyncio
from ghemud_agentkit import (
    AgentLoop, LoopConfig, ScriptedModel,
    ToolRegistry, ToolRuntime, tool,
)
from ghemud_agentkit.models import tool_call, text_response

registry = ToolRegistry()
# ... register tools ...

runtime = ToolRuntime(registry)

# Deterministic loop with a scripted model (no API key, no network):
model = ScriptedModel([
    tool_call("add", {"a": 19, "b": 23}),   # 1) model calls a tool
    text_response("19 + 23 = 42"),           # 2) model answers
])
loop = AgentLoop(model, runtime, config=LoopConfig(max_iterations=5))
result = asyncio.run(loop.run("what is 19+23?"))
print(result.final_text)          # -> "19 + 23 = 42"
print(result.stop_reason)         # -> StopReason.COMPLETED

Swap ScriptedModel for the OpenAI adapter (pip install "ghemud-agentkit[openai]") and the same loop, policies, budgets, and audit trail run against a real provider.

What's in the box

• Tool API — @tool decorator with schema inference from type hints (dataclasses, pydantic, Literal, enums, containers); sync and async tools; injected ctx: ToolContext for cancellation, state, and deadlines.
• Registries — namespaced, composite (first-match-wins with conflict detection), immutable snapshots, capability discovery.
• Invocation lifecycle — validated state machine (requested → validated → authorized → [approval] → queued → running → terminal) with structured events at every transition under one stable invocation ID.
• Permissions — capability-based policies with deny > approval > allow precedence, risk tiers, and a conservative DefaultPolicy.
• Human approval — TTL'd approval requests and TTL'd decisions; auto-deny for non-interactive environments; pluggable providers (console, callback, static).
• Resilience — bounded exponential backoff with jitter; retries only for idempotent/retryable tools; failure classification (validation/policy/approval/timeout/transient/application/…).
• Budgets — time, cost, and tool-call ceilings with atomic reserve/commit/release; budget state never leaks into error messages.
• Observability — typed event bus, in-memory collectors, mandatory secret redaction, debug events opt-in.
• Audit — hash-chained records (args digested from the redacted view), optional HMAC signing, JSONL file sink, chain verification API.
• Agent loop — model ↔ tools alternation with parallel tool calls, deterministic ordering, and eight explicit stop conditions.
• CLI — list, inspect, validate-policy, run --dry-run, trace.
• Interop — MCP adapter (optional extra); discovery schemas are byte-identical to enforcement schemas.

Installation

pip install ghemud-agentkit            # core, zero required dependencies
pip install "ghemud-agentkit[openai]"  # + OpenAI adapter
pip install "ghemud-agentkit[mcp]"     # + MCP interop

Python 3.10+ · Apache-2.0.

Documentation

• Quick start — deterministic local tools in 5 minutes
• Agent loop tutorial — budgets, parallel calls, stop conditions
• Security model — trust boundaries and the permission system
• Permission policy guide — rules, tiers, composition
• Provider adapters — fake models, OpenAI, writing your own
• Testing guide — deterministic agent tests without network
• What Ghemud AgentKit does NOT guarantee — read this before production

Compatibility policy

Semantic versioning. The public API is from ghemud_agentkit import ... plus stable submodules; anything documented in this README is covered. Internals (underscore-prefixed modules and names) may change at any patch release.

Author, citation, and contribution

Ghemud AgentKit was created by Yashraj Sachin Ghemud. Use the metadata in CITATION.cff when citing this software, review CREDITS.md for project attribution, and see CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md before participating or reporting a vulnerability.

Ghemud AgentKit treats model output as adversarial input even when the application trusts the model. If you remember one thing about this library, remember that.