CAOS — Customer Assurance Operating System

Answer the security questionnaires your customers send you, once.

Every company that handles customer data gets the same requests over and over: security questionnaires, privacy assessments, vendor risk reviews, procurement due diligence, evidence requests. Most organizations answer them by hand — a spreadsheet from the customer, a folder of policies, an email thread, and someone's memory of what they said last time.

CAOS turns that into a system of record. Questionnaires become structured, answerable work. Finished answers and your compliance documents become a searchable, citable corpus. The next questionnaire starts from what you already said, with every claim traceable to the document or prior answer it came from.

It is self-hosted. Your policies, your answers, and your customers' questionnaires stay on your infrastructure.

Status: v0. CAOS runs in production, but this repository is newly public. Interfaces, schema, and configuration are still moving. External contributions are not open yet — see Contributing.

What it does

Reads questionnaires without guessing. Upload a customer's XLSX and CAOS renders it faithfully — sheets, rows, cells, hidden columns, validation dropdowns. You then mark which rows are answerable and which cells to fill, in ranges rather than one at a time. There is no per-customer parser, because there is no standard: a bold row can be a question, a blank column can be the answer target, and every heuristic that gets one workbook right gets another confidently wrong.

Builds a corpus from work you already finished. Closing a questionnaire publishes its answered rows as reusable Q&A. Uploaded policies, certifications, and reports become citable passages. Both are versioned immutably, so an answer you sent last quarter still explains itself against the document that was current then.

Finds the right prior answer. Retrieval runs lexical and semantic search together, fuses their rankings, and reranks the top candidates. Compliance language needs both: exact tokens like "SOC 2 Type II" that embeddings smear, and paraphrases that keyword search misses entirely.

Drafts grounded answers. Optional. The model searches your corpus through bounded, allow-listed tools and drafts an answer with citations — plus a label saying where its authority came from: Knowledge grounded, Mixed, General guidance, or Based on current answer. A General guidance answer makes no claim about your organization, and says so.

Answers in Google Chat. A /ciso slash command hits the same grounded corpus, with a link back into a persistent conversation in the web app.

Exports back into the customer's own workbook. Answers are written into the original file structure, in the cells you mapped — not into a CAOS-shaped approximation of it.

Records everything. An append-only audit log with database-enforced immutability, carrying exact before-and-after answer values.

Modules

CAOS is organised into nine domain modules. Three of them — Evidence, Knowledge, and Tasks — are global: they are not owned by projects, because their value comes from crossing engagements.

Architecture

                          Internet
                             │
                       ┌─────┴─────┐
                       │   nginx   │   TLS · static frontend · /api proxy
                       └─────┬─────┘
              ┌──────────────┼──────────────┐
              │              │              │
        ┌─────┴─────┐  ┌─────┴─────┐  ┌─────┴──────┐
        │ Frontend  │  │    API    │  │  Taskiq    │
        │  React    │  │  FastAPI  │  │  workers   │
        │  static   │  │  :18800   │  │            │
        └───────────┘  └─────┬─────┘  └─────┬──────┘
                             │              │
                       ┌─────┴──────────────┴─────┐
                       │                          │
                 ┌─────┴──────┐            ┌──────┴─────┐
                 │ PostgreSQL │            │   Redis    │
                 │  pgvector  │            │ queue+cache│
                 └────────────┘            └────────────┘
                             │
                       ┌─────┴─────┐
                       │ Providers │   Bedrock · local models · Google Chat
                       └───────────┘

Backend — Python 3.12+, FastAPI, SQLAlchemy 2 async, PostgreSQL with pgvector, Redis, Taskiq workers. Each module splits into domain → application → infrastructure → presentation, with one-way dependencies. domain depends on nothing.

Frontend — React 19, TypeScript, Vite, Tailwind v4, shadcn/ui, Zustand. App-wide session and shell state live in src/app; feature and server-cache state live in feature stores; long-running page workflows live in feature controllers.

Both retrieval channels live in PostgreSQL. There is no separate vector database — one store means one transaction boundary and one backup.

