Nexus

Nexus is a modular local AI workspace for review-only administrative workflows. It keeps module boundaries explicit, and public APIs describe the business capability rather than the internal workflow engine.

Quick Start

Install the development environment, run the complete local quality suite, and exercise an offline retrieval path:

python -m pip install --editable ".[dev]"
npm install --global markdownlint-cli@0.49.0
make ci

nexus-resonance inspect \
  --store-backend memory \
  --embedding-backend hash \
  --reranker none

The smoke path uses no database, model snapshot, or external API. For the end-to-end Prefect walkthrough, continue with Getting Started. Optional local settings can be copied from .env.example.

Current Shape

	nexus.fabric	Shared technical foundation for Nexus modules. It owns strict JSON helpers, typed settings, model-client adapters, tool contracts, and reusable orchestration helpers.
	nexus.observer	Shared observability foundation. It provides Nexus-scoped logging primitives and reserves the boundary for metrics, tracing, correlation IDs, and runtime events.
	nexus.accretion	Source intake and normalization boundary. It persists incoming files and metadata, then creates normalized source views that later modules can consume.
	nexus.trajectory	First-hop routing boundary. It turns normalized, source-shaped inputs into deterministic next-boundary decisions with auditable reasons and no downstream execution.
	nexus.probe	Policy-gated fallback boundary. It evaluates bounded decision contexts when deterministic routing needs a conservative second opinion.
	nexus.orbit	Deterministic flow shell. It records a routing run, invokes Trajectory, optionally accepts Probe fallback, and returns the next step without executing it.
	nexus.resonance	Retrieval boundary. It indexes clean text or prepared chunks, embeds and retrieves candidates, reranks them, and returns source-linked context hits.
	nexus.gravitation	Context-preparation boundary. It gathers source-linked material through provider ports and prepares trusted context bundles for downstream review modules.
	nexus.impulse	Task-derivation boundary. It prepares review-only task candidates from source-shaped input and trusted context.
	nexus.modulation	Mail-reply boundary. It prepares review-only reply drafts from mail-shaped input and trusted context.
	nexus.spectrum	Document-processing boundary. It extracts validated structured data from one document into caller-provided schemas, using trusted context when supplied.
	nexus.coupling	Integration-adapter boundary. It hosts thin module-to-module adapters, including Accretion mappings, Resonance providers for Gravitation, and Orbit-to-Dilation enqueueing.
	nexus.continuum	Prefect-backed review orchestration boundary. It runs fixed source-to-review flows across existing Nexus modules, suspends for human review, and keeps V1 side-effect free.

Optional

nexus.dilation

Optional async execution boundary. It enqueues generic jobs, runs registered handlers through Redis/RQ workers, and keeps queue mechanics separate from module semantics.

Future modules can be added next to the existing boundaries. They should depend on Fabric and Observer for shared infrastructure, call other modules through public APIs, and put cross-module glue in Coupling instead of the core modules.

Architecture

Nexus is organized as explicit review-only boundaries rather than one large workflow engine. A typical source-oriented reading order is:

Fabric + Observer
  -> Accretion
  -> Trajectory (+ Probe fallback) through Orbit
  -> optional Dilation enqueueing
  -> Gravitation (+ Resonance providers)
  -> Impulse | Modulation | Spectrum
  -> Continuum for fixed Prefect review orchestration

Coupling sits between boundaries whenever one module needs another module's input model or queue adapter. Nexus currently stops at reviewed artifacts and explicit next-step decisions; approvals, ERP writes, sent mail, and other external side effects remain outside the core module boundaries.

API Documentation

The documentation index in docs/README.md groups the main onboarding path, local runtime guides, and all module API references. Module documentation describes the stable public boundaries and their settings.

Installation

The repository is configured for Python 3.11. If you use the local Nexus Conda environment, activate it and install the package:

conda activate nexus
make install

For a standalone editable pip installation:

python -m pip install --editable ".[ocr,dev]"

EasyOCR is optional and loaded lazily. Text PDFs only need the base dependencies.

Install the queue extra when using Dilation with Redis/RQ:

python -m pip install --editable ".[queue]"

Install the Prefect extra when using Continuum outside the Conda environment:

python -m pip install --editable ".[prefect]"

The PostgreSQL driver used by the central settings store and Accretion is part of the base installation.

Manual Hot Tests

Hot tests are explicit manual checks for real model and local model-snapshot paths. They are excluded from make ci and from the default test target.

OpenRouter-backed LLM hot tests use qwen/qwen3-32b by default:

NEXUS_RUN_HOT_LLM=1 OPENROUTER_API_KEY=... make test-hot-llm

Override the OpenRouter model when needed:

