aura-1b

<div align="center"> <img src="assets/aura.png" alt="Aura-1B" width="420"/>

The fastest answer is the one you never generate.

A 100% local, CPU-native AI system that splits language, exact math and factual memory into specialized modules — instead of asking one small model to do everything (and hallucinate when it can't).

Seven cognitive agents, exact symbolic experts and self-play turn a 1B brain into a system that behaves like a 7-8B where it counts — at 1B speed.

<a href="https://github.com/Simonc44/aura-1b/stargazers"><img src="https://img.shields.io/github/stars/Simonc44/aura-1b?style=social" alt="stars - aura-1b" /></a>

Other languages: Français

Why • Quickstart • Architecture • Teach it • .aef format • Benchmarks • Roadmap

</div>

---

💡 Why Aura-1B?

On a machine without GPU, a 1B LLM is slow (~14 tok/s) and hallucinates. Aura turns that weakness into a system design rule:

The small model proposes. The program proves. Anything unproven is verified against a source or refused — never invented.

The result: instant answers (0–5 ms) on 60–70 % of everyday questions, exact math and dates, real-time facts, and a 1B brain used only where it matters.

The equivalence, measured by capability

The mechanism is the one that makes a 70B feel smarter than its parameter count: organization, verification and style — not raw size. On verifiable tasks Aura no longer plays in the 3B league: it behaves like a 7-8B while keeping 1B speed and footprint.

🚀 Quickstart

One command (Windows, PowerShell)

powershell -ExecutionPolicy Bypass -File scripts/installer.ps1

Then, in a new PowerShell window:

aura "quel est le carre de 7"     # -> 49
aura                              # interactive chat

The installer copies the package to %LOCALAPPDATA%\Aura, creates the venv, downloads the brain (807 MB, once) and registers the aura command.

Development install

uv sync                                        # deps (llama.cpp included)
python scripts/telecharger_llama.py            # 807 MB GGUF, once
uv run python -m aura --demo                   # demo: X³ formula + physics news
uv run python -m aura "quelle est la capitale de la France ?"
uv run python -m aura --chat                   # chat with memory

🏗 Architecture

flowchart TD
subgraph group_entry["Entry and orchestration"]
  node_cli["CLI and chat<br/>[__main__.py]"]
  node_orchestrator["Answer orchestrator<br/>[orchestrateur.py]"]
end
subgraph group_reason["Routing and reasoning"]
  node_fast[("Instant answers and cache")]
  node_router["Question router<br/>[routeur.py]"]
  node_pal["Dates and units<br/>[pal.py]"]
  node_symbolic["Symbolic expert"]
  node_pot["Program-of-thoughts<br/>[raisonneur.py]"]
  node_logic["Logic solver<br/>[logique.py]"]
  node_potcode["Code sandbox<br/>[potcode.py]"]
end
subgraph group_knowledge["Facts and verification"]
  node_webmemory["Web retrieval and verification<br/>[memoire_web.py]"]
  node_factgraph[("Fact graph<br/>[graphe_faits.py]")]
end
subgraph group_generation["Language generation"]
  node_agents["Cognitive agents<br/>[agents.py]"]
end
subgraph group_runtime["Model runtime"]
  node_llm["Language model interface<br/>[llama_cerveau.py]"]
  node_adapters["LoRA adapters<br/>[adaptateurs.py]"]
  node_loraserver["Multi-LoRA server<br/>[serveur_lora.py]"]
  node_kernel["Sealed package boot<br/>[kernel.py]"]
end
node_user(("User"))
node_web(("DuckDuckGo"))
node_llama["llama.cpp model"]
node_aef[".aef package"]
node_user -->|"asks"| node_cli
node_cli -->|"submits question"| node_orchestrator
node_orchestrator -->|"checks first"| node_fast
node_orchestrator -->|"classifies"| node_router
node_orchestrator -->|"solves numeric tasks"| node_pal
node_orchestrator -->|"requests exact formulas"| node_symbolic
node_orchestrator -->|"checks reasoning steps"| node_pot
node_orchestrator -->|"solves constraints"| node_logic
node_orchestrator -->|"verifies code"| node_potcode
node_orchestrator -->|"structures response"| node_agents
node_orchestrator -->|"requests current facts"| node_webmemory
node_webmemory -.->|"searches"| node_web
node_orchestrator -->|"looks up facts"| node_factgraph
node_factgraph -->|"returns evidence"| node_orchestrator
node_orchestrator -->|"requests generation"| node_llm
node_llm -->|"generates with"| node_llama
node_orchestrator -.->|"swaps category adapter"| node_adapters
node_orchestrator -.->|"sets adapter weights"| node_loraserver
node_loraserver -.->|"serves model"| node_llama
node_adapters -.->|"mounts adapter"| node_llama
node_aef -.->|"boots from"| node_kernel
node_kernel -.->|"starts assistant"| node_orchestrator
click node_cli "https://github.com/simonc44/aura-1b/blob/main/aura/__main__.py"
click node_orchestrator "https://github.com/simonc44/aura-1b/blob/main/aura/orchestrateur.py"
click node_fast "https://github.com/simonc44/aura-1b/blob/main/aura/filtre_instantane.py"
click node_router "https://github.com/simonc44/aura-1b/blob/main/aura/routeur.py"
click node_pal "https://github.com/simonc44/aura-1b/blob/main/aura/pal.py"
click node_symbolic "https://github.com/simonc44/aura-1b/blob/main/aura/expert_symbolique.py"
click node_pot "https://github.com/simonc44/aura-1b/blob/main/aura/raisonneur.py"
click node_logic "https://github.com/simonc44/aura-1b/blob/main/aura/logique.py"
click node_potcode "https://github.com/simonc44/aura-1b/blob/main/aura/potcode.py"
click node_agents "https://github.com/simonc44/aura-1b/blob/main/aura/agents.py"
click node_webmemory "https://github.com/simonc44/aura-1b/blob/main/aura/memoire_web.py"
click node_factgraph "https://github.com/simonc44/aura-1b/blob/main/aura/graphe_faits.py"
click node_llm "https://github.com/simonc44/aura-1b/blob/main/aura/llama_cerveau.py"
click node_adapters "https://github.com/simonc44/aura-1b/blob/main/aura/adaptateurs.py"
click node_loraserver "https://github.com/simonc44/aura-1b/blob/main/aura/serveur_lora.py"
click node_kernel "https://github.com/simonc44/aura-1b/blob/main/aura/kernel.py"
classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_orchestrator,node_user toneBlue
class node_fast,node_router,node_pal,node_symbolic,node_pot,node_logic,node_potcode toneAmber
class node_webmemory,node_factgraph toneMint
class node_agents toneRose
class node_llm,node_adapters,node_loraserver,node_kernel,node_web,node_llama,node_aef toneIndigo

The pillars

The verified-intelligence layer (why a 1B stops hallucinating)

Rich mode (writing quality)

Open questions (≥ 9 words or explique/analyse/compare…) trigger a 3-step pipeline:

1. Enriched search — dual query (facts + analysis) + domain lexicon injected as keywords.
2. Masked Chain-of-Thought — planning inside <thinking> tags, stripped by regex; the user only sees the polished answer.
3. Sectioned generation — each part of the GBNF-constrained plan is written separately, with memory of previous sections (StoryWriter-lite).
4. Few-shot mimicry + double pass — style exemplars calibrate the draft, then a critique pass lists the flaws and the model rewrites: editing existing text is where a 1B statistically matches a much bigger one.

Cost: ~2-3× latency — reserved for questions that deserve it. Measured on the reference machine: fact 0.3 s, math 0.0 s, rich essay 66 s.

🎓 Teaching your AI

Aura improves from feedback with no retraining. Three levers, from easiest to deepest:

1. Correct a wrong answer — stored and injected into future prompts:

from aura import autoamelioration
autoamelioration.enregistrer_correction(
    "quel est le carre de 5", "20",   # its wrong answer
    "25",                             # the right one
    "math")

2. Feed the fact graph — anything web-verified is learned automatically; add curated facts:

from aura import graphe_faits
graphe_faits.ajouter("Canberra", "est la capitale de", "l'Australie",
                     source="manuel")

Or in bulk: python scripts/nourrir_graphe.py knowledge.jsonl (skips identity entries, tags health/law as general information).

3. Let it rehearse — verified answers join the semantic cache: ask again tomorrow, the answer comes back in ~1 ms. Wrong entries are replaced by reconsolidation (mettre_a_jour), never duplicated.

[!TIP] The fact graph only learns from web-verified content — by design, it cannot memorize a hallucination.

🔒 The .aef format + encrypted distribution

The whole system ships as one sealed binary file:

aura_system.aef (807 MB, monolithic)
├── HEADER (148 B)  magic "AURA" · version · build · CPU config · 3× SHA-256
├── CONFIG (LZMA)   auto-tuned settings compiled for the target machine
├── CODE (ZIP)      the entire aura/ python package (verified by hash)
└── WEIGHTS (raw)   the GGUF byte-for-byte (loaded directly, zero-copy)

Integrity: one altered byte anywhere → boot refused (SHA-256 over config, code and weights — tested). Optional Ed25519 signature of the file.

uv run python scripts/construire_exe.py            # -> dist/Aura.exe (~8.6 MB)
uv run python scripts/forger_aef.py --chiffrer     # -> aura_system.aef.enc (AES-256-GCM)

On the user machine (secret delivered separately, never in the file):

Aura.exe aura_system.aef.enc "your question"       # decrypt, verify, answer
Aura.exe --cache "your question"                    # next runs: instant start

[!IMPORTANT] AES-256-GCM + PBKDF2 (600 000 iterations): without the secret the payload is indistinguishable from noise, and any tampering breaks decryption. Honest note: this blocks passive copying — not a determined reverse-engineer.

⚙️ Hardware auto-tuning & GPU

Aura inspects the machine (CPU, cores, RAM, AVX2) and derives optimal settings:

python -m aura.profil_materiel

GPU support: CUDA/Vulkan build + discrete GPU → full offload; CPU-only → 0 (optimal here: 13.4 tok/s measured). Force CPU with AURA_GPU=0.

📊 Benchmarks

Same-quiz head-to-head (scripts/comparer_cerveaux.py): Llama 6/7 @ 3.0 s/answer vs MiniCPM5 3/7 @ 10.2 s/answer — MiniCPM5 is a thinking-first brain: without its native <think> phase it underperforms, with it (AURA_THINK=1) it is 3× slower. Aura's orchestration already reasons through experts, so a fast direct-answer brain wins here.

System-level quiz vs Qwen 2.5 1.5B: Aura 5/5 vs 4/5 (exact math, real-time facts, memory) — the organization beats the bigger brain on verifiable questions.

Honest limits

[!NOTE] On verifiable questions (math, facts, dates, format), Aura-1B beats bigger models by construction — they guess, it proves. Logic, code, style and knowledge are now system-compensated (perceived level: 7-8B); only deep unanchored abstract analysis stays 70B territory — the weights are still 1B, and that honesty is part of the design.

🗺 Roadmap

• Level 0: exact math, semantic cache, PAL
• Verified-intelligence layer: CRITIC, fact graph, PoT, logic solver, PoT-code
• Cognitive agents: planner, RAG compressor, style cleaner, recursive code debugger, persona router
• Dynamic LoRA hot-swapping: category adapters mounted on the live context (C-API), LRU memory registry
• .aef sealed format + Ed25519 + encrypted distribution
• Green CI (4 OS/py matrices + .aef chain + installer syntax)
• Served multi-LoRA (weights mix) + Dynamic Compute + RLSS + self-play + long-term memory
• Style mimicry (few-shot) + double-pass editing
• LoRA fine-tune on Colab — reasoning depth, keeps the 807 MB size
• MEMIT fact editing — fix long-tail facts directly in the weights
• lm-evaluation-harness — public, comparable brain scores
• Hugging Face release (.aef + Aura.exe + model card)

🧪 Tests & quality

uv run pytest -q        # 251 tests (CI: 245 + 6 skipped — no GGUF in CI)
uv run mypy aura/       # 0 error

CI (GitHub Actions) runs on Ubuntu + Windows (Python 3.11/3.12), re-validates the whole .aef chain (forge → Ed25519 signature → boot → tamper detection) on Linux, and syntax-checks the PowerShell installer.

📄 License

GPLv3 — see LICENSE. Copyleft: any derivative of Aura's multi-agent architecture must remain open-source under the same terms.