External vendors are kept at arm's length. Every integration separates a Platform Protocol (what CAOS expects, in product language), an Adapter Protocol, and a Vendor Implementation — the only layer importing the SDK. This is why embedding and reranking run on pinned local models or on Bedrock with no application code aware of which.

Detail: architecture · integration boundaries

How data flows

A document becomes retrievable. Upload → immutable version → durable ingestion job → commit → dispatch to a worker → extract passages of ≤1,500 characters, each keeping a citation locator (PDF page, DOCX paragraph, XLSX sheet/row/cell) → generate embeddings → searchable. The job commits before dispatch, so a queue failure becomes a visible retryable state rather than an invisible pending row.

A questionnaire becomes answered work. Upload → faithful row views → you map rows and answer targets → one workspace item per answerable row, each pointing at its exact source cells → autosave drafts → explicit completion with an expected-revision compare-and-set, so a stale tab gets 409 rather than overwriting a colleague.

Finished work becomes Knowledge. Closing a questionnaire (or a project, which closes all of them) publishes answered rows as reusable Q&A. Unanswered rows publish nothing. The raw workbook is never ingested — it is operational work, not grounding material.

A question becomes a grounded answer. Lexical and semantic retrieval run in parallel → Reciprocal Rank Fusion combines their ranks → tag boost → exclusion filters → rerank a bounded 50-candidate window → the model searches, inspects, and searches again within a fixed budget → a draft with citations pointing at immutable source versions, and a grounding label.

Every stage degrades toward a weaker but honest mode: reranker down means fused order and no confidence chip; embeddings down means lexical fallback, reported as such.

Detail: data flow

Quick start

Prerequisites: Docker with Compose. For frontend work, Node.js >=22.22.0 and pnpm 11.9.0. Backend development also uses uv.

No AWS account or LLM provider needed — generation is off by default and everything below works without it.

git clone https://github.com/DigiCred-OSS/caos-os.git
cd caos-os/backend
cp .env.example .env

Replace the BACKEND_USERS_SECRET placeholder in backend/.env with at least 32 random bytes:

python3 -c 'import secrets; print(secrets.token_urlsafe(48))'

Start PostgreSQL, Redis, the API, and the workers. Migrations run automatically via the migrator service:

cd backend && docker compose up --build

First run downloads ~500 MB of pinned model artifacts. The API is then on http://localhost:18800, Swagger at /api/docs, PostgreSQL on host port 15432.

CAOS has no sign-up page — create the first administrator from the host:

./caos-cli user create-superadmin --email [email protected]

cd frontend && pnpm install && pnpm dev

Open http://localhost:5173.

Use localhost consistently for both frontend and API. Session cookies are host-scoped, so mixing localhost and 127.0.0.1 silently drops your session — the most common local-setup problem.

Next: Getting started tutorial walks from here to an answered, exported questionnaire.

Defaults worth knowing

• Embeddings and reranking default to local in Compose (pinned Nomic and a MiniLM cross-encoder, baked into the image). Production defaults to AWS Bedrock. Runtime never downloads models.
• Answer generation is off. Set both BACKEND_KNOWLEDGE_GENERATION_PROVIDER and _MODEL to enable it.
• Google Chat is off, and requires Google SSO to enable in production.

Every setting is documented inline in backend/.env.example and grouped in the configuration reference.

Development

cd backend && uv sync --locked
uv run ruff check caos
uv run mypy caos

cd frontend && pnpm install && pnpm lint && pnpm build

This published distribution does not include CAOS's internal test suite. Lint, type checking, and a clean build are the verification gates here.

Use ./caos-cli for all migration work rather than invoking Alembic directly — it selects the right environment, container, and database.

Project conventions that are not obvious from the code are in AGENTS.md, with module-specific rules in each module's own AGENTS.md.

Documentation

docs/ follows Diátaxis — every page is a tutorial, a how-to, a reference, or an explanation, and the four are kept apart.

Security

Please do not open public issues for vulnerabilities. See SECURITY.md for private reporting.

Contributing

CAOS is open source, but not yet open for external contributions. We expect to accept outside pull requests in 2027. Until then, bug reports and questions via issues are welcome and genuinely useful — see CONTRIBUTING.md.

License

Apache License 2.0. Copyright 2026 DigiCred Technologies Pvt Ltd.