Metadata-Version: 2.4
Name: gaas-crewai
Version: 0.1.0
Summary: CrewAI integration for GaaS (Governance as a Service)
Project-URL: Homepage, https://gaas.is
Project-URL: Documentation, https://gaas.to/sdks.html
Project-URL: Repository, https://github.com/H2OmAI/gaas
Project-URL: Changelog, https://github.com/H2OmAI/gaas/blob/main/CHANGELOG.md
Author-email: H2Om <sdk@gaas.is>
License-Expression: Apache-2.0
Keywords: agents,ai,crewai,gaas,governance
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: gaas-sdk>=0.2.7
Requires-Dist: httpx>=0.27.0
Provides-Extra: all
Requires-Dist: crewai>=1.0; extra == 'all'
Provides-Extra: crewai
Requires-Dist: crewai>=1.0; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: crewai<2,>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# gaas-crewai

GaaS (Governance as a Service) integration for [CrewAI](https://github.com/crewAIInc/crewAI).

Every tool call is governed **before it executes**: the adapter submits a
governance intent to GaaS, and only an APPROVE (or an approved escalation)
lets the tool run. On BLOCK the wrapped tool never executes and
`GovernanceBlockedError` is raised from the tool.

```bash
pip install gaas-crewai[crewai]
```

## Quickstart

```python
from crewai import Agent
from gaas_crewai import govern_tools, GaaSGovernanceConfig

config = GaaSGovernanceConfig(api_key="gsk_...", agent_id="my-crew-agent")

researcher = Agent(
    role="researcher",
    goal="Find and share accurate information",
    backstory="...",
    tools=govern_tools([search_tool, email_tool], config=config),
)
```

Works with hand-written `BaseTool` subclasses and `@tool`-decorated functions
alike. Name, description, and `args_schema` are preserved — the agent sees an
identical tool.

## Verdict flow

```
tool call → GaaS intent → ┌─────────┐
                          │ APPROVE │ → tool executes
                          │ BLOCK   │ → GovernanceBlockedError; tool never runs
                          │ ESCALATE│ → raises by default; hold-and-poll optional
                          └─────────┘
```

**Honest enforcement note:** inside a running Crew, CrewAI's tool-usage loop
catches tool exceptions and surfaces them to the agent as an error
observation (it may retry). The blocked action still never executes — each
retry submits a fresh intent that is re-blocked, and every attempt lands on
the signed audit chain server-side. For hard-stop semantics, catch
`GovernanceBlockedError` where you invoke the crew or use the GaaS
deviation/auto-suspend controls.

## Configuration

```python
from gaas_crewai import GaaSGovernanceConfig

config = GaaSGovernanceConfig(
    api_url="https://api.gaas.is",    # GaaS API endpoint
    api_key="gsk_...",                # Your API key
    agent_id="my-crew-agent",         # Agent identifier (appears in audit trail)
    block_on_escalate=True,           # Raise GovernanceBlockedError on ESCALATE
    timeout_seconds=5.0,              # Governance check timeout (fail open on timeout)
    sensitivity="INTERNAL",           # Default sensitivity level for tool inputs
    raise_on_governance_error=False,  # Fail open if GaaS API is unreachable
    extra_regulatory_domains=["HIPAA"],   # Additional domains for all intents
    extra_data_categories=["PHI"],        # Additional data categories for all intents
    hold_on_escalate=False,           # Wait for the human decision on ESCALATE
    escalation_poll_seconds=5.0,      # Poll interval while holding
    escalation_max_wait_seconds=600.0,  # Give up (treat as timeout) after this
)
```

### Hold-and-Poll on ESCALATE

With `hold_on_escalate=True`, an ESCALATE verdict no longer raises
immediately. The tool call holds while GaaS routes the escalation to a human
reviewer, polling until it is decided:

- **approve / modify** — the tool executes.
- **deny** — raises `GovernanceBlockedError` with verdict `ESCALATE_DENY`.
- **timeout** — raises `GovernanceBlockedError` with verdict `ESCALATE_TIMEOUT`.

`hold_on_escalate` takes precedence over `block_on_escalate`. Transient
polling errors are retried until the deadline.

## Handling blocked calls

```python
from gaas_crewai import GovernanceBlockedError

try:
    result = governed_tool.run(to="all-customers@list", subject="...")
except GovernanceBlockedError as err:
    print(err.verdict)                  # BLOCK / ESCALATE / ESCALATE_DENY / ESCALATE_TIMEOUT
    print(err.decision_id)              # audit reference
    print(err.blocking_policies)        # policy IDs that triggered the block
    print(err.governance_proof_token)   # GPT token ID for the legal audit trail
```

## Links

- Docs: https://gaas.to/sdks.html
- GaaS: https://gaas.is
