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