Docs & Developer Hub

⚡ 1. Arquitetura em Duas Camadas & Fluxo de Roteamento

O DokaS1 opera em uma arquitetura desacoplada de ultra-alto desempenho, dividida entre uma camada de entrada inteligente em Go e núcleos computacionais matemáticos em Rust.

Camada Edge (Go 1.22+ / dokas1-edge)

• Autenticação & Rate Limiting Token Bucket O(1): Validação instantânea de chaves com isolamento rigoroso por tenant/aplicação.
• Balanceador de Carga Multi-Server com Cooldown: Monitora a integridade de nós aceleradores (ex: RTX 3060 via Tailscale) e comuta para o nó local VPS Zen 4 em caso de falha transitória (cooldown de 15 minutos).
• Shadow Evaluation Telemetry: Persistência paralela assíncrona em SQLite WAL para auditoria e calibração contínua.

Camada Core (Rust 1.80+ / dokas1-core)

• Compilação Nativa para Zen 4 / AVX-512: Código vetorizado executado com flags -C target-cpu=znver4.
• Memória Epistêmica ConceptBarsa: Grafo de conceitos enciclopédicos residente em memória com consulta instantânea (< 100 ns).

🧠 2. TruthMatrix (Matriz da Verdade) & ConceptBarsa

Diferente de LLMs probabilísticos que tentam "adivinhar" o próximo token, o DokaS1 decompõe o texto em uma matriz formal de alegações estruturadas (ClaimAtom):

Contradição Estrita por Antônimos

O ConceptBarsa resolve contradições mesmo quando a palavra "não" está ausente (ex: vigente ↔ rescindido, adimplente ↔ inadimplente, obstrutivo ↔ restritivo, concêntrica ↔ excêntrica), aplicando penalidade matemática de -0.65 a hipóteses antagônicas.

🔌 3. Endpoint Principal: POST /v1/systemone

Substituto direto (drop-in replacement) para chamadas TypeSafe JEV. Avalia simultaneamente múltiplas premissas de tipo boolean ou choice.

curl -X POST https://api.dokas1.ia.br/v1/systemone \
  -H "Authorization: Bearer dokas1_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dokas1-v1",
    "state": {
      "text": "Paciente com dor aguda no joelho. Teste de Lachman positivo e gaveta anterior com frouxidão ligamentar acentuada."
    },
    "questions": {
      "lesao_lca": { "type": "boolean" },
      "diagnostico": {
        "type": "choice",
        "options": [
          "LESAO_DO_LIGAMENTO_CRUZADO_ANTERIOR",
          "FRATURA_DE_PATELA",
          "BURSITE_TROCANTERICA"
        ]
      }
    }
  }'

import requests

payload = {
    "model": "dokas1-v1",
    "state": {
        "text": "Paciente com dor aguda no joelho. Teste de Lachman positivo e gaveta anterior com frouxidão."
    },
    "questions": {
        "lesao_lca": {"type": "boolean"},
        "diagnostico": {
            "type": "choice",
            "options": ["LESAO_DO_LIGAMENTO_CRUZADO_ANTERIOR", "FRATURA_DE_PATELA"]
        }
    }
}

res = requests.post(
    "https://api.dokas1.ia.br/v1/systemone",
    headers={"Authorization": "Bearer dokas1_live_sua_chave"},
    json=payload
)
print(res.json()["results"])

import axios from 'axios';

const api = axios.create({
  baseURL: 'https://api.dokas1.ia.br',
  headers: { 'Authorization': 'Bearer dokas1_live_sua_chave' }
});

async function avaliar() {
  const { data } = await api.post('/v1/systemone', {
    model: 'dokas1-v1',
    state: { text: 'Paciente com dor no joelho. Teste de Lachman positivo.' },
    questions: {
      lesao_lca: { type: 'boolean' }
    }
  });
  console.log(data.results.lesao_lca.answer); // true
}

avaliar();

package main

import (
    "bytes"
    "net/http"
    "io"
    "fmt"
)

