donkey-kit 0.1.0__tar.gz

donkey_kit-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env/
+env/
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Node / TS
+node_modules/
+*.tsbuildinfo
+
+# OS
+.DS_Store
+
+# Editors
+.vscode/
+
+# Claude Code worktrees (isolated agent workspaces)
+.claude/worktrees/
+
+# AI agent config & skills — live in the private donkey-development-kit-ai-config
+# repo and are symlinked in locally; never track them here (keeps internal IP out
+# of this public repo). Clone donkey-development-kit-ai-config as a sibling dir.
+/AGENTS.md
+/CLAUDE.md
+/.claude/skills
+/.claude/settings.json
+/.claude/workflows
+/.claude/commands
+
+# Playwright MCP scratch output (local agent tooling)
+.playwright-mcp/
+
+# Rebrand issue/PR sweep dry-run report (#338) — generated artifact, not source
+scripts/rebrand/sweep-report/
+
+# Local donkey config (secrets / dev creds — never commit)
+.donkey-kit.local.toml
+donkey.lock.local
+
+# Sandbox suite manifest — real proxy base URLs / cred env-var wiring (#400).
+# The committed proxies.toml.example is the template; the filled file stays local.
+python/tests/sandbox/proxies.toml
+
+# Env
+.env
+.envrc

