Architecture
============

This page gives a high-level overview of how FermiLink is organized.

Repository layout
-----------------

::

   FermiLink/
   ├── src/fermilink/          # core library
   │   ├── agents/             # AI provider adapters and runtime behavior
   │   ├── cli/                # command-line interface
   │   │   └── commands/       # subcommand implementations
   │   ├── packages/           # scientific-package registry and overlays
   │   ├── runner/             # FastAPI backend for run execution
   │   └── web/                # Chainlit-based web chat UI
   ├── tests/                  # test suite
   └── docs/                   # Sphinx documentation source

Core (``src/fermilink``)
^^^^^^^^^^^^^^^^^^^^^^^^

- ``agents/`` — pluggable AI-provider adapters (model selection, streaming, environment setup).
- ``providers.py`` — provider-agnostic wrappers used by the CLI and runner.
- ``agent_runtime.py`` — persisted runtime settings (provider, model, sandbox mode).
- ``config.py`` — path resolution for FermiLink's home directory.
- ``services.py`` — process lifecycle helpers for the runner and web server.
- ``router_rules.py`` — package-aware routing rule sync.

Packages (``src/fermilink/packages``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- ``package_registry.py`` — install, list, and manage scientific packages.
- ``package_core.py`` — overlay engine that injects package knowledge into sessions.
- ``curated_channels.py`` — built-in catalog of curated packages.

CLI (``src/fermilink/cli``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^

- ``commands/`` — one module per subcommand (packages, sessions, services, etc.).
- ``zero_arg.py`` — the guided entry point when you run bare ``fermilink``.
- ``exec_runtime.py`` — subprocess execution helpers.

Runner (``src/fermilink/runner``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- ``app.py`` — FastAPI server that executes runs and streams results via SSE.
- ``admission.py`` — concurrency and admission-queue management.

Web UI (``src/fermilink/web``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- ``app.py`` — Chainlit chat application and session orchestration.
- ``*_helpers.py`` — routing, auth, storage, and activity helpers.