ghemud-agentkit 0.1.0__tar.gz

ghemud_agentkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src tests examples
+      - run: ruff format --check src tests examples
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: mypy src/ghemud_agentkit
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q --cov=ghemud_agentkit --cov-report=term-missing
+      - run: pytest -m security -q   # explicit adversarial gate
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

ghemud_agentkit-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish-testpypi:
+    runs-on: ubuntu-latest
+    environment: testpypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - run: twine upload --repository testpypi dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.TESTPYPI_TOKEN }}
+
+  publish-pypi:
+    runs-on: ubuntu-latest
+    needs: publish-testpypi
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - run: twine upload dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}

ghemud_agentkit-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+*.log

ghemud_agentkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to Ghemud AgentKit are documented in this file. The project follows semantic versioning.
+
+## 0.1.0 (2026-08-23)
+
+First public release by **Yashraj Sachin Ghemud**.
+
+### Core
+- `@tool` decorator + class-based Tool API with schema inference from type
+  hints (primitives, Literal/Enum, containers, dataclasses, optional pydantic);
+  fail-closed on unsupported annotations.
+- Deterministic JSON Schema generation with canonical serialization and
+  schema digests (discovery == enforcement, provable).
+- Built-in zero-dependency argument validator: closed schemas, size/depth/
+  item/string limits, NaN/Infinity rejection, JSON-pointer error paths.
+- Registry: namespaced, composite (first-match + conflict detection),
+  immutable snapshots, capability discovery, risk-filtered discovery docs.
+- Invocation lifecycle state machine with validated transitions and
+  structured events under stable, time-sortable invocation IDs.
+
+### Security
+- Capability-based permission policies (allow/deny/approval, risk tiers,
+  most-restrictive-wins composition, JSON policy files + CLI validation).
+- Human approval flow with TTL'd requests AND TTL'd decisions; auto-deny
+  for non-interactive runtimes; provider interface (console/callback/static).
+- Mandatory emission-time secret redaction (name heuristics + declarations +
+  value-shape scanning) across events, audit, results, and error messages.
+- Tamper-evident hash-chained audit trail with optional HMAC signing,
+  JSONL file sink, and chain verification.
+- Security test suite: prompt-injection args, type confusion, path traversal
+  (incl. symlink), command injection, secret exfiltration, oversized
+  payloads, budget bypass, retry-resurrection of denied calls.
+- PathGuard jail, safe AST math evaluator, secret-shape result scanning.
+- Sandbox boundary: `SandboxExecutor` interface + `SubprocessSandboxExecutor`
+  (hard timeout kills, process-group kill) with documented trust boundary.
+
+### Runtime
+- Full pipeline: lookup → validate → authorize → middleware → approve →
+  reserve → execute → normalize → audit.
+- Bounded exponential backoff with full jitter; retries only for
+  idempotent/retryable tools; failure classification.
+- Time/cost/tool-call budgets with atomic reserve/commit/release.
+- Per-tool + global concurrency limits; token-bucket rate limits.
+- Graceful shutdown with drain reporting (nothing silently abandoned).
+- Middleware hooks (before/after, onion ordering, veto → denial flow).
+
+### Agents
+- Provider-neutral model interface; deterministic Scripted/Static/Flaky
+  fake models; OpenAI adapter (optional extra).
+- Agent loop: parallel tool calls, deterministic result ordering, eight
+  explicit stop conditions, cancellation racing model calls.
+- Streaming tool results as an extension (async iterators aggregate for
+  non-streaming consumers; `run_stream` for streaming consumers).
+
+### Tooling
+- CLI: list / inspect / validate-policy / run (+ --dry-run) / trace / replay
+  / doctor. `run` always applies the full pipeline.
+- MCP interop adapter (optional extra) with schema consistency via
+  discovery-document digests.
+- Trace recording + replay (JSONL, redacted at emission).

ghemud_agentkit-0.1.0/CITATION.cff

@@ -0,0 +1,19 @@
+cff-version: 1.2.0
+message: "If you use Ghemud AgentKit in research or software, please cite it using this metadata."
+title: "Ghemud AgentKit"
+abstract: "A secure, provider-agnostic Python runtime for AI agent tool execution with policies, budgets, approvals, and audit trails."
+type: software
+authors:
+  - family-names: Ghemud
+    given-names: Yashraj Sachin
+repository-code: "https://github.com/yashraj-ghemud/ghemud-agentkit"
+url: "https://github.com/yashraj-ghemud/ghemud-agentkit"
+license: Apache-2.0
+version: 0.1.0
+date-released: 2026-08-23
+keywords:
+  - AI agents
+  - agent runtime
+  - Python
+  - security
+  - tool calling

