API e Dados

Endpoints

Método	Endpoint	Uso
POST	/api/analyze	Análise NLP com sentenças, POS, dependências, entidades e métricas.
POST	/api/detail	Análise linguística detalhada com OpenAI.
POST	/api/sanitize	Sanitização textual stateless.
POST	/api/classify-clitics	Classificação de clíticos em lotes de sentenças.
POST	/api/model/run	Execução de modelo analítico no backend.
POST	/api/report/compile	Compilação assistida de relatório.
POST	/api/report/section/regenerate	Regeneração de seção do relatório.
POST	/api/visualize/dependencies	HTML SVG de dependências sintáticas.
POST	/api/visualize/entities	HTML de entidades nomeadas.

Configuração de ambiente

Variável	Uso
OPENAI_API_KEY	Necessária para /api/detail e /api/report/*.
OPENAI_DETAIL_MODEL	Modelo opcional para análise detalhada.
OPENAI_REPORT_MODEL	Modelo opcional para relatório, fallback gpt-4o-mini.
VITE_API_URL	URL da API usada pelo frontend.

Snapshot de produção

O projeto de produção é serializado como ProductionProjectSnapshot.

interface ProductionProjectSnapshot {
  schemaVersion: number;
  projectId: string;
  projectName: string;
  projectDescription: string;
  updatedAt: string;
  dados: BatchState;
  preparacao: { processed: ProcessedRow[] | null };
  etiquetagem: {
    pendingRequest: EtiquetagemRequest | null;
    lastCompletedRequestId: number | null;
    result: AnalyzeResponse | null;
    enabledPOS: string[];
  };
  filtragem: { classifiedResult: ClassifiedSentence[] | null };
  triagem: { occurrences: TriagedOccurrence[] };
  configuracao: { variables: AnalysisVariable[] };
  codificacao: { rows: CodifiedRow[] };
  transformacao: {
    method: "dummy" | "label-encoding" | "tfidf";
    dropFirst: boolean;
    matrix: AnalysisMatrix | null;
  };
  analise: {
    selectedModel: "log_binomial" | "log_multinomial" | "mixed_effects";
    results: ModelResults | null;
  };
}

Ocorrência de clítico

Campos centrais de uma ocorrência:

Campo	Tipo	Descrição
ocorrencia_id	string	Identificador da ocorrência.
documento_id	string	UID do documento.
sentenca_id	string	Identificador da sentença.
texto_sentenca	string	Sentença de origem.
verbo_hospedeiro	string	Verbo associado ao clítico.
clitico	string	Forma textual do clítico.
colocacao_clitico	enum	proclise, enclise, mesoclise, duvidoso.
y_proclise	0, 1 ou null	Variável dependente binária.
ambiente_neutro	enum	sim, nao, duvidoso.
ocorrencia_valida	boolean	Elegibilidade para rodada Martins.
motivo_exclusao	string	Razão da exclusão quando aplicável.
status	enum	pendente, confirmado, descartado.
confidence	number	Confiança da classificação automática.

Variável analítica

interface AnalysisVariable {
  id: string;
  name: string;
  label: string;
  role: "dependent" | "independent" | "control" | "random_effect";
  kind: "categorical" | "ordinal" | "numeric" | "binary" | "text";
  source: "triage" | "metadata" | "linguistic" | "manual" | "derived";
  sourceField?: string;
  enabled: boolean;
  levels: VariableLevel[];
  referenceLevelId?: string;
  missingPolicy: "exclude" | "keep_as_level" | "impute";
}

Matriz analítica

interface AnalysisMatrix {
  columns: string[];
  rows: MatrixPreviewRow[];
  sampleCount: number;
  method: "dummy" | "label-encoding" | "tfidf";
  dropFirst: boolean;
  generatedAt: string;
}

Payload de relatório

O relatório recebe um ReportCompileRequest.

interface ReportCompileRequest {
  options: ReportOptions;
  project: ReportProjectContext;
  data: ReportDataContext;
  evidenceCandidates: EvidenceCandidate[];
}

Regras de privacidade:

• não enviar rawText integral dos documentos;
• enviar no máximo 20 exemplos de sentenças;
• truncar exemplos longos para 500 caracteres;
• enviar agregações e amostras em vez da matriz completa quando grande;
• incluir alertas sobre dados ausentes, modelo ausente ou amostra pequena.

Persistência local

Chave ou store	Descrição
PHPB Lab.productionProject.active	Snapshot ativo do projeto de produção.
IndexedDB store snapshots	Armazenamento principal dos snapshots.
localStorage	Fallback quando IndexedDB não está disponível.
PHPB Lab_sanitizer_presets	Presets do workbench de sanitização.