jhcontext-crewai

Production deployment of the PAC-AI protocol with CrewAI agents on AWS.

Multi-agent healthcare, education, recommendation, and finance scenarios that demonstrate EU AI Act compliance (Annex III 5(b), Articles 13 and 14) through auditable context envelopes, W3C PROV provenance graphs, and cryptographic integrity verification — all persisted on DynamoDB + S3.

TL;DR: This is the production-grade version of the jhcontext compliance scenarios — real CrewAI agents, AWS infrastructure (Chalice Lambda + DynamoDB + S3), and persistent storage. For a lightweight in-memory proof-of-concept with no infrastructure, see jhcontext-usecases.

Architecture

                          ┌─────────────────────────────┐
                          │     Agent (local/Lambda)     │
                          │  CrewAI Flows + ContextMixin │
                          └──────────┬──────────────────┘
                                     │ HTTPS
                    ┌────────────────┼────────────────┐
                    ▼                ▼                 ▼
         ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
         │  jhcontext-api│  │ jhcontext-mcp│  │   S3 Bucket  │
         │   (Chalice)   │  │   (Chalice)  │  │  artifacts   │
         │   Lambda      │  │   Lambda     │  └──────────────┘
         └───────┬───────┘  └───────┬──────┘
                 │                  │
         ┌───────┴──────────────────┴──────┐
         │           DynamoDB              │
         │  envelopes · artifacts · prov   │
         │  decisions (4 tables)           │
         └─────────────────────────────────┘

Three independent modules, three separate deployments. The agent runs locally and calls the deployed API over HTTPS — keeping Lambda cold start under 2 seconds.

See Architecture for full repository structure and dependency separation.

Scenarios (Crews)

Each scenario demonstrates a different EU AI Act compliance pattern:

| Scenario | Article | Risk | Agents | Key Proof | |----------|---------|------|--------|-----------| | Healthcare | Art. 14 — Human Oversight | HIGH | 5 (sensor → situation → decision → oversight → audit) | Temporal proof that physician reviewed docs AFTER AI recommendation | | Education | Art. 13 — Non-Discrimination | HIGH | 4 (ingestion → grading ╳ equity → audit) | Workflow isolation + negative proof (identity absent from grading) | | Recommendation | LOW-risk | LOW | 3 (profile → search → personalize) | Full provenance with Raw-Forward policy | | Finance | Annex III 5(b) — Composite | HIGH | 7 (data → risk → decision → oversight ╳ fair lending → audit) | All 4 patterns: negative proof + temporal oversight + workflow isolation + PII detachment |

Crew Delegation in PROV

Crews are modeled explicitly in the W3C PROV graph using prov:actedOnBehalfOf. The PROV graph itself serves as the coordination layer — no external pipeline ID needed.

In any flow, call _register_crew() after _init_context():

class MyFlow(Flow, ContextMixin):
    @start()
    def init(self):
        self._init_context(
            scope="healthcare",
            producer="did:hospital:system",
            risk_level=RiskLevel.HIGH,
        )

        # Agents in the crew get prov:actedOnBehalfOf the crew agent
        self._register_crew(
            crew_id="crew:clinical-pipeline",
            label="Clinical Pipeline Crew",
            agent_ids=[
                "did:hospital:sensor-agent",
                "did:hospital:situation-agent",
                "did:hospital:decision-agent",
            ],
        )
        # Oversight agent stays outside the crew — explicit boundary

This produces PROV triples like:

jh:crew-clinical-pipeline a prov:Agent, prov:SoftwareAgent ;
    rdfs:label "Clinical Pipeline Crew" ;
    jh:agentType "crew" .

<did:hospital:sensor-agent> prov:actedOnBehalfOf jh:crew-clinical-pipeline .

Query all activities from a crew via SPARQL:

SELECT ?activity ?label WHERE {
    ?agent prov:actedOnBehalfOf jh:crew-clinical-pipeline .
    ?activity prov:wasAssociatedWith ?agent .
    ?activity rdfs:label ?label .
}

Quick Start

Prerequisites

• Python 3.10+
• AWS account with credentials configured (aws configure)
• jhcontext SDK published to PyPI (or installed from ../jhcontext-sdk)

1. Create DynamoDB tables and S3 bucket

cd jhcontext-crewai/api
pip install -r requirements.txt
python setup_tables.py

This creates 4 DynamoDB tables (PAY_PER_REQUEST billing) and 1 S3 bucket:

• jhcontext-envelopes (PK: context_id, GSI: ScopeIndex)
• jhcontext-artifacts (PK: artifact_id, GSI: ContextIndex)
• jhcontext-prov-graphs (PK: context_id)
• jhcontext-decisions (PK: decision_id, GSI: ContextIndex)
• jhcontext-artifacts-dev (S3 bucket for large artifact content)

2. Deploy API

cd jhcontext-crewai/api
./deploy.sh

Note the API endpoint URL printed at the end.

3. Deploy MCP (optional)

cd jhcontext-crewai/mcp
./deploy.sh

4. Install agent dependencies (local)

cd jhcontext-crewai
pip install -r agent/requirements.txt

Set the API URL:

export JHCONTEXT_API_URL=https://{api-id}.execute-api.us-east-1.amazonaws.com/api

Running Scenarios

With AWS

python -m agent.run --scenario healthcare
python -m agent.run --scenario education
python -m agent.run --scenario recommendation
python -m agent.run --scenario finance
python -m agent.run --scenario all

Without AWS (local mode)

python -m agent.run --local --scenario healthcare
python -m agent.run --local --scenario all

Auto-starts a local SQLite server on :8400, runs the scenario, and shuts down. No second terminal needed. See Local Development for details.

Validate results

python -m agent.run --validate        # validate latest run
python -m agent.run --validate v01    # validate specific run

See Validation for interpreting results, audit checks, and UserML semantic payloads.

Documentation

| Topic | Description | |-------|-------------| | Architecture | System diagram, repository structure, dependency separation | | API Reference | All API routes with curl examples | | Forwarding Policy | Semantic-Forward vs Raw-Forward, monotonic enforcement | | Understanding Run Output | How to read envelopes, PROV graphs, audits, metrics, and validation results | | Local Development | Running without AWS (SQLite backend) | | Security | API authentication roadmap (API key → IAM → Cognito → mTLS) | | Validation | Protocol validation, audit checks, UserML, PROV, metrics | | Test Suite | Unit tests: storage backend, local mode, ontology validation |

Crew Documentation

| Crew | Article | Description | |------|---------|-------------| | Healthcare | Art. 14 | 5 agents, 3 crews, Semantic-Forward, temporal oversight proof | | Education | Art. 13 | 4 agents, 3 isolated flows, workflow isolation + negative proof | | Recommendation | LOW-risk | 3 agents, 1 crew, Raw-Forward, full provenance | | Finance | Annex III 5(b) | 7 agents, 4 crews, composite compliance (all 4 patterns) |

Scenario Diagrams

Reference figures from the PAC-AI paper (IADIS AIS 2026):

| Figure | Scenario | Description | |--------|----------|-------------| | | Healthcare (Art. 14) | Temporal provenance proving meaningful human oversight — physician accessed source documents independently before reviewing AI recommendation | | | Education (Art. 13) | Negative provenance proof — two isolated subgraphs show grading used only text/rubric (no identity data) |

License

Apache 2.0