jhcontext-crewai

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

Multi-agent healthcare, education, recommendation, finance, and hiring scenarios that demonstrate EU AI Act compliance (Annex III 4(a) and 5(b), Articles 5(1)(f)/(g), 13, 14, and 26) 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 — Fair Grading	Art. 13 — Non-Discrimination	HIGH	4 (ingestion → grading ╳ equity → audit)	Workflow isolation + negative proof (identity absent from grading)
Education — Rubric-Grounded Grading	Annex III §3 — Three-scenario audit	HIGH	6 (ingestion → scoring → feedback → equity → TA review → audit)	(A) negative proof + isolation, (B) rubric-criterion binding, (C) temporal oversight
Education — Oral Feedback (supplementary)	Annex III §3 (multimodal)	HIGH	6 (audio-ingestion → scoring → feedback → equity → TA review → audit)	Same A/B/C pattern over audio; per-sentence binding to (start_ms, end_ms) audited via verify_multimodal_binding
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
Hiring	Annex III §4(a) + Arts. 5(1)(f)/(g), 13, 14, 26	HIGH	6 (sourcing → parsing → screening → interview → ranking → decision-support) + recruiter	Quadripartite Semantic-Forward at every handoff (every task outputs a FlatEnvelope); 7 HR-specific verifiers + cohort 4/5 disparate-impact test
Benefits A3I — toeslagenaffaire anchor	GDPR Arts. 13-15 + EU AI Act Arts. 14, 86	HIGH	3 (intake → semantic extractor → decision)	Two pipelines side-by-side (Raw-Forward + Semantic-Forward) + four citizen SPARQL queries (integrity, semantic_claims, reasoning_chain, counterfactual) demonstrating what Semantic-Forward enables that Raw-Forward does not. Offline deterministic runner at agent/scenarios/benefits_a3i/simulate.py (no LLM key needed).

Offline-first healthcare scenarios

Three additional scenarios exercise PAC-AI under offline/deferred-sync semantics. Envelopes are enqueued into a local SQLite queue during connectivity outages and drained when the uplink returns — with predecessor-hash chain verification, tamper detection, and late-arrival flagging at drain time.

Scenario	Risk	Agents	Connectivity profile
Rural Cardiac Triage	HIGH (Annex III §5)	3 (physio-signal → triage → resource-allocation) + teleconsult oversight	Offline during AI pipeline → online for specialist review 10 min later
Chronic-Disease Remote Monitoring	HIGH	4 (sensor-agg → trend → alert → care-plan) + nurse oversight	Offline per daily handoff → opportunistic sync → next-day nurse review
CHW Mental-Health Screening	HIGH	3 (PHQ-9 interview → risk-classifier → referral) + district-specialist oversight	Offline during CHW home visit → online on return to clinic

See Offline healthcare scenarios for the code mapping, connectivity timelines, and the full list of outputs per run.

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-fair
python -m agent.run --scenario education-rubric
python -m agent.run --scenario education-oral       # supplementary multimodal variant
python -m agent.run --scenario recommendation
python -m agent.run --scenario finance
python -m agent.run --scenario all

Hiring scenarios (offline-friendly)

The hiring crew runs the full six-task multi-agent pipeline with FlatEnvelope round-tripping at every handoff. With HIRING_USE_MOCK_LLM=1 it reproduces deterministically without an ANTHROPIC_API_KEY:

HIRING_USE_MOCK_LLM=1 python -m agent.scenarios.hiring.run_procurement
HIRING_USE_MOCK_LLM=1 python -m agent.scenarios.hiring.run_inflight
HIRING_USE_MOCK_LLM=1 python -m agent.scenarios.hiring.run_cohort
HIRING_USE_MOCK_LLM=1 python -m agent.scenarios.hiring.run_all
python -m agent.scenarios.hiring.render_forwarding_diff   # before/after sizes per handoff

See agent/crews/hiring/README.md for the six functional agents, the FlatEnvelope→Envelope→ForwardingEnforcer→ FlatEnvelope round trip per task, and the three audit checkpoints (procurement, in-flight, cohort).

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.

Offline healthcare simulation

The offline healthcare scenarios run via a separate driver that skips the Chalice API and enqueues envelopes into a local SQLite queue during scripted connectivity outages, then drains them against the scripted timeline with chain / tamper / late-arrival verification:

export ANTHROPIC_API_KEY=sk-ant-...
python -m agent.offline_simulate triage    # Rural cardiac triage
python -m agent.offline_simulate chronic   # Chronic-disease remote monitoring
python -m agent.offline_simulate chw       # CHW mental-health screening
python -m agent.offline_simulate all

Outputs under output/runs/vNN/:

File	Description
<scenario>_envelopes.json	Per-task envelope snapshots (JSON-LD)
<scenario>_prov.ttl	W3C PROV graph (Turtle)
<scenario>_audit.json	Programmatic + narrative audit report
<scenario>_queue.sqlite	Local offline queue persisted across runs
<scenario>_sync_log.json	Drain report (queued / drained / tampered / chain_broken / late)
<scenario>_upstream_received.json	What the mock upstream actually received at drain time
healthcare_offline_summary.json	Combined summary across the three scenarios

The simulation driver is in agent/offline_simulate.py; the offline protocol layer (drop-in replacement for ContextMixin) lives in agent/protocol/ — offline_queue.py, sync_manager.py, offline_context_mixin.py, mock_upstream.py. Full detail in Offline healthcare scenarios.

Running the test suite

.venv/bin/python -m pytest tests/test_offline_layer.py tests/test_offline_flow_e2e.py -v

The offline protocol layer ships with 6 tests covering clean drain, tamper detection, chain-break detection, late-arrival flagging, and a full mixin→queue→sync end-to-end chain that runs without an Anthropic API key.

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 — Fair Grading	Art. 13	4 agents, 3 isolated flows, workflow isolation + negative proof
Education — Rubric-Grounded Grading	Annex III §3	6 agents, 4 flows, three-scenario audit (negative proof + rubric grounding + temporal oversight)
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)
Hiring	Annex III §4(a) + Arts. 5(1)(f)/(g), 13, 14, 26	6 agents, 1 crew, Quadripartite Semantic-Forward; 7 HR-specific verifiers + cohort 4/5; mock-LLM offline mode
Offline healthcare scenarios	Annex III §5	Rural triage + chronic monitoring + CHW mental-health, offline-first with scripted connectivity

Scenario Diagrams

Reference figures from the PAC-AI protocol:

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