Reports & Deployer Manual¶

Two documents a regulator or an auditor will ask for, generated from what the deployment actually recorded: a compliance report covering a period (statistics, oversight, chain state, per-framework mapping) and a deployer transparency manual describing the current system in plain language, as Article 13 requires. Both come as structured data or as a rendered PDF.

Compliance Report¶

What it does. Aggregates everything the deployment recorded — call statistics, per-axis detection rates, oversight activity, audit-chain state, FRIA status — into one report, mapped article by article against the legal frameworks you select.

Three endpoints, same request body:

Call it¶

# structured data
curl -s -X POST http://localhost:8080/v1/glad/report \
  -H "Content-Type: application/json" \
  -d '{
    "company_name":      "ACME Corporation",
    "company_country":   "IT",
    "model_description": "Customer Support AI",
    "applicable_laws":   ["EU_AI_ACT", "GDPR"],
    "from_date":         "2026-01-01",
    "to_date":           "2026-06-30",
    "contact_email":     "ai-compliance@acme.com",
    "language":          "en"
  }' | jq

# PDF, inline
curl -s -X POST http://localhost:8080/v1/glad/report/pdf \
  -H "Content-Type: application/json" \
  -d '{"company_name":"ACME Corporation","company_country":"IT",
       "applicable_laws":["EU_AI_ACT","GDPR"]}' \
  --output compliance_report.pdf

import time, httpx

c = httpx.Client(base_url="http://localhost:8080", timeout=300)
body = {
    "company_name": "ACME Corporation",
    "company_country": "IT",
    "model_description": "Customer Support AI",
    "applicable_laws": ["EU_AI_ACT", "GDPR"],
    "from_date": "2026-01-01",
    "to_date": "2026-06-30",
    "contact_email": "ai-compliance@acme.com",
}

# Async is the safe path — a big render outlives most connection timeouts.
job = c.post("/v1/glad/report/pdf/async", json=body).json()
while True:
    st = c.get(f"/v1/glad/doc-jobs/{job['job_id']}/status",
               params={"token": job["token"]}).json()
    if st["status"] == "error":
        raise RuntimeError(st.get("error", "render failed"))
    if st["status"] == "done":
        break
    time.sleep(2)

pdf = c.get(f"/v1/glad/doc-jobs/{job['job_id']}/download", params={"token": job["token"]})
open("compliance_report.pdf", "wb").write(pdf.content)

const body = {
  company_name: "ACME Corporation",
  company_country: "IT",
  model_description: "Customer Support AI",
  applicable_laws: ["EU_AI_ACT", "GDPR"],
  from_date: "2026-01-01",
  to_date: "2026-06-30",
}

const job = await fetch("http://localhost:8080/v1/glad/report/pdf/async", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(body),
}).then(r => r.json())

for (;;) {
  const st = await fetch(
    `http://localhost:8080/v1/glad/doc-jobs/${job.job_id}/status?token=${job.token}`,
  ).then(r => r.json())
  if (st.status === "error") throw new Error(st.error)
  if (st.status === "done") break
  await new Promise(r => setTimeout(r, 2000))
}

const blob = await fetch(
  `http://localhost:8080/v1/glad/doc-jobs/${job.job_id}/download?token=${job.token}`,
).then(r => r.blob())

What comes back¶

POST /v1/glad/report returns the report as structured data — a report_id, the period covered, the call statistics, the per-framework mapping, and the paths of any artifacts written. The /pdf variants return the file itself.

Request fields¶

Every field has a default; a bare {} produces a report for the whole history under the deployment's configured identity.

Report structure¶

Deployer Transparency Manual¶

What it does. Generates a plain-language instructions-for-use document: what the system does, what it cannot do, how it is overseen, what is logged and for how long. This is the EU AI Act Article 13 transparency artifact, and the Article 26(1) instructions the deployer is required to hold.

Unlike the compliance report it describes the current configuration, not a historical period — so it takes no dates.

curl -s -X POST http://localhost:8080/v1/glad/deployer-manual/pdf \
  -H "Content-Type: application/json" \
  -d '{
    "company_name":    "ACME Corporation",
    "company_country": "IT",
    "contact_email":   "ai-compliance@acme.com",
    "applicable_laws": ["EU_AI_ACT", "GDPR"],
    "retention_months": 6,
    "language":        "en"
  }' --output deployer_manual.pdf

manual = c.post("/v1/glad/deployer-manual", json={
    "company_name": "ACME Corporation",
    "company_country": "IT",
    "contact_email": "ai-compliance@acme.com",
    "applicable_laws": ["EU_AI_ACT", "GDPR"],
}).json()          # structured data

