CAOS — Sistema Operacional de Garantia ao Cliente

Responda de uma vez aos questionários de segurança que seus clientes enviam a você.

Toda empresa que lida com dados de clientes recebe as mesmas solicitações repetidamente: questionários de segurança, avaliações de privacidade, análises de risco de fornecedores, due diligence de compras, solicitações de evidências. A maioria das organizações responde manualmente — uma planilha do cliente, uma pasta de políticas, uma thread de e-mail e a memória de alguém sobre o que foi dito da última vez.

O CAOS transforma isso em um sistema de registro. Questionários tornam-se trabalho estruturado e respondível. Respostas concluídas e seus documentos de conformidade tornam-se um corpus pesquisável e citável. O próximo questionário começa a partir do que você já disse, com cada afirmação rastreável até o documento ou resposta anterior de onde veio.

Ele é auto-hospedado. Suas políticas, suas respostas e os questionários dos seus clientes permanecem na sua infraestrutura.

Status: v0. O CAOS roda em produção, mas este repositório é recém-público. Interfaces, schema e configuração ainda estão em movimento. Contribuições externas ainda não estão abertas — veja Contribuindo.

O que ele faz

Lê questionários sem adivinhar. Envie um XLSX do cliente e o CAOS o renderiza fielmente — planilhas, linhas, células, colunas ocultas, listas suspensas de validação. Em seguida, você marca quais linhas são respondíveis e quais células preencher, em intervalos em vez de uma por uma. Não existe parser por cliente, porque não existe padrão: uma linha em negrito pode ser uma pergunta, uma coluna em branco pode ser o alvo da resposta, e toda heurística que acerta em um workbook erra confiantemente em outro.

Constrói um corpus a partir do trabalho que você já concluiu. Fechar um questionário publica suas linhas respondidas como Q&A reutilizável. Políticas, certificações e relatórios enviados tornam-se passagens citáveis. Ambos são versionados de forma imutável, de modo que uma resposta enviada no trimestre passado ainda se explica em relação ao documento vigente na época.

Encontra a resposta anterior certa. A recuperação executa busca lexical e semântica em conjunto, funde suas classificações e reclassifica os principais candidatos. A linguagem de conformidade precisa de ambas: tokens exatos como "SOC 2 Type II", que embeddings borram, e paráfrases que a busca por palavras-chave perde completamente.

Redige respostas fundamentadas. Opcional. O modelo pesquisa seu corpus por meio de ferramentas limitadas e na lista de permissões e redige uma resposta com citações — além de um rótulo indicando de onde veio sua autoridade: Knowledge grounded, Mixed, General guidance ou Based on current answer. Uma resposta General guidance não faz nenhuma afirmação sobre sua organização, e diz isso.

Responde no Google Chat. Um comando de barra /ciso acessa o mesmo corpus fundamentado, com um link de volta para uma conversa persistente no aplicativo web.

Exporta de volta para o próprio workbook do cliente. As respostas são gravadas na estrutura de arquivo original, nas células que você mapeou — não em uma aproximação no formato do CAOS.

Registra tudo. Um log de auditoria somente de acréscimo com imutabilidade imposta pelo banco de dados, carregando valores exatos de antes e depois das respostas.

Módulos

O CAOS é organizado em nove módulos de domínio. Três deles — Evidence, Knowledge e Tasks — são globais: não pertencem a projetos, porque seu valor vem de atravessar engajamentos.

Arquitetura

                          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 com pgvector, Redis, workers Taskiq. Cada módulo se divide em domain → application → infrastructure → presentation, com dependências unidirecionais. domain não depende de nada.

Frontend — React 19, TypeScript, Vite, Tailwind v4, shadcn/ui, Zustand. O estado de sessão e shell de toda a aplicação vive em src/app; o estado de funcionalidades e de cache do servidor vive em stores de funcionalidades; fluxos de trabalho longos em páginas vivem em controllers de funcionalidades.

Ambos os canais de recuperação vivem no PostgreSQL. Não há um banco de dados vetorial separado — um único armazenamento significa um único limite de transação e um único backup.

Fornecedores externos são mantidos à distância. Cada integração separa um Protocolo de Plataforma (o que o CAOS espera, em linguagem de produto), um Protocolo de Adaptador e uma Implementação de Fornecedor — a única camada que importa o SDK. É por isso que embedding e reranking rodam em modelos locais fixados ou no Bedrock, sem que nenhum código de aplicação saiba qual deles.

Detalhe: arquitetura · fronteiras de integração

Como os dados fluem