func main() {
    payload := []byte(`{
        "model": "dokas1-v1",
        "state": {"text": "Paciente com teste de Lachman positivo."},
        "questions": {"lesao_lca": {"type": "boolean"}}
    }`)

    req, _ := http.NewRequest("POST", "https://api.dokas1.ia.br/v1/systemone", bytes.NewBuffer(payload))
    req.Header.Set("Authorization", "Bearer dokas1_live_sua_chave")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

{
  "results": {
    "lesao_lca": {
      "answer": true,
      "confidence": 0.92,
      "reasoning": "Lachman test positive entails anterior cruciate ligament rupture."
    },
    "diagnostico": {
      "answer": "LESAO_DO_LIGAMENTO_CRUZADO_ANTERIOR",
      "confidence": 0.88,
      "reasoning": "Resonance bonus (+0.50) with CONCEPT_ACL_INJURY."
    }
  },
  "engine": "dokas1-rust",
  "processing_time_ms": 14.2
}

🔍 3.1. Captura de Evidências & Dossiê Atômico (evidence_mode)

Para conformidade regulatória, auditoria de decisões financeiras/médicas ou destaque visual no front-end, o DokaS1 suporta ancoragem de evidências estruturadas via parâmetro evidence_mode:

Exemplo de Payload com Evidências (evidence_mode: "inline")

curl -X POST https://api.dokas1.ia.br/v1/systemone \
  -H "Authorization: Bearer dokas1_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dokas1-v1",
    "evidence_mode": "inline",
    "tenant_id": "fintech_credito",
    "entity_id": "proposta_88391",
    "state": {
      "text": "Empresa Exemplo Comércio ME possui faturamento de R$ 45.000/mês. Consta duplicata protestada no valor de R$ 1.200,00 quitada em cartório há 2 dias."
    },
    "questions": {
      "protesto_inadimplido": {
        "type": "boolean",
        "instructions": "Consta duplicata protestada em aberto sem quitação?"
      }
    }
  }'

{
  "answers": {
    "protesto_inadimplido": {
      "type": "boolean",
      "value": false,
      "confidence": 0.94,
      "epistemic_status": "REFUTED",
      "uncertainty": 0.06,
      "high_uncertainty": false
    }
  },
  "decision_id": "dec_9f81a7b2c01944e8",
  "evidence_mode": "inline",
  "evidence": {
    "protesto_inadimplido": {
      "question_key": "protesto_inadimplido",
      "evaluation_type": "boolean",
      "verdict": false,
      "epistemic_status": "FACTUAL_LITERAL",
      "evidence_grounding": {
        "exact_match_span": "Consta duplicata protestada no valor de R$ 1.200,00 quitada em cartório há 2 dias.",
        "char_offsets": [67, 149],
        "source_sha256": "4a719d268d87ef635678b871c82bc3128911d9f4e3c2b1897c5e21901a8b2701"
      },
      "arithmetic": {
        "dice_lexical": 0.52,
        "polarity_weight": 0.94
      },
      "counterfactual_modifier": {
        "condition": "Se for apresentada certidão comprovando pendência ativa sem quitação",
        "expected_verdict_shift": "Shift from REFUTED to SUSTAINED (true)"
      }
    }
  },
  "processing_time_ms": 14.8
}

⚖️ 3.2. Prova sob Demanda: POST /decisions/proveit

O endpoint /decisions/proveit (também acessível via alias /v1/decisions/proveit) implementa a arquitetura de Proof-on-Demand (Prova sob Demanda). Ele desacopla a rota crítica de alta vazão (< 1 ms no modo none ou deferred) da exigência formal de explicabilidade, garantindo que o custo de provar seja pago exclusivamente quando uma decisão for auditada ou contestada.

Modo 2: Recomputação Just-in-Time (Sem Staging Prévio)

Quando a decisão original rodou no modo de máxima velocidade evidence_mode: "none" (zero I/O em disco) e um analista solicita a prova formal, a aplicação envia o contexto original e a pergunta contestada:

