v1.0.0 is the first complete Victus Processing baseline. It includes the
Markdown-to-structured-paper flow, PostgreSQL-backed scientific outputs,
paper classification, evidence-ready blocks, experiment maps, canonical
evidence, and paper processing state.
victus-processing exists to turn scientific-paper inputs into local,
inspectable evidence-processing artifacts for the Victus ecosystem.
It covers the local workflow from paper metadata and PDFs to structured blocks,
trimmed evidence inputs, experiment maps, and canonical evidence. The
repository is optimized for reproducible batch processing, explicit artifact
boundaries, and agent-readable documentation.
- Keep paper-processing stages explicit and reproducible.
- Preserve stable local artifacts between stages.
- Make repository boundaries clear for humans and AI agents.
- Prefer operationally simple workflows over hidden orchestration.
- Keep model-mediated outputs traceable to inputs, prompts, and configuration.
- Separate onboarding, architecture, operations, contracts, and decisions.
Non-goals:
- serve analytics products;
- host RAG/vector indexing;
- own deployment infrastructure;
- replace external paper retrieval services;
- guarantee external API availability or model behavior.
This repository covers:
victus-processing CLI commands;- local
data/ runtime layout;
- metadata discovery and candidate state;
- manual PDF intake into canonical artifacts;
- Docling/LLM PDF-processing artifacts;
- LLM evidence extraction outputs;
- local contracts for artifacts, paths, and stage handoffs.
This repository does not cover:
- analytics dashboards or downstream products;
- production infrastructure;
- vector stores or query-serving systems;
- external PDF download services;
- external vendor billing, limits, or uptime.
Primary hubs:
- Architecture: system design, components, data architecture,
quality attributes, decisions, and invariants.
- Operations: configuration, daily commands, validation,
troubleshooting, and rollback notes.
- Contracts: storage paths, environment variables, data layout,
and identity contracts.
- Contract details: source-of-truth contracts for data layout,
configuration/CLI, stage handoffs, artifact schemas, blocks, experiment maps,
and canonical evidence.
- CLI operations: command groups and common command flow.
- PDF processing operations: runtime details
specific to PDF-processing flow.
- Runbooks: task-specific operational procedures.
Planned documentation structure:
000-SYSTEM-CONTEXT.md: repository orientation and documentation map.100-ARCHITECTURE.md: architecture hub.200-OPERATIONS.md: operations hub.300-DECISIONS.md: decisions hub.- module folders under
docs/: deeper focused documentation.
- Paper: scientific publication processed by the pipeline.
- Metadata candidate: pre-PDF paper record discovered or fetched by DOI.
- Document ID: identity used before a PDF is normalized.
- Paper ID: identity used for post-PDF processing artifacts.
- Stage: explicit processing step invoked by CLI command.
- Artifact: durable file produced or consumed by a stage.
- Active PDF: normalized PDF ready for PDF processing.
- Structured block: smallest stable unit for preserving scientific text,
document location, order, context, and content kind.
- Trimmed paper JSON: evidence-stage handoff containing only metadata and
blocks from evidence-relevant scientific sections.
- Experiment Map: block-id grouping produced by
results_scope_mapper.
- Canonical Evidence: normalized, traceable evidence record extracted from
metadata, blocks, and an experiment map.
- Runtime layout: local directory structure under
data/.
src/ -> pipeline code and CLI implementation
config/ -> runtime defaults and stage configuration
docs/ -> system, architecture, operations, and contract documentation
tests/ -> validation for CLI, prompts, and processing behavior
ops/ -> operational helper scripts
data/ -> local runtime artifacts, ignored or environment-specific
- Explicit stages: processing should be visible through commands and files.
- Stable artifacts: stage handoffs should use predictable paths and names.
- Low hidden state: important state should be inspectable on disk.
- Restartable workflow: interrupted runs should resume from existing outputs.
- Contract-first docs: paths, identities, and invariants must be documented.
- Agent-safe navigation: docs should tell agents where to look before code.
- Separation of concerns: README, context, architecture, operations,
contracts, and decisions each have distinct jobs.