donkey_kit-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.5
+Name: donkey-kit
+Version: 0.1.0
+Summary: An SDK for consuming Agent Fabric capabilities (governed model and tool access) from your own agent framework.
+Project-URL: Homepage, https://github.com/Donkey-Development-Kit/donkey-development-kit
+Project-URL: Documentation, https://donkey-development-kit.github.io/donkey-development-kit
+Project-URL: Repository, https://github.com/Donkey-Development-Kit/donkey-development-kit
+Project-URL: Issues, https://github.com/Donkey-Development-Kit/donkey-development-kit/issues
+Project-URL: Changelog, https://github.com/Donkey-Development-Kit/donkey-development-kit/releases
+Author: See README for maintainer + support statement
+License: Apache-2.0
+Keywords: agent,anypoint,donkey-kit,gateway,llm,mcp,mulesoft
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typing-extensions>=4.10; python_version < '3.12'
+Provides-Extra: a2a
+Requires-Dist: a2a-sdk>=0.1; extra == 'a2a'
+Provides-Extra: adk
+Requires-Dist: google-adk>=0.2; extra == 'adk'
+Requires-Dist: litellm>=1.84; extra == 'adk'
+Provides-Extra: agent-framework
+Requires-Dist: agent-framework>=0.1; extra == 'agent-framework'
+Provides-Extra: all
+Requires-Dist: agent-framework>=0.1; extra == 'all'
+Requires-Dist: anthropic>=0.40; extra == 'all'
+Requires-Dist: crewai>=0.80; extra == 'all'
+Requires-Dist: google-adk>=0.2; extra == 'all'
+Requires-Dist: langchain-core>=0.2; extra == 'all'
+Requires-Dist: langchain-openai>=0.1; extra == 'all'
+Requires-Dist: langgraph>=0.3; extra == 'all'
+Requires-Dist: litellm>=1.84; extra == 'all'
+Requires-Dist: llama-index-llms-openai-like>=0.1; extra == 'all'
+Requires-Dist: mcp>=1.2; extra == 'all'
+Requires-Dist: openai-agents>=0.1; extra == 'all'
+Requires-Dist: openai>=1.30; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.24; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.24; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.24; extra == 'all'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
+Requires-Dist: pytest>=8.0; extra == 'all'
+Requires-Dist: pyyaml>=6.0; extra == 'all'
+Requires-Dist: rich>=13.0; extra == 'all'
+Requires-Dist: starlette>=0.37; extra == 'all'
+Requires-Dist: strands-agents>=0.1; extra == 'all'
+Requires-Dist: typer>=0.12; extra == 'all'
+Requires-Dist: uvicorn>=0.30; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: cli
+Requires-Dist: pyyaml>=6.0; extra == 'cli'
+Requires-Dist: rich>=13.0; extra == 'cli'
+Requires-Dist: typer>=0.12; extra == 'cli'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.80; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: import-linter>=2.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: typer>=0.12; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=0.2; extra == 'langgraph'
+Requires-Dist: langchain-openai>=0.1; extra == 'langgraph'
+Requires-Dist: langgraph>=0.3; extra == 'langgraph'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-llms-openai-like>=0.1; extra == 'llamaindex'
+Provides-Extra: llm
+Requires-Dist: openai>=1.30; extra == 'llm'
+Provides-Extra: local
+Requires-Dist: starlette>=0.37; extra == 'local'
+Requires-Dist: uvicorn>=0.30; extra == 'local'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.1; extra == 'openai-agents'
+Requires-Dist: openai>=1.30; extra == 'openai-agents'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.24; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.24; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.24; extra == 'otel'
+Provides-Extra: strands
+Requires-Dist: strands-agents>=0.1; extra == 'strands'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Donkey-Development-Kit/donkey-development-kit/main/brand/ddk-logo-stacked-black.png" alt="Donkey Development Kit (DDK)" width="180" />
+</p>
+
+# Donkey Development Kit
+
+An SDK for consuming **Agent Fabric** capabilities — governed model and tool
+access — from your own agent framework, in your own IDE, without adopting Mule.
+
+> **Project status — alpha.** This is `v0.1.0`, the first release
+> (`Development Status :: 3 - Alpha`). The **LLM data plane is live-verified**;
+> most other surfaces are verification-gated (see
+> [What's verified](#whats-verified-verification-discipline) below). Install it
+> from PyPI with `pip install donkey-kit` — see [Install](#install).
+> **Unofficial:** an independent project,
+> **not** affiliated with or endorsed by Salesforce or MuleSoft.
+
+> **Already integrated the pre-rebrand SDK?** The move to Donkey Development Kit
+> is a clean break — no import shims, env fallbacks, or OpenTelemetry dual-emit.
+> The [migration guide](https://github.com/Donkey-Development-Kit/donkey-development-kit/blob/main/MIGRATION.md)
+> maps every renamed import, class, CLI, config key, and environment variable,
+> and calls out the breaking OpenTelemetry attribute-namespace change.
+
+> ### Support & trademark statement (please read)
+>
+> **"Agent Fabric" is a MuleSoft (Salesforce) product name, not a generic
+> term.** `MuleSoft`, `Anypoint`, `Omni Gateway`, and `Agent Fabric` are
+> Salesforce trademarks.
+>
+> **Maintainer & support.** This is an **independent, community-maintained**
+> project, published under the org-scoped `Donkey-Development-Kit` name — it is **not**
+> affiliated with, endorsed by, or supported by Salesforce or MuleSoft. It is
+> provided **as-is, without warranty of any kind**; the maintainers triage issues
+> and pull requests on a **best-effort basis, with no SLA**. Because it ships
+> under a distinct, org-scoped name, only the descriptive form ("an SDK for
+> MuleSoft Agent Fabric") appears in prose — the package does not represent itself
+> as a first-party, official-status SDK.
+>
+> Licensed under [Apache-2.0](LICENSE). See
+> [`docs/unsupported-boundary.md`](docs/unsupported-boundary.md) for exactly
+> which platform APIs this SDK calls and their support classification.
+
+## Documentation
+
+Two audiences, two doc sets:
+
+- **Use the SDK** → the documentation site:
+  **<https://donkey-development-kit.github.io/donkey-development-kit/>**. Install and
+  configure, per-framework model access, the governed error taxonomy, and what
+  to trust today — everything you need to point your agent at a governed proxy.
+- **See it run** → runnable demos live in the companion repo
+  **[donkey-development-kit-demos](https://github.com/Donkey-Development-Kit/donkey-development-kit-demos)**:
+  the framework-free client, native framework objects, the governed error
+  taxonomy, and the screen-recording scripts.
+- **Understand or contribute to the repo:**
+  - [`ARCHITECTURE.md`](ARCHITECTURE.md) — how the SDK is built: the layered
+    stack, the framework-free core, verification discipline, the error taxonomy,
+    and framework tiering.
+  - [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to work in the repo: the
+    branch/PR/release workflow, the testing strategy, coding conventions, and
+    the docs-sync rule.
+  - [`docs/verified-apis.md`](docs/verified-apis.md) — the verification ledger:
+    the single source of truth for what is confirmed against a real sandbox and
+    what is still blocked.
+
+## Install
+
+```bash
+pip install "donkey-kit[llm,langgraph]"   # base + raw client + one framework
+```
+
+To work on the SDK itself, install from source instead:
+
+```bash
+git clone https://github.com/Donkey-Development-Kit/donkey-development-kit.git
+cd donkey-development-kit/python
+pip install -e ".[llm,langgraph]"
+```
+
+Extras are one per framework (`langgraph`, `adk`, `strands`, `agent_framework`,
+`openai-agents`, `anthropic`, `crewai`, `llamaindex`) plus `mcp`, `a2a`, `otel`, `cli`,
+`local`, `test` (the [conformance pytest plugin](https://donkey-development-kit.github.io/donkey-development-kit/testing) —
+`pytest --donkey-conformance --agent=my_app.agent:build`), and `all`.
+Configuration and first-agent walkthroughs live on the
+[documentation site](https://donkey-development-kit.github.io/donkey-development-kit/).
+
+## Framework support
+
+The roster is deliberately **one deep, seven shallow** (`BG §1.8`): one adapter
+held to the full conformance bar, the rest supported through the three-line
+`connection_kwargs()` escape hatch. Every framework below returns its framework's
+**own native object** — never a wrapper.
+
+| Tier | Frameworks | What it means |
+| --- | --- | --- |
+| **Conformance-tested** | The raw client (`donkey.llm.client()`) and **LangGraph** | Held to the conformance suite in CI — the governed contract is proven end to end. |
+| **Supported via `connection_kwargs()`** | Google ADK, Strands, Microsoft Agent Framework, OpenAI Agents SDK, Anthropic SDK, CrewAI, LlamaIndex | Governed kwargs verified at the `connection_kwargs()` level, not conformance-tested. |
+
+`connection_kwargs()` works for all eight; a second deep adapter is promoted from
+demand evidence, one at a time (#223/#244) — never guessed up front. See the
+[framework pages](https://donkey-development-kit.github.io/donkey-development-kit/frameworks/)
+for each.
+
+## What's verified (verification discipline)
+
+The **LLM data plane** — governed model access through the Omni Gateway proxy —
+is live-verified against a real Anypoint sandbox, and both the framework-free
+client and the framework adapters are wired to that verified contract — LangGraph
+is held to the conformance suite, the other seven are supported at the
+`connection_kwargs()` level (see [Framework support](#framework-support)).
+Everything still gated raises `NotImplementedError("blocked on verification: …")`
+rather than guessing at an unverified endpoint, header, or class name — that
+currently includes Exchange→MCP tool discovery, the provisioning control-plane,
+and the exact framework adapter class names/kwargs.
+
+The discipline behind this is documented in
+[`ARCHITECTURE.md` → Verification discipline](ARCHITECTURE.md#verification-discipline);
+the row-by-row worklist is [`docs/verified-apis.md`](docs/verified-apis.md).
+
+## Conformance exemptions
+
+The [conformance plugin](https://donkey-development-kit.github.io/donkey-development-kit/testing)
+holds the SDK to the same bar it asks of your agent. Where a framework
+legitimately cannot satisfy a scenario, the reason is asserted in code
+(`KNOWN_LIMITATIONS`) and published here as credibility — never a silent skip
+(the conformance kit):
+
+| Framework | Scenario | Why it's exempt |
+| --- | --- | --- |
+| ADK, CrewAI | correlation ID propagated | LiteLLM owns the transport, so the SDK's `httpx` client cannot be injected — the correlation ID ends up per-client, not per-run. A LiteLLM logger callback may recover trace correlation later. |
+| LlamaIndex, Microsoft Agent Framework | correlation ID propagated | These adapters receive a static `default_headers` snapshot, which deliberately excludes the per-run correlation ID. Without the SDK's `httpx` client, `donkey.run(id=...)` cannot update their request headers. |
+| ADK, CrewAI | gateway identity observed | LiteLLM owns the transport, so no response reaches the SDK's `_on_response` hook. When every resolved adapter is non-observing, `donkey.last_call` reports `UNAVAILABLE` and names them in `surface`. |
+| LlamaIndex, Microsoft Agent Framework | gateway identity observed | These adapters receive `default_headers`, not the SDK's `httpx` client, so no response reaches `_on_response`. When every resolved adapter is non-observing, `donkey.last_call` reports `UNAVAILABLE` and names them in `surface`. |

donkey_kit-0.1.0/README.md

@@ -0,0 +1,133 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Donkey-Development-Kit/donkey-development-kit/main/brand/ddk-logo-stacked-black.png" alt="Donkey Development Kit (DDK)" width="180" />
+</p>
+
+# Donkey Development Kit
+
+An SDK for consuming **Agent Fabric** capabilities — governed model and tool
+access — from your own agent framework, in your own IDE, without adopting Mule.
+
+> **Project status — alpha.** This is `v0.1.0`, the first release
+> (`Development Status :: 3 - Alpha`). The **LLM data plane is live-verified**;
+> most other surfaces are verification-gated (see
+> [What's verified](#whats-verified-verification-discipline) below). Install it
+> from PyPI with `pip install donkey-kit` — see [Install](#install).
+> **Unofficial:** an independent project,
+> **not** affiliated with or endorsed by Salesforce or MuleSoft.
+
+> **Already integrated the pre-rebrand SDK?** The move to Donkey Development Kit
+> is a clean break — no import shims, env fallbacks, or OpenTelemetry dual-emit.
+> The [migration guide](https://github.com/Donkey-Development-Kit/donkey-development-kit/blob/main/MIGRATION.md)
+> maps every renamed import, class, CLI, config key, and environment variable,
+> and calls out the breaking OpenTelemetry attribute-namespace change.
+
+> ### Support & trademark statement (please read)
+>
+> **"Agent Fabric" is a MuleSoft (Salesforce) product name, not a generic
+> term.** `MuleSoft`, `Anypoint`, `Omni Gateway`, and `Agent Fabric` are
+> Salesforce trademarks.
+>
+> **Maintainer & support.** This is an **independent, community-maintained**
+> project, published under the org-scoped `Donkey-Development-Kit` name — it is **not**
+> affiliated with, endorsed by, or supported by Salesforce or MuleSoft. It is
+> provided **as-is, without warranty of any kind**; the maintainers triage issues
+> and pull requests on a **best-effort basis, with no SLA**. Because it ships
+> under a distinct, org-scoped name, only the descriptive form ("an SDK for
+> MuleSoft Agent Fabric") appears in prose — the package does not represent itself
+> as a first-party, official-status SDK.
+>
+> Licensed under [Apache-2.0](LICENSE). See
+> [`docs/unsupported-boundary.md`](docs/unsupported-boundary.md) for exactly
+> which platform APIs this SDK calls and their support classification.
+
+## Documentation
+
+Two audiences, two doc sets:
+
+- **Use the SDK** → the documentation site:
+  **<https://donkey-development-kit.github.io/donkey-development-kit/>**. Install and
+  configure, per-framework model access, the governed error taxonomy, and what
+  to trust today — everything you need to point your agent at a governed proxy.
+- **See it run** → runnable demos live in the companion repo
+  **[donkey-development-kit-demos](https://github.com/Donkey-Development-Kit/donkey-development-kit-demos)**:
+  the framework-free client, native framework objects, the governed error
+  taxonomy, and the screen-recording scripts.
+- **Understand or contribute to the repo:**
+  - [`ARCHITECTURE.md`](ARCHITECTURE.md) — how the SDK is built: the layered
+    stack, the framework-free core, verification discipline, the error taxonomy,
+    and framework tiering.
+  - [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to work in the repo: the
+    branch/PR/release workflow, the testing strategy, coding conventions, and
+    the docs-sync rule.
+  - [`docs/verified-apis.md`](docs/verified-apis.md) — the verification ledger:
+    the single source of truth for what is confirmed against a real sandbox and
+    what is still blocked.
+
+## Install
+
+```bash
+pip install "donkey-kit[llm,langgraph]"   # base + raw client + one framework
+```
+
+To work on the SDK itself, install from source instead:
+
+```bash
+git clone https://github.com/Donkey-Development-Kit/donkey-development-kit.git
+cd donkey-development-kit/python
+pip install -e ".[llm,langgraph]"
+```
+
+Extras are one per framework (`langgraph`, `adk`, `strands`, `agent_framework`,
+`openai-agents`, `anthropic`, `crewai`, `llamaindex`) plus `mcp`, `a2a`, `otel`, `cli`,
+`local`, `test` (the [conformance pytest plugin](https://donkey-development-kit.github.io/donkey-development-kit/testing) —
+`pytest --donkey-conformance --agent=my_app.agent:build`), and `all`.
+Configuration and first-agent walkthroughs live on the
+[documentation site](https://donkey-development-kit.github.io/donkey-development-kit/).
+
+## Framework support
+
+The roster is deliberately **one deep, seven shallow** (`BG §1.8`): one adapter
+held to the full conformance bar, the rest supported through the three-line
+`connection_kwargs()` escape hatch. Every framework below returns its framework's
+**own native object** — never a wrapper.
+
+| Tier | Frameworks | What it means |
+| --- | --- | --- |
+| **Conformance-tested** | The raw client (`donkey.llm.client()`) and **LangGraph** | Held to the conformance suite in CI — the governed contract is proven end to end. |
+| **Supported via `connection_kwargs()`** | Google ADK, Strands, Microsoft Agent Framework, OpenAI Agents SDK, Anthropic SDK, CrewAI, LlamaIndex | Governed kwargs verified at the `connection_kwargs()` level, not conformance-tested. |
+
+`connection_kwargs()` works for all eight; a second deep adapter is promoted from
+demand evidence, one at a time (#223/#244) — never guessed up front. See the
+[framework pages](https://donkey-development-kit.github.io/donkey-development-kit/frameworks/)
+for each.
+
+## What's verified (verification discipline)
+
+The **LLM data plane** — governed model access through the Omni Gateway proxy —
+is live-verified against a real Anypoint sandbox, and both the framework-free
+client and the framework adapters are wired to that verified contract — LangGraph
+is held to the conformance suite, the other seven are supported at the
+`connection_kwargs()` level (see [Framework support](#framework-support)).
+Everything still gated raises `NotImplementedError("blocked on verification: …")`
+rather than guessing at an unverified endpoint, header, or class name — that
+currently includes Exchange→MCP tool discovery, the provisioning control-plane,
+and the exact framework adapter class names/kwargs.
+
+The discipline behind this is documented in
+[`ARCHITECTURE.md` → Verification discipline](ARCHITECTURE.md#verification-discipline);
+the row-by-row worklist is [`docs/verified-apis.md`](docs/verified-apis.md).
+
+## Conformance exemptions
+
+The [conformance plugin](https://donkey-development-kit.github.io/donkey-development-kit/testing)
+holds the SDK to the same bar it asks of your agent. Where a framework
+legitimately cannot satisfy a scenario, the reason is asserted in code
+(`KNOWN_LIMITATIONS`) and published here as credibility — never a silent skip
+(the conformance kit):
+
+| Framework | Scenario | Why it's exempt |
+| --- | --- | --- |
+| ADK, CrewAI | correlation ID propagated | LiteLLM owns the transport, so the SDK's `httpx` client cannot be injected — the correlation ID ends up per-client, not per-run. A LiteLLM logger callback may recover trace correlation later. |
+| LlamaIndex, Microsoft Agent Framework | correlation ID propagated | These adapters receive a static `default_headers` snapshot, which deliberately excludes the per-run correlation ID. Without the SDK's `httpx` client, `donkey.run(id=...)` cannot update their request headers. |
+| ADK, CrewAI | gateway identity observed | LiteLLM owns the transport, so no response reaches the SDK's `_on_response` hook. When every resolved adapter is non-observing, `donkey.last_call` reports `UNAVAILABLE` and names them in `surface`. |
+| LlamaIndex, Microsoft Agent Framework | gateway identity observed | These adapters receive `default_headers`, not the SDK's `httpx` client, so no response reaches `_on_response`. When every resolved adapter is non-observing, `donkey.last_call` reports `UNAVAILABLE` and names them in `surface`. |

donkey_kit-0.1.0/examples/adk/README.md

@@ -0,0 +1,61 @@
+# Google ADK example
+
+Supported at connection_kwargs() — not conformance-tested (BG §1.8).
+
+**What this shows.** A one-line factory call gets you a *native*
+`google.adk.models.lite_llm.LiteLlm` pointed at the governed Agent Fabric LLM
+proxy — correct `api_base`, `client_id`/`client_secret` auth via
+`extra_headers` (not bearer), and the model id auto-prefixed with `openai/`
+so LiteLLM routes it correctly. The returned object is ADK's own class, not
+a wrapper. Note: LiteLLM owns its own HTTP transport, so (unlike LangGraph)
+the SDK's shared http client/retry hooks are not injected here — this is a
+documented conformance exemption, not an oversight. This example only
+constructs the object; it deliberately does not attempt a live inference
+call, since ADK drives models through its own `Runner`/`Agent` session
+machinery rather than a simple method call.
+
+> 📖 **Prefer reading to running?** The canonical walkthrough — install,
+> configure, and the manual equivalent — is in the docs:
+> **[Google ADK](https://donkey-development-kit.github.io/donkey-development-kit/frameworks/adk)**.
+> This README duplicates the runnable essentials on purpose so you can run it in
+> place; if the two ever differ, the docs page is canonical.
+
+## Run
+
+```bash
+pip install "donkey-kit[adk]"
+
+export DONKEY_LLM_PROXY_URL="https://<ingress-gw>/<instance>/"   # note: no /v1
+export DONKEY_LLM_PROXY_CLIENT_ID="<consumer client id>"
+export DONKEY_LLM_PROXY_CLIENT_SECRET="<consumer client secret>"
+
+python examples/adk/main.py
+```
+
+## The manual equivalent
+
+The factory call is equivalent to building `LiteLlm` yourself with the
+governed connection values (BG §1.8):
+
+```python
+from google.adk.models.lite_llm import LiteLlm
+
+m = LiteLlm(
+    model="openai/gpt-4o",  # LiteLLM's OpenAI-compatible route needs this prefix
+    api_base=DONKEY_LLM_PROXY_URL,
+    api_key="unused",  # the proxy enforces client_id/client_secret headers instead
+    extra_headers={
+        "client_id": DONKEY_LLM_PROXY_CLIENT_ID,
+        "client_secret": DONKEY_LLM_PROXY_CLIENT_SECRET,
+    },
+)
+```
+
+The factory (`donkey_kit.integrations.adk.model`) fills in `api_base`,
+`api_key`, `extra_headers`, and the `openai/` prefix from one governed
+config source.
+
+## Links
+
+- Google Agent Development Kit (ADK) docs: see the framework's official
+  documentation

donkey_kit-0.1.0/examples/adk/main.py

@@ -0,0 +1,68 @@
+"""Google ADK adapter example (BG §1.8).
+
+Supported at connection_kwargs() — not conformance-tested (BG §1.8).
+
+Demonstrates constructing a native ``google.adk.models.lite_llm.LiteLlm``
+pointed at the governed Agent Fabric LLM proxy with a single factory call:
+
+    from donkey_kit.integrations.adk import model
+    m = model("gpt-4o")  # sent to LiteLLM as "openai/gpt-4o"
+
+Honest status (verification discipline / docs/verified-apis.md §8): the proxy *contract* (base URL,
+client_id/secret auth, attribution headers) is live-verified, and ``LiteLlm``/its kwargs are
+verified per the FACTS table. What is NOT attempted here is a live
+inference call: ADK drives models through its own ``Runner``/``Agent``
+session machinery, not a simple one-line method on the model object, and
+guessing that call risks inventing an API (verification discipline). Construction is this
+example's verified surface — once you have ``m``, wire it into your own ADK
+``Agent``/``Runner`` per ADK's own docs.
+"""
+
+from __future__ import annotations
+
+import os
+
+from donkey_kit.core.errors import ConfigError
+from donkey_kit.integrations.adk import model
+
+
+def _missing_env() -> list[str]:
+    names = (
+        "DONKEY_LLM_PROXY_URL",
+        "DONKEY_LLM_PROXY_CLIENT_ID",
+        "DONKEY_LLM_PROXY_CLIENT_SECRET",
+    )
+    return [n for n in names if not os.environ.get(n)]
+
+
+def main() -> None:
+    missing = _missing_env()
+    if missing:
+        print("Set the following environment variables and re-run:")
+        print('    export DONKEY_LLM_PROXY_URL="https://<ingress-gw>/<instance>/"  # no /v1')
+        print('    export DONKEY_LLM_PROXY_CLIENT_ID="<consumer client id>"')
+        print('    export DONKEY_LLM_PROXY_CLIENT_SECRET="<consumer client secret>"')
+        return
+
+    model_id = os.environ.get("DEMO_MODEL", "gpt-4o")
+
+    try:
+        m = model(model_id)
+    except ImportError:
+        print("Google ADK not installed. Install it with:")
+        print('    pip install "donkey-kit[adk]"')
+        return
+    except ConfigError as e:
+        print(f"Config error: {e}")
+        return
+
+    print(f"Constructed native object: {type(m).__module__}.{type(m).__name__}")
+    print(
+        "Construction is the SDK's verified surface; drive this object with "
+        "ADK's own Agent/Runner API (see this example's README) — that "
+        "runtime call is UNVERIFIED here and deliberately not guessed (verification discipline)."
+    )
+
+
+if __name__ == "__main__":
+    main()

donkey_kit-0.1.0/examples/agent_framework/README.md

@@ -0,0 +1,65 @@
+# Microsoft Agent Framework example
+
+Supported at connection_kwargs() — not conformance-tested (BG §1.8).
+
+**What this shows.** A one-line factory call attempts to build a native
+Agent Framework OpenAI-compatible chat client pointed at the governed
+Agent Fabric LLM proxy. The proxy *contract* (base URL, `client_id`/
+`client_secret` header auth, attribution headers) is live-verified. The
+chat-client class name/path itself — `agent_framework.openai.OpenAIChatClient`
+— and its base-URL kwarg (`model_id`) are **UNVERIFIED** (docs/verified-apis.md §8): Agent
+Framework is a young package that has renamed classes recently. If the
+import fails, the factory raises a `NotImplementedError` ("blocked on
+verification") rather than guessing further; this example catches that and
+prints it plainly. This example only constructs the object; it deliberately
+does not attempt a live inference call, since Agent Framework drives chat
+clients through its own `Agent` object rather than a method on the client
+itself.
+
+> 📖 **Prefer reading to running?** The canonical walkthrough — install,
+> configure, and the manual equivalent — is in the docs:
+> **[Microsoft Agent Framework](https://donkey-development-kit.github.io/donkey-development-kit/frameworks/agent-framework)**.
+> This README duplicates the runnable essentials on purpose so you can run it in
+> place; if the two ever differ, the docs page is canonical.
+
+## Run
+
+```bash
+pip install "donkey-kit[agent_framework]"
+
+export DONKEY_LLM_PROXY_URL="https://<ingress-gw>/<instance>/"   # note: no /v1
+export DONKEY_LLM_PROXY_CLIENT_ID="<consumer client id>"
+export DONKEY_LLM_PROXY_CLIENT_SECRET="<consumer client secret>"
+
+python examples/agent_framework/main.py
+```
+
+## The manual equivalent
+
+The factory call is equivalent to attempting to build the chat client
+yourself with the governed connection values (BG §1.8) — **class name and
+kwarg UNVERIFIED (docs/verified-apis.md §8), confirm against your installed version**:
+
+```python
+# CLASS NAME/PATH AND KWARG NAMES UNVERIFIED (docs/verified-apis.md §8) — confirm before relying on this
+from agent_framework.openai import OpenAIChatClient
+
+client = OpenAIChatClient(
+    model_id="gpt-4o",  # kwarg name UNVERIFIED
+    base_url=DONKEY_LLM_PROXY_URL,
+    api_key="unused",  # the proxy enforces client_id/client_secret headers instead
+    default_headers={
+        "client_id": DONKEY_LLM_PROXY_CLIENT_ID,
+        "client_secret": DONKEY_LLM_PROXY_CLIENT_SECRET,
+    },
+)
+```
+
+The factory (`donkey_kit.integrations.agent_framework.chat_client`) fills
+in `base_url`, `api_key`, and `default_headers` from one governed config
+source, and raises a clear "blocked on verification" error instead of
+silently guessing if the class import fails.
+
+## Links
+
+- Microsoft Agent Framework docs: see the framework's official documentation