curl -X POST https://api.dokas1.ia.br/decisions/proveit \
  -H "Authorization: Bearer dokas1_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "text": "Empresa: Metalúrgica Alvorada S.A. Faturamento contábil: R$ 450.000,00/mês. Volume médio de notas fiscais autorizadas nos últimos 90 dias totaliza R$ 112.400,00/mês."
    },
    "question_key": "divergencia_fiscal",
    "question": "O faturamento fiscal real apurado diverge criticamente da receita contábil declarada?",
    "eval_type": "noul"
  }'

import requests

payload = {
    "context": {"text": "Empresa: Metalúrgica Alvorada S.A. Faturamento contábil: R$ 450.000,00/mês. Volume médio de notas fiscais: R$ 112.400,00/mês."},
    "question_key": "divergencia_fiscal",
    "question": "O faturamento fiscal real apurado diverge criticamente da receita contábil declarada?",
    "eval_type": "noul"
}
headers = {"Authorization": "Bearer dokas1_live_sua_chave"}
res = requests.post("https://api.dokas1.ia.br/decisions/proveit", json=payload, headers=headers)
print(res.json())

const { data } = await axios.post('https://api.dokas1.ia.br/decisions/proveit', {
  context: { text: 'Empresa: Metalúrgica Alvorada S.A. Faturamento contábil: R$ 450.000,00/mês. Volume médio de notas: R$ 112.400,00/mês.' },
  question_key: 'divergencia_fiscal',
  question: 'O faturamento fiscal real apurado diverge criticamente da receita contábil declarada?',
  eval_type: 'noul'
}, {
  headers: { Authorization: 'Bearer dokas1_live_sua_chave' }
});
console.log(data.proof.ground_span);

req, _ := http.NewRequest("POST", "https://api.dokas1.ia.br/decisions/proveit", bytes.NewBuffer(payload))
req.Header.Set("Authorization", "Bearer dokas1_live_sua_chave")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)

Modo 1: Resgate Direto por Referência (Staged)

Quando a decisão original rodou com evidence_mode: "deferred", o dossiê foi persistido em background no SQLite WAL com TTL de 72 horas. O resgate é executado em tempo recorde (< 1 ms):

curl -X POST https://api.dokas1.ia.br/decisions/proveit \
  -H "Authorization: Bearer dokas1_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_id": "dec_8c8a679da00149749b91be6a8c12f00a",
    "question_key": "probe_revenue_divergence"
  }'

{
  "status": "PROVEN",
  "mode": "just_in_time",
  "question_key": "probe_revenue_divergence",
  "verdict": {
    "value": 0.9323,
    "confidence": 0.8650,
    "uncertainty": 0.1350
  },
  "epistemic_status": "FACTUAL_LITERAL",
  "proof": {
    "ground_span": "text: Empresa: Metalúrgica Alvorada S.A. Faturamento contábil declarado: R$ 450.000,00/mês.",
    "char_offsets": [0, 91],
    "context_sha256": "fdf2f01ffc5a45b491fb2f77db5de220383595ccfd12742d26497ecea144e7e2",
    "arithmetic_breakdown": {
      "dice_lexical": 0.468,
      "polarity_weight": 0.0,
      "composite_score": 0.932
    },
    "counterfactual_modifier": {
      "reversal_condition": "Se for apresentada certidão negativa, aditivo contratual ou contraprova idônea refutando 'probe_revenue_divergence'",
      "expected_shift": "noul <= 0.20 (Não confirmado / Reversão)",
      "rule_generation_method": "heuristic_template"
    }
  }
}

🔢 3.3. Contabilidade Exata de Tokens BPE (Padrão OpenAI cl100k_base)

O DokaS1 utiliza o tokenizador nativo em Rust tiktoken-rs configurado no padrão oficial cl100k_base (o mesmo vocabulário e padrão de cálculo utilizado pela OpenAI no GPT-4 e ChatGPT).

A contagem é executada token por token em tempo de execução (< 10 microssegundos em Rust), garantindo 100% de paridade contábil e permitindo auditar o ROI exato da substituição de LLMs de nuvem pelo DokaS1.

{
  "usage": {
    "input_tokens": 175,
    "output_tokens": 224,
    "total_tokens": 399
  }
}

Headers HTTP Emitidos Automaticamente:

