Introduction
============

**FermiLink** is a unified AI agent framework for autonomous scientific
computing on **laptops**, **workstations**, **HPC clusters**, and **cellphones**.
It combines scientific package management, workflows at different scales, and
multiple interaction interfaces in one consistent system.

What makes FermiLink practical
------------------------------

Many scientific-agent systems break down when you switch tools or scale up task
complexity. FermiLink is designed to stay consistent:

- **one uniform package-selection layer** automatically routes requests to the most suitable installed scientific packages;
- **one unified short-term/long-term memory model** for iterative and long-running work in the same workspace;
- **three distinct workflows** for computational tasks at different scales.


You can start quickly with built-in scientific packages
(``fermilink install``), and you can also turn your own local projects or paper
pipelines into reusable package knowledge with
``fermilink compile`` / ``fermilink recompile``.


Three major autonomous workflows
--------------------------------

.. figure:: _static/img/major_modes_workflow.svg
   :alt: Three major FermiLink workflows: exec for single runs, loop for iterative runs involving long SLURM or PID jobs, and research/reproduce for full research-paper-level calculations.
   :align: center
   :width: 95%


Three major FermiLink workflows are supported in FermiLink:

- ``exec``: one prompt, one agent run; suitable for short computing (< 30 minutes).
- ``loop``: autonomous iteration with memory updates, local PID and SLURM job polling, and long-running task support.
- ``research`` / ``reproduce``: planner + task-loop workflows for
  idea-to-results and paper-reproduction workflows, suitable for simulations at scale of a research paper.


Package management workflow
---------------------------

.. figure:: _static/img/package_management_workflow.svg
   :alt: FermiLink package management workflow.
   :align: center
   :width: 95%

FermiLink uses **Agent Skills** to compress knowledge for agent reasoning. It has a built-in `**Curated Computational Packages** channel <https://github.com/orgs/skilled-scipkg/repositories>`_ 
which stores the full source-code tree + **Agent Skills** containing the entry-level tutorials and the informative file map of this source-code tree. This design allows AI agents
to **efficiently locate and access the most relevant documentation, tutorials, and source code functions** in the source code tree **for reasoning**. Common pitfalls for using the package are also highlighted in **Agent Skills**. 
`This GitHub channel <https://github.com/orgs/skilled-scipkg/repositories>`_  now supports more than 150 scientific packages across multiple domains.

Users can also easily use the command line tools in FermiLink to add their own local packages. Additionally, users can add pipelines in research papers, database, or unpublished secrets 
as additional **Agent Skills** for one specific package. This package knowledge base, once installed, is used across all jobs in FermiLink globally.

How to choose your starting point
---------------------------------

1. Use ``fermilink exec`` when you need a direct result quickly.
2. Use ``fermilink loop`` when a task needs iterative refinement or long simulation waits (say, > 30 minutes).
3. Use ``fermilink reproduce`` or ``fermilink research`` when you need
   publication-scale workflows.
4. Use ``fermilink compile`` / ``fermilink recompile`` when your package
   knowledge base should be created and updated.

See :doc:`architecture` for the full runtime flow and contracts.