Metadata-Version: 2.5
Name: ghemud-agentkit
Version: 0.1.0
Summary: A secure, provider-agnostic Python runtime for AI agent tool execution with policies, budgets, approvals, and audit trails.
Project-URL: Homepage, https://github.com/yashraj-ghemud/ghemud-agentkit
Project-URL: Documentation, https://github.com/yashraj-ghemud/ghemud-agentkit/tree/main/docs
Project-URL: Changelog, https://github.com/yashraj-ghemud/ghemud-agentkit/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/yashraj-ghemud/ghemud-agentkit/issues
Project-URL: Source, https://github.com/yashraj-ghemud/ghemud-agentkit
Author: Yashraj Sachin Ghemud
Maintainer: Yashraj Sachin Ghemud
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent runtime,agent security,agentic ai,ai agents,artificial intelligence,llm tools,model context protocol,python ai framework,secure tool calling,tool orchestration
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: jsonschema>=4.19; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pydantic>=2.5; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Provides-Extra: jsonschema
Requires-Dist: jsonschema>=4.19; extra == 'jsonschema'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: openai
Requires-Dist: openai>=1.30; extra == 'openai'
Provides-Extra: pydantic
Requires-Dist: pydantic>=2.5; extra == 'pydantic'
Description-Content-Type: text/markdown

# 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.

```python
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

| Without a runtime boundary | With Ghemud AgentKit |
|---|---|
| Model output trusted as function calls | Model output validated against JSON Schema with size/depth limits |
| "The agent has access to everything" | Capability-based permissions: allow / deny / human-approval, evaluated **before** side effects |
| Unbounded tool loops | Time, cost, and tool-call budgets with atomic reservation |
| Secrets sprayed through logs | Mandatory redaction in every event, audit record, and model-visible result |
| No answer to "who approved what, when" | Hash-chained (optionally HMAC-signed) audit trail |
| Untestable without a provider API key | Deterministic fake models; zero network in the entire test suite |

## The 30-second tour

```python
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

```bash
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](docs/quickstart.md) — deterministic local tools in 5 minutes
- [Agent loop tutorial](docs/agent-loop.md) — budgets, parallel calls, stop conditions
- [Security model](docs/security.md) — trust boundaries and the permission system
- [Permission policy guide](docs/policies.md) — rules, tiers, composition
- [Provider adapters](docs/providers.md) — fake models, OpenAI, writing your own
- [Testing guide](docs/testing.md) — deterministic agent tests without network
- [What Ghemud AgentKit does NOT guarantee](docs/security.md#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](CITATION.cff) when citing this software, review [CREDITS.md](CREDITS.md) for project attribution, and see [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [SECURITY.md](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.*