• X-DokaS1-Input-Tokens: Quantidade exata de tokens BPE do prompt e premissas.
• X-DokaS1-Output-Tokens: Quantidade exata de tokens BPE da resposta serializada.
• X-DokaS1-Questions: Total de perguntas avaliadas no lote.

🎯 4. Engenharia de Contexto & Boas Práticas do Sistema 1 (Fast-Thinking)

O DokaS1 implementa uma arquitetura discriminativa nativa de software classificada como System One Models. Inspirado na psicologia cognitiva (pensamento rápido vs. pensamento lento), o modelo atua como uma camada de reflexo semântico: em vez de gerar texto livre autorregressivo token a token, avalia o estado do sistema contra perguntas estritamente tipadas, devolvendo decisões discretas acompanhadas por distribuições de probabilidade e estimativas calibradas de incerteza em menos de 15 milissegundos.

4.1. Dicotomia Arquitetural: LLMs Generativos vs. DokaS1 Sistema 1

4.2. Primitivas Tipadas & Matemática da Incerteza

O contrato da API rejeita campos abertos para conversa. Toda decisão é governada por três primitivas fundamentais que mapeiam formalmente diferentes categorias de julgamento:

Formulação Matemática dos Índices de Confiança

4.3. Os 5 Pilares de Engenharia de Contexto para Sistema 1

Modelos de Sistema 1 não possuem memória enciclopédica aberta no momento do cálculo. Todo o universo informacional coincide rigorosamente com o payload de state. Aplique estas diretrizes para garantir máxima assertividade:

1. Mitigação Ativa do Context Rot:
   A assertividade semântica é inversamente proporcional à dispersão de dados não pertinentes. Injetar transcrições integrais de chamados, payloads residuais ou logs de erro com milhares de linhas dilui os sinais relevantes, achatando as probabilidades. Extraia no código previamente os dados-chave; deixe o DokaS1 julgar os fatos consolidados.
2. Tipagem Estruturada de Estado (JSON Semântico):
   Prefira objetos JSON descritivos (ex: {"cliente": {"faturamento": 85000, "status_serasa": "limpo"}}) em vez de texto corrido ambíguo. Chaves semânticas bem delineadas delimitam o papel de cada dado e reduzem ambiguidades interpretativas.
3. Ancoragem Direta por Navegação Pontuada:
   Nas instruções das perguntas, aponte diretamente o caminho no JSON usando notação de ponto (ex: "Instrução: Avalie o campo ticket.customer_history[0].status"). O modelo atinge máxima calibração quando o julgamento recai sobre um caminho referenciado textualmente.
4. Separação Rígida entre Fatos e Aritmética:
   Modelos de inferência semântica operam sob rigor literal e não devem atuar como interpretadores lógicos ou calculadoras de juros. Cálculo de dias decorridos, contagem de prazos ou juros de mora devem ser executados pelo código da aplicação e inseridos como novo campo literal no estado (ex: "dias_desde_vencimento": 14). O DokaS1 avalia o significado de negócio daquele número.
5. Amortecimento Obrigatório de Entropia (Opções de Escape):
   Ao criar perguntas da primitiva Choice, nunca force o modelo a escolher entre opções inadequadas para entradas atípicas. Inclua sempre uma alternativa de escape (ex: "OUTRO", "SOLICITAR_DOCUMENTACAO_ADICIONAL" ou "ESCALONAMENTO_HUMANO"). Isso impede que a densidade matemática seja alocada na opção "menos incorreta", evitando falsos empates (33%/33%/33%).

4.4. Padrões Arquiteturais e Orquestração Operacional

A Cascata Tripla de Decisão de Software

Substitua pipelines caros de LLMs generativos por uma arquitetura em três camadas otimizadas:

4.5. Superfície de Ataque & Governança Corporativa

• Imunidade de Esquema vs. Segurança de Conteúdo: O DokaS1 assegura 0% de erro de tipo JSON, mas interpreta o texto do estado como fatos verdadeiros. Textos manipulados por terceiros devem ser previamente higienizados em um AI Gateway antes de submissão ao modelo.
• Fixação Rígida de Versões em Produção: É vedado o uso de identificadores voláteis como latest em pipelines corporativos. Fixe sempre a versão exata do modelo (ex: dokas1-v1) e versione os arquivos de configuração de critérios em repositório Git.
• Observabilidade & Auditoria Formal Regulatória: Toda inferência gera um pacote de telemetria contendo decision_id, hash SHA-256 do estado, distribuição de probabilidade e os offsets literais exatos do texto (char_offsets), viabilizando auditoria perante BACEN, LGPD e CADE.

