Archiv is an early-stage, local-first knowledge-work system for preserving, searching, analysing, and producing evidence-backed documents while keeping source data and execution under the user's control.
Archiv combines five deliberately separate layers:
- immutable canonical originals;
- rebuildable extraction and search indexes;
- bounded deterministic capabilities;
- optional model-assisted reasoning;
- independent validation and provenance.
Models propose. Validators decide whether work succeeded.
Archiv includes a human-facing Fedora command surface, a deterministic environment doctor, native searchable-text ingestion for InPage .inp documents, local visual OCR recovery for images and image-only PDF pages, a reproducible multilingual OCR benchmark, explainable natural-language retrieval, bounded source-location verification (archiv source), grounded QA over local evidence (archiv ask), model-assisted cited report generation (archiv report), loopback-only OpenAI-compatible model configuration (archiv model), immutable local ingestion, validated SQLite full-text retrieval, independently verified cited DOCX generation, a bounded local MCP server, and a pinned replaceable CoWork-OS workbench integration:
archiv add /path/to/documents
archiv ingest /path/to/urdu-document.inp
archiv ingest /path/to/scanned-page.png
archiv benchmark-ocr --output "$HOME/archiv-ocr-benchmark"
archiv model configure --endpoint http://127.0.0.1:11434 --model llama3
archiv ask "What decisions were made and what remains unresolved?"
archiv ask "What remains unfinished?" --explain-retrieval
archiv report "Prepare a cited status report with risks and next actions"
archiv statusThe grounded-question journey runs over locally ingested Archiv evidence:
user question
→ deterministic local query derivation
→ validated literal FTS searches
→ source-diverse merge, ranking and evidence limit
→ citation validation
→ bounded evidence package
→ configured local model
→ proposed answer
→ citation parsing and validation
→ independent verification
→ readable answer with sources
→ durable run and retrieval evidence
archiv find remains literal and predictable. archiv source accepts either a canonical object SHA-256 or one explicit citation from a JSON citation, find result, ask result, or report manifest; it revalidates the immutable original and citation before returning a bounded read-only path inside Archiv-controlled storage. Natural-language ask and model-assisted report derive bounded query variants locally, without a model, embedding service, vector database, network call, or background daemon. --explain-retrieval shows the terms, recognized concepts, selected sources, native locators, scores, and ranks used for the decision.
Ingestion validates supported inputs, stores read-only content-addressed originals, records processing in SQLite, and builds rebuildable search indexes. Native InPage100 and InPage300 files are parsed locally into stream/byte-offset text segments for search and grounded use; the immutable source is preserved, while page/frame/layout reconstruction is explicitly outside the current claim. When local Tesseract is installed, PNG/JPEG images and PDF pages without native text produce explicitly attributed visual_ocr segments with page and pixel-region citations. Missing OCR tools or requested language models skip cleanly without fabricating text or invalidating the immutable ingestion. The local benchmark generates lawful synthetic English/Arabic/Urdu fixtures and records CER, WER, runtime, memory, exact model hashes and failure cases without changing production configuration. Full-text search builds a separate replaceable FTS5 database and returns citations that are revalidated against the original and normalized hashes before use. Cited DOCX reports include exact source evidence and are reopened, structurally validated, and rendered through LibreOffice before success is reported.
The model interface is strictly bound to explicit loopback-only HTTP endpoints such as Ollama, LocalAI, or vLLM. Remote hosts, cloud fallbacks, HTTPS tunnels, and credential embedding are rejected.
The frozen public field trial retrieves every required source for all 22 benchmark questions at evidence limit 8, with 22/22 structurally valid citation packages and zero fabricated identifiers. See the field-trial report for scope and limitations.
Install on Fedora without cloning the repository or activating a virtual environment:
curl -fsSL https://raw.githubusercontent.com/Nan0pk/Archiv/main/tools/install-fedora.sh | bashThe installer resolves main to one immutable commit, installs that exact source under ~/.local/share/archiv-alpha/versions/, records the commit and downloaded archive hash in install.json, and exposes archiv through ~/.local/bin.
Use the everyday interface:
archiv sample-vault "$HOME/Archiv-Sample"
archiv add "$HOME/Archiv-Sample"
archiv ingest "$HOME/Documents/urdu-document.inp"
archiv ingest "$HOME/Documents/scanned-page.png"
archiv benchmark-ocr --output "$HOME/archiv-ocr-benchmark"
archiv find "unique fixture marker" --json > matches.json
archiv source --citation-file matches.json --citation-number 1
archiv ask "What decisions were made?" --explain-retrieval
archiv report "Prepare a cited status report with risks and next actions"
archiv status
archiv backup "$HOME/archiv-backup.zip"add refreshes search automatically. find shows readable verified literal matches. source locates one independently revalidated preserved original without arbitrary browsing or execution. ask runs grounded QA over locally retrieved evidence. report creates a cited DOCX report for a user objective and independently verifies it before reporting success. benchmark-ocr measures the installed Tesseract language configurations on generated local fixtures and does not change OCR settings. Add --json when machine-readable output is required.
Development setup:
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
archiv doctor
pytestDo not commit private documents, personal data, credentials, model keys, production databases, generated user archives, or proprietary test material. Development fixtures must be synthetic or explicitly redistributable. See the public repository policy and GitHub governance and CI trust boundary.
- Product charter
- Architecture
- Execution contract
- Immutable ingestion
- Native InPage ingestion
- Local visual OCR
- OCR benchmark method
- Measured multilingual OCR baseline
- Local search and citations
- Bounded source location
- Real-work field-trial method
- Measured field-trial report
- Cited DOCX reports
- Bounded local MCP server
- CoWork-OS integration
- User-ready Fedora alpha
- Hardware and performance notes
- GitHub governance and CI trust boundary
- Definition of done
- Roadmap
No open-source licence has been selected yet. Until a licence is added, copyright is reserved and the public source is available for inspection only. A licence decision is tracked separately so that publishing the repository does not accidentally grant terms the project has not chosen.
Product work proceeds through pull requests with evidence-producing acceptance checks.