Metadata-Version: 2.4
Name: lodestar-crewai
Version: 0.3.0
Summary: Govern a CrewAI crew's native tool calls with Lodestar — the thin native hook that remotes each tool call through the Lodestar Action Kernel over NDJSON-RPC (ADR-0026).
Project-URL: Homepage, https://qmilab.com/lodestar
Project-URL: Repository, https://github.com/qmilab/lodestar
Project-URL: Issues, https://github.com/qmilab/lodestar/issues
Author-email: QMI Lab <hello@qmilab.com>
License: Apache-2.0
Keywords: agents,ai-agents,crewai,governance,lodestar,trust
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: lodestar-runtime-client==0.3.0
Provides-Extra: crewai
Requires-Dist: crewai>=1.0.0; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: crewai>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# lodestar-crewai

Govern a **CrewAI** crew's native tool calls with
[Lodestar](https://qmilab.com/lodestar) — the open epistemic-governance framework
for AI agents.

CrewAI runs role-based agents whose tools are native in-process Python objects and
does not speak MCP, so the MCP proxy cannot wrap it. This package is the **thin
native hook** (ADR-0026): it spawns the TypeScript **governance-gate sidecar**
(`lodestar runtime gate`) and remotes each native tool call through the Lodestar
Action Kernel over newline-delimited JSON-RPC. The same machinery the MCP proxy
and the LangGraph adapter run — two-phase `propose → arbitrate → execute`, the
signed policy gate, cognitive-core ingestion (external-document content can't
auto-promote), sentinel arbitration, and the signed-approval L4 hold path — now
applies to CrewAI, with no change to the engine. The gate sidecar is shared,
unchanged; only this hook is new.

The tool body runs **only** inside the gate's execute phase, reached only after
the gate (and any approval hold) clears: "tools that do work before approval are
bugs" — across the Python↔TS boundary.

## Install

```bash
pip install "lodestar-crewai[crewai]"
# and the Lodestar CLI (Bun/npm), which provides `lodestar runtime gate`:
npm install -g @qmilab/lodestar-cli   # or: bun add -g @qmilab/lodestar-cli
```

## Use

```python
from crewai import Agent, Crew, Task
from lodestar_crewai import GateClient, govern_tools, governed_call

with GateClient("runtime-gate.config.json") as gate:
    governed = govern_tools(gate, my_tools)        # register + wrap the toolset
    agent = Agent(role="researcher", goal="...", backstory="...", tools=governed)
    task = Task(description="...", agent=agent, expected_output="...")
    crew = Crew(agents=[agent], tasks=[task])
    crew.kickoff()                                  # every tool call is governed

    # A custom step invokes a governed tool through the helper, never raw:
    result = governed_call(gate, "search_web", {"q": "lodestar"})
```

The gate's config (`runtime-gate.config.json`) is a `RuntimeGateConfig` — the
signed policy document, approver keys, sentinel ids, persistence, and durable log
root all live there. The hook never holds credentials or policy.

## Scope (honest, ADR-0004 lineage)

This is **governance over declared actions, not OS containment of the process.**
Raw I/O performed *outside* the tool abstraction — a custom step that calls
`requests.get()` directly instead of a registered tool — is outside the governed
surface, exactly as `guard.wrap()` and the MCP proxy only govern the tools they
are given. A call for an unregistered tool is **denied** (fail closed). Pair the
adapter with network/filesystem controls for defense in depth.

## Holds & denials

An L4 action the trust-ladder floor parks for approval is resolved by
block-polling the gate up to the deadline for a *signed* approval (`hold_wait_ms`)
— the headless default. A denied / held-then-timed-out call raises
`LodestarDenied` by default; CrewAI's `ToolUsage` catches it and surfaces the
reason to the agent as a re-plannable observation. Pass `on_denied` to
`govern_tools` to map a denial to a return value instead.

Apache-2.0. Part of the Lodestar monorepo (`runtimes/crewai/`).