📚 5. Ingestão Dinâmica: POST /v1/epistemic-memory/digest

Permite ingerir glossários técnicos, verbetes médicos, regulamentações jurídicas ou termos de contratos em tempo de execução, expandindo a memória epistêmica sem reiniciar o serviço:

curl -X POST https://api.dokas1.ia.br/v1/epistemic-memory/digest \
  -H "Authorization: Bearer dokas1_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "A manobra de Lachman e o teste da gaveta anterior avaliam a estabilidade do ligamento cruzado anterior (LCA).",
    "domain": "fisioterapia_ortopedia"
  }'

Importação Estruturada em Lote: POST /v1/epistemic-memory/import

Para importar pacotes completos de verbetes JSON com sinônimos, antônimos, hiperônimos, implicações e polaridade intrínseca (+1 / -1), replicados automaticamente em todos os nós e com invalidação instantânea do TruthMatrixCache:

curl -X POST https://api.dokas1.ia.br/v1/epistemic-memory/import \
  -H "Authorization: Bearer dokas1_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "concepts": [
      {
        "canonical_key": "CONCEPT_MED_BACEN_REVERSAL",
        "domain": "FINANCEIRO_PIX",
        "description": "Mecanismo Especial de Devolução do Banco Central",
        "synonyms": ["reversão compulsória via med", "bloqueio cautelar e devolução especial"],
        "antonym_keys": ["CONCEPT_PIX_IRREVOCABLE_SETTLED"],
        "inherent_polarity": -1
      }
    ]
  }'

🏢 6. Exemplos Práticos de Uso por Domínio

Abaixo estão padrões de chamada prontos para esteiras de crédito, protocolos fisioterápicos/médicos e conformidade contratual:

Caso 1: Mesa de Crédito & Solvência Financeira

payload = {
    "model": "dokas1-v1",
    "evidence_mode": "inline",
    "state": {
        "text": "Empresa Alfa Comércio ME, faturamento comprovado de R$ 85.000,00/mês. Consta protesto no valor de R$ 450,00 já cancelado por quitação voluntária no tabelionato, com certidão de baixa emitida."
    },
    "questions": {
        "protesto_regularizado": {
            "type": "boolean",
            "instructions": "O protesto apontado foi formalmente cancelado por quitação voluntária?"
        },
        "perfil_solvencia": {
            "type": "choice",
            "instructions": "Qual a classificação de risco e perfil de solvência da empresa?",
            "criteria": {
                "ALTO_POTENCIAL": "Faturamento comprovado de R$ 85.000 com protesto cancelado por quitação voluntária",
                "MODERADO": "Faturamento irregular com pendências em negociação",
                "RESTRITO_INADIMPLENTE": "Protesto ativo não pago ou faturamento incompatível"
            }
        }
    }
}
# Veredito Real: protesto_regularizado = True (CONF: 0.94) | perfil_solvencia = ALTO_POTENCIAL (CONF: 0.40 | Prob: 62.8%)

Caso 2: Semiologia Ortopédica & Fisioterapia Hospitalar

