giovannino a619cefb52 Update README.md

Explain OHIOD

2026-06-12 14:33:45 +02:00

12 KiB

Raw Permalink Blame History

Biblioteca CE Ambrosiana

A sovereign RAG knowledge appliance — architecture, corpus, and deployment documentation.

Public domain. Built in Brianza. Designed for anyone.

What This Is

Biblioteca CE Ambrosiana (BCEA) is a local-first, privacy-correct Retrieval-Augmented Generation¹ system built on commodity ARM hardware. It runs without cloud dependencies, without licensing fees, and without surrendering control of the knowledge it serves.

This repository contains everything needed to understand, replicate, and extend it: the architecture documentation, the RAG document style guide, the corpus of AI-first reference documents, and the deployment guides for individuals and small businesses.

The system is operational. The documentation is the product.

Design Principles

Sovereignty by architecture, not by policy. Data stays local because the system is designed that way — not because a privacy policy says so. Policies change. Architecture does not.

The corpus is the asset. Hardware fails and gets replaced. Models improve and get swapped. Frameworks come and go. A well-structured, completely sourced, model-agnostic document corpus outlasts all of it.

Capability and sovereignty are complementary, not competing. The cascading model² — local inference, sovereign RAG, optional frontier AI at the boundary — delivers both simultaneously by correctly separating the concerns.

SLM constraint as quality standard. Documents precise enough for a small language model³ to retrieve correctly are precise enough for any model. The weakest capable retriever sets the quality floor. Everything above it is headroom.

25% headroom, always. Storage, RAM, power, bandwidth. Hardware that is never stressed lasts. Wear is cumulative and permanent. Speed gains are marginal and temporary.

Repository Structure

biblioteca-ce-ambrosiana/
├── README.md                        — this file
├── architecture/                    — system design and component documentation
├── corpus/                          — RAG document library (public tier)
│   ├── system/                      — OS, kernel, networking, init
│   ├── use-case/                    — tool references and domain knowledge
│   ├── workflow/                    — deployment and operational procedures
│   ├── scripts/                     — verified CE scripts with usage docs
│   └── experience/                  — operational findings and debugging wins
├── style-guide/                     — RAG document authoring standard
└── deployment/                      — build and deployment guides

The Stack

Component	Choice	Rationale
Hardware	Raspberry Pi 5 8GB	Sufficient, sovereign, affordable
OS	Debian ARM64	Broad hardware support, long support lifecycle
Inference runtime	Ollama	Model-agnostic, local, actively maintained
Candidate retrieval	snowflake-arctic-embed:xs	Fast, small, accurate for Stage 1
Reranker	nomic-embed-text (768-dim)	Quality reranking at bounded cost
Vector store⁴	SQLite + numpy cosine	Zero overhead, sovereign, correct at this scale
RAG server	FastMCP	Lightweight, MCP-native⁵
Stage 1 retrieval	BM25⁶ + arctic-embed → RRF⁷ → top 15–20	Lexical + semantic, fused
Stage 2 reranking	nomic-embed-text → top 5	Quality gate, cost bounded

Model roles in the pipeline:

Task	Model
Section doc authoring from scraped source	Qwen3 0.6B
Style guide compliance review	Qwen3 0.6B
Index/context — simple doc sets	Phi-4 Mini
Index/context — medium complexity	Mistral Small
Index/context — book-length and OHIOD-authored works⁸	Claude Code
Man pages, helpme, explanatory content	Phi-4 Mini
Content recon and injection detection	Phi-4 Mini
Architecture docs, position papers, public-facing content	Claude

Model assignments are dynamic — best current performers for each task, always. No model is permanent infrastructure.

No cloud APIs in the retrieval pipeline. No managed services. No vendor lock-in.

The Corpus

Documents in this library are authored to an explicit style guide optimised for retrieval by small language models. The standard is higher than typical RAG documentation because the retriever is intentionally constrained — if a small model can find the right answer, a larger one certainly can.

Every document is:

Scoped to a single concept or tool
Self-contained at the section level — each chunk⁹ makes sense without surrounding context
Completely sourced with verifiable upstream references
Reviewed by a human before corpus commit
Licensed for reuse without restriction

The style guide is in style-guide/. Read it before contributing.

Scaling: From Pi to Hive

The reference implementation runs on a Raspberry Pi 5. That is a deliberate floor — a proof that sovereign RAG does not require expensive hardware. But the architecture is explicitly designed to scale without replacement: the same pipeline, the same corpus, the same principles, running on progressively more capable hardware as the use case demands.

Hardware tiers:

Tier	Hardware	Use case
Personal	Raspberry Pi 5 8GB	Individual, home office, small team
Prosumer	AMD Ryzen / Intel Core, 32GB RAM, multiple SATA drives	Small business, professional studio, community organisation
Enterprise	Rackmounted x86, NVMe arrays, GPU inference	Multi-site organisation, high-concurrency deployment

Database backend scales with the corpus:

Scale	Backend	Migration trigger
Single node, small corpus	SQLite + numpy cosine	Default — no action needed
Growing corpus or multiple consumers	sqlite-vec	Query latency increase
Dedicated server, concurrent users	PostgreSQL + pgvector	Concurrent consumer pressure
Enterprise throughput	Qdrant / Weaviate / Milvus	Throughput + redundancy requirements