make test-hot-llm HOT_OPENROUTER_MODEL=qwen/qwen3-32b

Local RAG hot tests require the embedding and reranking snapshots under models/:

python models/snapshot_download.py
make test-hot-rag

Hot tests assert stable structure, evidence handling, and review-only behavior. They do not assert exact model wording.

Runtime State

Local runtime artifacts are written below runtime/ by default:

• redis/: local Redis development data when make redis-up is used.
• postgres/: local PostgreSQL development data when make postgres-up is used. It contains separate local databases for module data and settings.
• pgadmin/: local pgAdmin development data when make pgadmin-up is used.
• accretion/: copied source files and normalized attachment payloads when Accretion ingests source items.

These files are local development state. Extracted business data is not persisted by the Spectrum CLI.

Return to a fresh local checkout shape after demos, hot tests, or integration runs:

make pristine-local CONFIRM=pristine-local

This removes ignored runtime data, caches, and generated local artifacts. Local model files and snapshots under models/ are preserved. .env is preserved unless CONFIRM_DELETE_ENV=delete-env is also provided.

Local Redis

Dilation can use a local Redis development service:

make redis-up
make redis-ping
make redis-down

The default Dilation Redis URL is redis://127.0.0.1:6379/0. Override it with NEXUS_DILATION_REDIS_URL when needed. The Docker Redis service is for local development and integration tests, not a production Redis deployment.

Local PostgreSQL

Accretion and the central settings store can use a local PostgreSQL development service:

make postgres-up
make postgres-settings-db
make postgres-ping
make postgres-down

The default Accretion database URL is postgresql+psycopg://nexus:nexus@127.0.0.1:5432/nexus_accretion. Override it with NEXUS_ACCRETION_DATABASE_URL when needed. The default central settings database URL is postgresql+psycopg://nexus:nexus@127.0.0.1:5432/nexus_settings. Override it with NEXUS_SETTINGS_DATABASE_URL when needed.

The Docker PostgreSQL service is for local development and integration tests, not a production database deployment.

Optional pgAdmin UI:

make pgadmin-up
make pgadmin-down

Open http://127.0.0.1:5050 and log in with admin@nexus.dev / nexus. When adding the PostgreSQL server in pgAdmin, use postgres as the host, 5432 as the port, nexus_accretion or nexus_settings as the database, and nexus / nexus as user and password.

Local llama.cpp

Fabric defaults to an OpenAI-compatible llama.cpp server at http://127.0.0.1:8000/v1. Start it with Docker:

make llama-serve
make llama-logs
make llama-down

By default, the server expects models/Qwen3-4B-Instruct-2507-Q5_K_M.gguf. Override the model or port when needed:

make llama-serve MODEL_PATH=/path/to/model.gguf PORT=8001

Continuum also defaults to Fabric profile local, even when the persisted Fabric active profile points somewhere else. External OpenRouter or OpenAI-compatible runtimes are used only when a run explicitly passes a different --fabric-profile and the matching secret, such as OPENROUTER_API_KEY, is present in the worker process.

Local Prefect

Continuum uses Prefect for the flow graph, task state, logs, artifacts, and the human review suspension point. The local stack is isolated from Dilation and stores runtime data under runtime/prefect/:

make continuum-local-up
make continuum-deploy
make continuum-start SOURCE_JSON='{"source_type":"email","title":"Termin","body_text":"Koennten Sie bitte eine Rueckmeldung geben?"}'
make prefect-logs
make prefect-down

Open http://127.0.0.1:4200 for the Prefect UI. continuum-local-up starts PostgreSQL/settings DB and Prefect. Start llama.cpp separately with make llama-up when configured runs should call the local model.

The Docker worker mounts the repository at /workspace, sets NEXUS_CONTINUUM_SOURCE_ROOT=/workspace, and forwards OPENROUTER_API_KEY from the host environment when it is present. File-backed flow runs can therefore use repo-relative paths such as sample_data/mails/documents/inbox/inbox_000013.eml.

Sample Data

sample_data/ contains shared local fixture corpora for tests and local demos:

• sample_data/offers/: ten generated German offer PDFs, metadata, and master data.
• sample_data/mails/: synthetic one-month mailbox corpus with inbox/sent email documents, neutral runtime metadata, and separate gold evaluation cases.
• sample_data/knowledge/: a German Wikipedia article preparer and prepared Resonance chunks.

Regenerate the offer fixtures from master data with:

python sample_data/offers/generate_all.py --clean

Quality Checks

Run the full local suite:

make ci

Run only service-backed or optional-store integration tests:

make test-integration

Run them against local Docker Redis and PostgreSQL services:

make test-integration-local

Build the package separately when needed:

python -m build