payload = {
    "model": "dokas1-v1",
    "evidence_mode": "inline",
    "state": {
        "text": "Paciente com dor e crepitação subacromial no ombro direito. Manobras de Neer e Hawkins-Kennedy fortemente positivas confirmando conflito subacromial. Arco doloroso presente entre 60° e 120° de abdução."
    },
    "questions": {
        "manobras_positivas": {
            "type": "boolean",
            "instructions": "As manobras de Neer e Hawkins-Kennedy foram positivas no ombro direito?"
        },
        "diagnostico_topografico": {
            "type": "choice",
            "instructions": "Qual o diagnóstico topográfico confirmado pelo arco doloroso e testes de Neer e Hawkins-Kennedy?",
            "criteria": {
                "SINDROME_DO_IMPACTO_SUBACROMIAL": "Síndrome do impacto subacromial confirmada por manobras de Neer e Hawkins-Kennedy positivas",
                "CAPSULITE_ADESIVA_CONGELADA": "Capsulite adesiva congelada com perda global de rotação passiva",
                "LUXACAO_ACROMIOCLAVICULAR": "Luxação acromioclavicular com sinal da tecla de piano evidente"
            }
        }
    }
}
# Veredito Real: manobras_positivas = True (CONF: 0.96) | diagnostico = SINDROME_DO_IMPACTO_SUBACROMIAL (CONF: 0.51 | Prob: 73.1%)

Caso 3: Auditoria Contratual & Compliance Jurídico

payload = {
    "model": "dokas1-v1",
    "evidence_mode": "inline",
    "state": {
        "text": "Cláusula 12ª: Qualquer das partes poderá rescindir o presente contrato imotivadamente mediante aviso prévio por escrito com antecedência mínima de 30 dias, com isenção total de multa rescisória."
    },
    "questions": {
        "aviso_previo_exigido": {
            "type": "boolean",
            "instructions": "O contrato exige aviso prévio formal por escrito com antecedência mínima para rescisão?"
        },
        "prazo_notificacao": {
            "type": "choice",
            "instructions": "Qual o prazo formal de aviso prévio por escrito exigido pela cláusula 12ª?",
            "criteria": {
                "PRAZO_30_DIAS": "Aviso prévio por escrito com antecedência mínima de 30 dias",
                "PRAZO_60_DIAS": "Aviso prévio com antecedência de 60 dias",
                "PRAZO_IMEDIATO": "Rescisão imediata sem necessidade de aviso prévio"
            }
        }
    }
}
# Veredito Real: aviso_previo_exigido = True (CONF: 0.96) | prazo_notificacao = PRAZO_30_DIAS (CONF: 0.42 | Prob: 63.6%)

Caso 4: Dossiê Canônico Estruturado (Ancoragem por Dot-Notation)

payload = {
    "model": "dokas1-v1",
    "evidence_mode": "inline",
    "state": {
        "text": (
            "Dossiê de Crédito Corporativo - Estado Canônico:\n"
            "cliente.tempo_fundacao_anos: 8.5 anos\n"
            "operacao.valor_parcela_individual: R$ 4125.00\n"
            "operacao.razao_parcela_faturamento: 3.7%\n"
            "capacidade.faturamento_efetivo_adotado: R$ 111500.00\n"
            "capacidade.faixa_risco_algoritmico: MEDIUM\n"
            "historico_erp.percentual_pago_em_dia: 29.0%\n"
            "bureau_mercado.score_serasa: 812\n"
            "bureau_mercado.restricoes_conglomerado_qtd: 0\n"
            "governanca_e_bloqueios.alavancagem_excessiva: False"
        )
    },
    "questions": {
        "payment_capacity": {
            "type": "noul",
            "instructions": "Avalie operacao.razao_parcela_faturamento e capacidade.faturamento_efetivo_adotado. O valor da parcela mensal compromete de forma excessiva ou perigosa a capacidade mensal de pagamento da empresa?"
        },
        "behavioral_coherence": {
            "type": "choice",
            "instructions": "Compare historico_erp.percentual_pago_em_dia com bureau_mercado.score_serasa. Qual padrão descreve o comportamento do cliente?",
            "criteria": {
                "COERENCIA_POSITIVA": "Bom pagador interno e externo sem restrições",
                "ASSIMETRIA_NEGATIVA": "Bom perfil no mercado (score Serasa alto e zero restrições), mas atrasos recorrentes no histórico interno (ERP)",
                "PREVALENCIA_HISTORICO_INTERNO": "Excelente histórico interno (90%+ em dia) que supera oscilações externas"
            }
        }
    }
}
# Veredito Real: payment_capacity = 0.12 (CONF: 0.76 | REFUTED) | behavioral_coherence = ASSIMETRIA_NEGATIVA (CONF: 0.74)

📊 7. Benchmarks & Performance