ghemud_agentkit-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,15 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in the Ghemud AgentKit community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity or expression, experience level, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our standards
+
+Constructive collaboration, respectful disagreement, and empathy are expected. Harassment, discriminatory language, personal attacks, intimidation, and publication of private information without permission are not acceptable.
+
+## Enforcement
+
+Report unacceptable behavior privately through the repository’s security contact channel. Reports will be reviewed fairly and, where appropriate, may lead to correction, warning, temporary restriction, or removal from community spaces.
+
+This policy is adapted from the Contributor Covenant, version 2.1.

ghemud_agentkit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing to Ghemud AgentKit
+
+Thanks for helping build a safer tool runtime for agents. Ghemud AgentKit was created and is maintained by **Yashraj Sachin Ghemud**.
+
+## Setup
+
+```bash
+git clone https://github.com/yashraj-ghemud/ghemud-agentkit.git && cd ghemud-agentkit
+pip install -e ".[dev]"
+make test
+```
+
+## Ground rules
+
+1. **The pipeline is the product.** Features that bypass validation, policy,
+   or audit are not features — they're vulnerabilities. Every PR that adds a
+   capability must state its security boundary in the PR description.
+2. **Tests first for security behavior.** New guard? Negative test. New tool
+   declaration? Validation test. New event? Assert it carries the stable
+   invocation ID.
+3. **Model output is untrusted.** Any code path that consumes model-produced
+   fields must validate first. `tests/security/` is the pattern book.
+4. **No secrets in telemetry, ever.** Events/audit/results pass through the
+   redaction pipeline at emission time. There is no opt-out, and PRs adding
+   one will be closed.
+5. **Optional dependencies stay optional.** Core imports must never require
+   extras; guard imports and raise `InteroperabilityError` with install
+   instructions.
+6. **Zero required dependencies in core.** Adding one requires a design
+   doc explaining why wrapping/integrating is insufficient.
+
+## Checklist
+
+- [ ] `make lint && make typecheck && make test && make security`
+- [ ] Docstrings on all public APIs (type hints are mandatory)
+- [ ] `CHANGELOG.md` entry
+- [ ] Docs updated if behavior changed

ghemud_agentkit-0.1.0/CREDITS.md

@@ -0,0 +1,11 @@
+# Credits
+
+## Creator and maintainer
+
+**Ghemud AgentKit** was created and is maintained by **Yashraj Sachin Ghemud**.
+
+The project’s design centers on secure, provider-agnostic execution for Python AI-agent tools. Its public documentation, distribution metadata, release process, and repository stewardship are credited to Yashraj Sachin Ghemud.
+
+## Acknowledgements
+
+Ghemud AgentKit is released as open-source software under the Apache License 2.0. Contributions from the community are welcome and will be acknowledged through GitHub’s contributor history and release notes.

ghemud_agentkit-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ghemud_agentkit-0.1.0/NOTICE

@@ -0,0 +1,5 @@
+Ghemud AgentKit
+Copyright 2026 Yashraj Sachin Ghemud
+
+This product is licensed under the Apache License, Version 2.0.
+You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

ghemud_agentkit-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+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.*

ghemud_agentkit-0.1.0/README.md

@@ -0,0 +1,108 @@
+# 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.*

ghemud_agentkit-0.1.0/SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Supported versions
+
+Only the latest published release receives security fixes.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Instead, use the
+repository's private security-advisory workflow and include a minimal
+reproduction, affected version, and impact assessment. Do not include secrets,
+access tokens, or private data.
+
+Yashraj Sachin Ghemud will assess valid reports and coordinate a fix or mitigation.
+
+## Scope
+
+In scope: the Ghemud AgentKit runtime, schema generation/validation, permission
+system, approval flow, audit trail, and adapters shipped in this repository.
+
+Out of scope: vulnerabilities in provider SDKs, model alignment behavior,
+and deployments that disable documented safeguards. Ghemud AgentKit is an
+application-layer control and does not replace operating-system isolation,
+secret management, identity and access management, or network controls.