biblioteca-ce-ambrosiana/README.md

# 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[^1] 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[^2] — 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[^3] 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[^4] | SQLite + numpy cosine | Zero overhead, sovereign, correct at this scale |
| RAG server | FastMCP | Lightweight, MCP-native[^5] |
| Stage 1 retrieval | BM25[^6] + arctic-embed → RRF[^7] → 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[^10] | 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[^8] 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[^9] 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).*

---

[^1]: **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.

[^2]: **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.

[^3]: **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.

[^4]: **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.

[^5]: **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.

[^6]: **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.

[^7]: **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.

[^8]: **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.

[^9]: **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.

[^10]: **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.