Um documento torna-se recuperável. Upload → versão imutável → job de ingestão durável → commit → despacho para um worker → extração de passagens de ≤1.500 caracteres, cada uma mantendo um localizador de citação (página PDF, parágrafo DOCX, planilha/linha/célula XLSX) → geração de embeddings → pesquisável. O job faz commit antes do despacho, portanto uma falha de fila torna-se um estado visível e repetível em vez de uma linha pendente invisível.

Um questionário torna-se trabalho respondido. Upload → visualizações fiéis de linhas → você mapeia linhas e alvos de resposta → um item de workspace por linha respondível, cada um apontando para suas células de origem exatas → rascunhos com salvamento automático → conclusão explícita com compare-and-set de revisão esperada, de modo que uma aba desatualizada receba 409 em vez de sobrescrever um colega.

Trabalho concluído torna-se Knowledge. Fechar um questionário (ou um projeto, que fecha todos eles) publica as linhas respondidas como Q&A reutilizável. Linhas não respondidas não publicam nada. O workbook bruto nunca é ingerido — é trabalho operacional, não material de fundamentação.

Uma pergunta torna-se uma resposta fundamentada. A recuperação lexical e semântica roda em paralelo → a Fusão de Classificação Recíproca combina seus ranks → boost de tags → filtros de exclusão → reclassificação de uma janela limitada de 50 candidatos → o modelo busca, inspeciona e busca novamente dentro de um orçamento fixo → um rascunho com citações apontando para versões de origem imutáveis e um rótulo de fundamentação.

Cada estágio degrada em direção a um modo mais fraco, porém honesto: reranker fora do ar significa ordem fundida e sem chip de confiança; embeddings fora do ar significam fallback lexical, reportado como tal.

Detalhe: fluxo de dados

Início rápido

Pré-requisitos: Docker com Compose. Para trabalho no frontend, Node.js >=22.22.0 e pnpm 11.9.0. O desenvolvimento do backend também usa uv.

Não é necessária conta AWS nem provedor de LLM — a geração está desligada por padrão e tudo abaixo funciona sem ela.

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

Substitua o espaço reservado BACKEND_USERS_SECRET em backend/.env por pelo menos 32 bytes aleatórios:

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

Inicie PostgreSQL, Redis, a API e os workers. As migrações são executadas automaticamente pelo serviço migrator:

cd backend && docker compose up --build

A primeira execução baixa ~500 MB de artefatos de modelo fixados. A API estará então em http://localhost:18800, o Swagger em /api/docs e o PostgreSQL na porta 15432 do host.

O CAOS não tem página de cadastro — crie o primeiro administrador a partir do host:

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

cd frontend && pnpm install && pnpm dev

Abra http://localhost:5173.

Use localhost consistentemente tanto para o frontend quanto para a API. Os cookies de sessão são limitados ao host; portanto, misturar localhost e 127.0.0.1 derruba sua sessão silenciosamente — o problema mais comum na configuração local.

A seguir: o Tutorial de primeiros passos leva daqui até um questionário respondido e exportado.

Padrões que vale a pena conhecer

• Embeddings e reranking usam local por padrão no Compose (Nomic fixado e um cross-encoder MiniLM, embutidos na imagem). Em produção, o padrão é AWS Bedrock. O runtime nunca baixa modelos.
• A geração de respostas está desligada. Defina BACKEND_KNOWLEDGE_GENERATION_PROVIDER e _MODEL para ativá-la.
• O Google Chat está desligado e exige Google SSO para ser ativado em produção.

Todas as configurações estão documentadas inline em backend/.env.example e agrupadas na referência de configuração.

Desenvolvimento

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

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

Esta distribuição publicada não inclui a suíte de testes interna do CAOS. Lint, verificação de tipos e build limpa são os portões de verificação aqui.

Use ./caos-cli para todo trabalho de migração em vez de invocar o Alembic diretamente — ele seleciona o ambiente, o contêiner e o banco de dados corretos.

Convenções do projeto que não são óbvias a partir do código estão em AGENTS.md, com regras específicas de módulo em cada AGENTS.md do próprio módulo.

Documentação

docs/ segue Diátaxis — cada página é um tutorial, um how-to, uma referência ou uma explicação, e os quatro são mantidos separados.

Segurança

Por favor, não abra issues públicas para vulnerabilidades. Veja SECURITY.md para relato privado.

Contribuindo

O CAOS é de código aberto, mas ainda não está aberto para contribuições externas. Esperamos aceitar pull requests externos em 2027. Até lá, relatos de bugs e perguntas por meio de issues são bem-vindos e genuinamente úteis — veja CONTRIBUTING.md.

Licença

Apache License 2.0. Copyright 2026 DigiCred Technologies Pvt Ltd.