Migration between backends is a configuration change, not a code change. The corpus moves intact. Nothing is rewritten.

OS tier scales with operational requirements:

Tier	OS	Context
Personal to mid-range	Debian	CE standard, broad hardware support
Enterprise mid to large	RHEL / AlmaLinux / Rocky	SELinux, support contracts, certified hardware
Specialised enterprise	NixOS	Declarative, reproducible, auditable deployments
European enterprise	SUSE	Strong EU infrastructure presence

The Ambrosiana Hive

At multi-node scale, individual Ambrosiana instances federate into a Hive — a coordinated cluster where nodes share corpus curation workload, distribute embedding generation, and maintain redundancy. A query answered by any node in the Hive draws on the full corpus maintained collectively by all of them.

The Hive has no single point of failure and no central authority. Each node is independently functional. Federation is additive — a node can join or leave the Hive without disrupting the others.

This is the same hub-and-spoke architecture¹⁰ as the single-node fleet model, extended across multiple Ambrosiana instances rather than fleet devices.

Cascading Sovereign AI

BCEA is one layer in a broader architectural model:

Cloud frontier AI
  ↑ clean, scrubbed, enriched context     ↓ reasoning depth, breadth
PII scrubbing layer (architectural guarantee)
  ↑ structured, retrieved, relevant knowledge
Ambrosiana sovereign RAG
  ↑ local, curated, domain-specific corpus
Fleet device local inference
  ↑ raw data, local context, private by architecture
Source documents and operational reality

Each layer contributes what the layer below cannot provide. Nothing flows upward that compromises sovereignty. Nothing flows downward that creates dependency on the layer above.

A grandmother's Pi Zero in a rural school gets frontier reasoning depth without ever having exposed sensitive data to reach it.

Who This Is For

Individuals who want a personal knowledge assistant that runs on hardware they own, answers from sources they chose, and never phones home.

Small businesses that need domain-specific AI assistance without putting operational knowledge into someone else's cloud.

Technical communities interested in sovereign AI infrastructure as a replicable, documented practice rather than a theoretical position.

AI agents that need a structured, machine-readable corpus of technical reference material. This repository is intentionally accessible without authentication.

Licence

All original content in this repository is released to the public domain under the Unlicense (software and scripts) or CC0 (documentation and hardware references).

Corpus documents derived from upstream sources retain their upstream licences, noted in each document's footer.

This work stands on the shoulders of billions of dwarves.

Project

Cervello Elettrico OS — git.jhoeven.net/ceos

Brianza, Italy · servizi@cervelloelettrico.it · cervelloelettrico.it

Crafted by John A. Hoeven with the ethical assistance of Claude AI (Anthropic).

RAG (Retrieval-Augmented Generation): A technique where an AI model is given relevant documents retrieved from a knowledge base before generating its answer, rather than relying solely on what it learned during training. The result is answers grounded in your actual documents rather than generalised training data. ↩︎
Cascading model: An architecture where multiple AI layers — local inference, local RAG, and optionally a cloud frontier model — each handle what they do best. Local layers handle privacy-sensitive work; cloud layers add reasoning depth when needed. See architecture/cascading-sovereign-ai.md for the full design. ↩︎
Small language model (SLM): A language model small enough to run on modest hardware — a laptop, a Raspberry Pi, a NAS — rather than requiring a data centre. Examples here include Phi-4 Mini (~3GB) and Qwen3 0.6B (~500MB). Smaller means more constrained, which raises the bar for document quality. ↩︎
Vector store: A database optimised for storing and searching vector embeddings — numerical representations of text that capture semantic meaning. Similar meaning = similar vectors = found together in search. SQLite + numpy cosine is a lightweight implementation suitable for corpora in the low-gigabyte range. ↩︎
MCP (Model Context Protocol): An open protocol for connecting AI models to external tools and data sources in a standardised way. FastMCP is a lightweight server implementation of this protocol. ↩︎
BM25: A classical text search algorithm (Best Match 25) that finds documents containing the query's actual words, weighted by frequency and rarity. Fast, no GPU required, excellent at exact-term matching. Complements semantic search rather than competing with it. ↩︎
RRF (Reciprocal Rank Fusion): A simple, effective method for combining ranked results from multiple search systems — in this case BM25 and semantic embedding search — into a single ranked list without needing to tune weights between them. ↩︎
OHIOD (Organic Humanoid I/O Device): The human being at the keyboard — framed architecturally rather than romantically. The term captures the human's role in the CE pipeline precisely: source vetter, design authority, live evaluator, and final decision-maker. The system is designed to sustain OHIOD judgment quality over time, not replace it. A person is irreducibly the best tool for the jobs that require being a person. ↩︎
Chunk: A section of a document as it is stored and retrieved by the RAG system. Documents are split into chunks at index time; the retriever finds the most relevant chunks for a query rather than entire documents. Chunk quality — size, scope, self-containment — directly determines retrieval quality. ↩︎
Hub-and-spoke: A network architecture where a central node (the hub) coordinates with peripheral nodes (the spokes). Here, each Ambrosiana instance acts as a hub for its local fleet devices; in the Hive, multiple hubs coordinate with each other while each remains independently functional. ↩︎

12 KiB Raw Permalink Blame History Unescape Escape