Appearance
Regulatory Library — Hands-On Lab
Estimated duration: ~40 minutes
Audience: Solutions engineers, platform admins, compliance-minded developers
Prerequisites: GhostAI backend running (default http://localhost:8000), curl, python3 -m json.tool optional for pretty output. Steps that adopt, annotate, bookmark, posture, export PDF, or change alerts require an authenticated user (JWT Bearer token or session cookie). With AUTH_DISABLED development settings, the server still resolves a single-user tenant context for those calls—verify your environment.
Feature flag: regulatory_library must be enabled for the tenant when enforcement is on in your deployment.
Environment
bash
export BASE_URL="http://localhost:8000"
export RL="$BASE_URL/api/regulatory-library"
# Obtain a JWT after login (browser DevTools → Application → Cookies → access_token,
# or your SSO flow). Paste the raw JWT string.
export TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
AUTH=( -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" )Public catalog calls omit $AUTH. Authenticated calls use "${AUTH[@]}".
Step 1: List all frameworks (~3 min)
Returns lightweight summaries: id, abbreviation, full_name, description, category, jurisdiction (type, regions), jurisdiction_flag, industries, ghostai_readiness_level, tags, status.
bash
curl -s "$RL" | python3 -m json.tool | head -n 80Expected: JSON array with dozens of frameworks; note a few id values (for example hipaa, gdpr, pci_dss) for later steps.
Count only:
bash
curl -s "$RL" | python3 -c "import sys,json; print(len(json.load(sys.stdin)))"Step 2: Search and filter (~5 min)
Endpoint: GET /api/regulatory-library/search
Query parameters (all optional):
| Parameter | Purpose |
|---|---|
q | Text search across abbreviation, full name, description, citation, GhostAI support text, tags, requirement titles/descriptions |
category | Exact category match (case-insensitive), e.g. Healthcare, Privacy, Financial, AI Governance |
jurisdiction | jurisdiction.type, e.g. us_federal, eu, us_state, industry |
jurisdiction_region | Substring membership in jurisdiction.regions, e.g. CA, NY |
industry | Framework must list the industry, e.g. healthcare, financial |
data_type | Framework must list protected data type id, e.g. phi, pii, npi |
readiness | ghostai_readiness_level: full, partial, or awareness |
Examples:
bash
# Free-text
curl -s "$RL/search?q=tokenization" | python3 -m json.tool | head -n 60
# Healthcare category + EU jurisdiction
curl -s "$RL/search?category=Healthcare&jurisdiction=eu" | python3 -m json.tool | head -n 60
# US state law where regions include CA
curl -s "$RL/search?jurisdiction=us_state&jurisdiction_region=CA" | python3 -m json.tool
# Frameworks touching PHI
curl -s "$RL/search?data_type=phi" | python3 -m json.tool | head -n 40
# High readiness only
curl -s "$RL/search?readiness=full" | python3 -m json.tool | head -n 40Reverse applicability (scored): GET /api/regulatory-library/applicable
Comma-separated lists:
bash
curl -s "$RL/applicable?industries=healthcare,financial&data_types=phi,pii&jurisdictions=us_federal,eu" \
| python3 -m json.tool | head -n 80Expected: Summaries plus relevance_score (higher when more dimensions match). Frameworks are sorted by score descending.
Supporting discovery:
bash
curl -s "$RL/categories" | python3 -m json.tool
curl -s "$RL/data-types" | python3 -m json.tool | head -n 50Step 3: Framework detail (~4 min)
bash
curl -s "$RL/hipaa" | python3 -m json.toolExpected fields (in addition to summary fields): enforcement_body, penalty_summary, max_penalty (amount, unit, basis), key_requirements (each with title, description, ghostai_feature), protected_data_types, applicable_to, related_frameworks (id, relationship), citation, effective_date, last_amended, version, external_url, ghostai_support, ghostai_features, upcoming_changes, last_verified.
Try a second id:
bash
curl -s "$RL/gdpr" | python3 -m json.tool | head -n 100404 check:
bash
curl -s -o /dev/null -w "%{http_code}\n" "$RL/not_a_real_framework_id"Step 4: Graph, timeline, and penalties (~6 min)
Relationship graph
GET /api/regulatory-library/graph returns nodes and edges.
bash
curl -s "$RL/graph" | python3 -c "
import json,sys
d=json.load(sys.stdin)
print('nodes', len(d['nodes']), 'edges', len(d['edges']))
print('sample node', d['nodes'][0])
print('sample edge', d['edges'][0])
"Node fields: id, abbreviation, category, full_name, ghostai_readiness_level, connection_count.
Edge fields: source, target, relationship (complements, extends, supersedes, overlaps, implements, …).
Timeline
bash
curl -s "$RL/timeline" | python3 -m json.tool | head -n 60Row shape: framework_id, abbreviation, category, effective_date, last_amended, upcoming_changes — sorted by effective_date.
Penalties (frameworks with structured penalty data)
bash
curl -s "$RL/penalties" | python3 -m json.tool | head -n 80Row shape: framework_id, abbreviation, category, penalty_summary, max_penalty. Only frameworks that have max_penalty defined in the catalog appear in this list (there is no row with max_penalty: null).
Step 5: Adopt a framework (~5 min)
Adoption merges recommended entity types and thresholds into the user’s detection settings and appends the framework id to the stored regulations list.
bash
curl -s -X POST "${AUTH[@]}" "$RL/hipaa/adopt" | python3 -m json.toolTypical success body: status adopted, framework_id, abbreviation, entities_added, entities_total, thresholds_applied, total_adopted.
Idempotent repeat: status already_adopted.
Rollback:
bash
curl -s -X POST "${AUTH[@]}" "$RL/hipaa/unadopt" | python3 -m json.toolTypical body: status unadopted, entities_removed (orphaned entities), total_adopted.
Re-adopt once before Step 7 if you want bulk-adopt to have a clear “already_adopted” example:
bash
curl -s -X POST "${AUTH[@]}" "$RL/hipaa/adopt" | python3 -m json.toolAudit (server-side): COMPLIANCE_FRAMEWORK_ADOPT, COMPLIANCE_FRAMEWORK_UNADOPT.
Step 6: Compliance posture (~4 min)
bash
curl -s "${AUTH[@]}" "$RL/posture" | python3 -m json.tool | head -n 80Each element: framework_id, abbreviation, category, is_relevant (true if org vertical is in framework industries), readiness (configured | partial | not_configured), configured_features, missing_features, total_features, configured_count.
Filter locally for a quick view:
bash
curl -s "${AUTH[@]}" "$RL/posture" | python3 -c "
import json,sys
for row in json.load(sys.stdin):
if row.get('is_relevant'):
print(row['abbreviation'], row['readiness'], row['configured_count'], '/', row['total_features'])
"Step 7: Bulk adopt (~4 min)
bash
curl -s -X POST "${AUTH[@]}" "$RL/bulk-adopt" \
-d '{"framework_ids":["hitech","gdpr"]}' | python3 -m json.toolResponse: results (per-id status adopted, already_adopted, or not_found), total_adopted, frameworks_added.
Audit: COMPLIANCE_BULK_ADOPT when at least one new framework is adopted.
Step 8: Annotations and bookmarks (~6 min)
Bookmarks (toggle — user-scoped)
List bookmarked framework ids:
bash
curl -s "${AUTH[@]}" "$RL/bookmarks" | python3 -m json.toolToggle on:
bash
curl -s -X POST "${AUTH[@]}" "$RL/bookmarks/gdpr" | python3 -m json.toolExpected: {"bookmarked": true} or false on second call.
Annotations (org-scoped; admin or owner only)
List:
bash
curl -s "${AUTH[@]}" "$RL/annotations/gdpr" | python3 -m json.toolCreate and capture the returned id:
bash
export ANN_ID="$(curl -s -X POST "${AUTH[@]}" "$RL/annotations/gdpr" \
-d '{"text":"Legal review scheduled Q2; confirm BAA template with counsel."}' | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")"
echo "ANN_ID=$ANN_ID"
curl -s "${AUTH[@]}" "$RL/annotations/gdpr" | python3 -m json.toolExpected: ANN_ID is a UUID string; the list call includes the new note with author_email / author_name when joined to users.
Delete:
bash
curl -s -X DELETE "${AUTH[@]}" "$RL/annotations/$ANN_ID" | python3 -m json.toolExpected: {"deleted": true}.
Step 9: Export posture PDF, change alerts, and glossary (~5 min)
Posture PDF
bash
curl -s -L "${AUTH[@]}" "$RL/posture/export" -o ghostai-compliance-posture.pdf
file ghostai-compliance-posture.pdfExpected: PDF file; Content-Disposition suggests filename ghostai-compliance-posture.pdf.
Audit: COMPLIANCE_REPORT_EXPORT.
If the server returns HTTP 500 with “reportlab not installed”, install backend dependency reportlab and retry.
Change alerts (adopted frameworks with upcoming_changes)
bash
curl -s "${AUTH[@]}" "$RL/change-alerts" | python3 -m json.toolExpected: Array of {framework_id, abbreviation, upcoming_changes, last_amended} for adopted frameworks that have catalog text in upcoming_changes. Empty array is normal if nothing adopted or no upcoming text.
Glossary
All terms:
bash
curl -s "$RL/glossary" | python3 -m json.tool | head -n 40Single term by id:
bash
curl -s "$RL/glossary/covered_entity" | python3 -m json.toolShape: id, term, definition, frameworks, related_terms.
Path reference (from regulatory_library.py)
| Method | Path |
|---|---|
| GET | /api/regulatory-library |
| GET | /api/regulatory-library/search |
| GET | /api/regulatory-library/categories |
| GET | /api/regulatory-library/data-types |
| GET | /api/regulatory-library/graph |
| GET | /api/regulatory-library/timeline |
| GET | /api/regulatory-library/penalties |
| GET | /api/regulatory-library/glossary |
| GET | /api/regulatory-library/glossary/{term_id} |
| GET | /api/regulatory-library/applicable |
| GET | /api/regulatory-library/bookmarks |
| POST | /api/regulatory-library/bookmarks/{framework_id} |
| GET | /api/regulatory-library/annotations/{framework_id} |
| POST | /api/regulatory-library/annotations/{framework_id} |
| DELETE | /api/regulatory-library/annotations/{annotation_id} |
| GET | /api/regulatory-library/posture |
| GET | /api/regulatory-library/change-alerts |
| POST | /api/regulatory-library/{framework_id}/adopt |
| POST | /api/regulatory-library/{framework_id}/unadopt |
| POST | /api/regulatory-library/bulk-adopt |
| GET | /api/regulatory-library/posture/export |
| GET | /api/regulatory-library/{framework_id} |
Success criteria
- You can list and search frameworks with at least two different filter dimensions.
- You can retrieve full detail for one framework and explain
key_requirements[].ghostai_feature. - You can interpret graph nodes/edges and one timeline entry.
- You can adopt and unadopt and describe what changes in detection settings at a high level.
/posturereturns rows withreadinessandis_relevantmeaningful for your org vertical./bulk-adoptreturns per-id statuses.- Bookmarks toggle; annotations CRUD works with an admin-capable token.
/posture/exportproduces a PDF whenreportlabis available./change-alertsand/glossaryreturn sensible JSON for your tenant state.
Lab wrap-up
Regulatory Library data is reference catalog on read; adopt, bulk-adopt, unadopt, and posture export are state-changing and emit audit events suitable for SIEM or compliance review. Keep JWTs out of shell history in shared environments—prefer short-lived tokens or a .env file excluded from version control.