pdf = c.post("/v1/glad/deployer-manual/pdf", json={
    "company_name": "ACME Corporation",
    "company_country": "IT",
    "contact_email": "ai-compliance@acme.com",
})
open("deployer_manual.pdf", "wb").write(pdf.content)

const res = await fetch("http://localhost:8080/v1/glad/deployer-manual/pdf", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    company_name: "ACME Corporation",
    company_country: "IT",
    contact_email: "ai-compliance@acme.com",
  }),
})
const blob = await res.blob()

Request fields¶

Both endpoints also have an /async variant (POST /v1/glad/deployer-manual/pdf/async) that returns {job_id, token} — same document-job flow as the compliance report.

Manual contents¶

Provider Identity¶

GET /v1/glad/provider-identity¶

Returns machine-readable provider identity information — the system's "identity card" for regulatory systems.

curl http://localhost:8080/v1/glad/provider-identity

{
  "provider": "Geodesia AI",
  "system_name": "Geodesia G-1",
  "system_version": "1.0.0",
  "model_family": "Geodesia G-1 Companion",
  "eu_ai_act_risk_class": "high",
  "eu_conformity_basis": ["Art. 9", "Art. 10", "Art. 11", "Art. 12", "Art. 13", "Art. 14"],
  "supported_frameworks": ["EU_AI_ACT", "GDPR", "ISO_42001", ...],
  "contact": "compliance@geodesia.ai"
}

Threshold Preferences¶

The deployer-level threshold profile: four scalar thresholds that apply where no per-Application policy overrides them. Distinct from the nine-axis per-Application policy, which lives on the control plane.

GET /v1/glad/threshold-prefs¶

What it does. Returns the stored profile, or the built-in defaults if that profile has never been written.

curl -s "http://localhost:8080/v1/glad/threshold-prefs?profile_id=default" | jq

import httpx
prefs = httpx.get("http://localhost:8080/v1/glad/threshold-prefs",
                  params={"profile_id": "default"}).json()
print(prefs)

const prefs = await fetch("http://localhost:8080/v1/glad/threshold-prefs?profile_id=default")
  .then(r => r.json())

What comes back

{
  "profile_id": "default",
  "prompt_safety_threshold": 0.731,
  "answer_safety_threshold": 0.142,
  "halluc_threshold": 0.500,
  "combined_halluc_threshold": 0.782,
  "updated_at": "2026-06-18T09:00:00Z"
}

updated_at is absent until the profile has been written at least once.

POST /v1/glad/threshold-prefs¶

What it does. A partial update — send only the thresholds you want to move. Unknown keys are ignored; a body with none of the four known keys returns 400.

curl -s -X POST "http://localhost:8080/v1/glad/threshold-prefs?profile_id=default" \
  -H "Content-Type: application/json" \
  -d '{"prompt_safety_threshold": 0.80, "halluc_threshold": 0.617}' | jq

updated = httpx.post("http://localhost:8080/v1/glad/threshold-prefs",
                     params={"profile_id": "default"},
                     json={"prompt_safety_threshold": 0.80,
                           "halluc_threshold": 0.617}).json()

const updated = await fetch(
  "http://localhost:8080/v1/glad/threshold-prefs?profile_id=default",
  { method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ prompt_safety_threshold: 0.80, halluc_threshold: 0.617 }) },
).then(r => r.json())

What comes back — the complete profile after the merge.

profile_id is a query parameter, not a body field, and defaults to default.

Data Retention¶

GET /v1/glad/retention/status¶

What it does. Reports the retention policy in force and how much data is inside, at, or past its window. Takes no parameters.

curl -s http://localhost:8080/v1/glad/retention/status | jq

r = httpx.get("http://localhost:8080/v1/glad/retention/status").json()
if r["overdue_calls"]:
    print(f"{r['overdue_calls']} records are past their retention window")

const r = await fetch("http://localhost:8080/v1/glad/retention/status").then(r => r.json())
if (r.overdue_calls) console.warn(`${r.overdue_calls} records past retention`)

What comes back

{
  "generated_at": "2026-06-18T09:00:00+00:00",
  "total_calls": 48291,
  "active_calls": 48291,
  "overdue_calls": 0,
  "policy": { "default_months": 6 },
  "applicable_laws": ["EU_AI_ACT", "GDPR"],
  "tiers": {
    "standard": { "total": 48000, "archived": 0, "overdue": 0 },
    "extended": { "total": 291,   "archived": 0, "overdue": 0 }
  }
}

Configure retention periods in config.yaml.

License Tokens¶

Customer licence tokens are managed under /v1/glad/license-tokens/… and documented in Licensing & Entitlements. Creating, listing and revoking a token requires the X-Geodesia-Admin-Key header; validation (GET/POST /v1/glad/license-tokens/validate) does not.