Use built-in and third-party plugins

Plugins connect the Scientific Agent research loop to domains, solvers, evaluators, and reporting tools. A run authorizes named capabilities such as toy.evaluate; it does not give the Reasoner unrestricted access to local programs.

Plugin states

The Plugins page exposes these states:

State Meaning
Available A catalog declaration exists, but it is not installed
Installed Stored and validated, but code loading is not enabled
Enabled Available to new runs; plugin code will be loaded
Disabled Installed but not offered to new runs
Unavailable Dependencies or environment requirements are missing

An existing research contract retains its plugin and capability records. Installing, disabling, or updating a plugin primarily affects new runs.

Capabilities shipped with the distribution

The exact list depends on packaging and optional dependencies. Settings → Plugins or /api/v1/capabilities is authoritative for the current machine.

Plugin Main capabilities Typical use
Toy Dynamics toy.evaluate Offline onboarding and health checks
Local Executor execution.local.run Run generated local jobs in a controlled workspace
Xsuite Beam Dynamics beam.xsuite.track_particles, beam.xsuite.generate_stability_dataset Particle tracking and data generation in the reference accelerator lattice
Model Evaluation evaluation.classification.evaluate Trusted evaluation of classification predictions
Three-Body Trajectory Evaluation evaluation.three_body_trajectory.evaluate Trusted evaluation of three-body trajectory predictions
Scientific Analysis scientific.analysis.analyze Analyze datasets, models, and evaluations
Scientific Knowledge scientific.evidence.extract, and others Evidence, claims, hypotheses, and verification records
Report Generator scientific.report.generate Markdown scientific reports and SVG figures

The repository also contains two runnable teaching domain plugins:

  • physics.three_body for three-body integration and surrogate dataset generation;
  • tutorial.oscillator, the zero-dependency example built in this guide.

Geant4 Transport and Plasma Simulation are dependency-bearing capability declarations in the available catalog. They can be enabled only when their environment requirements and a loadable adapter are present. Seeing a card does not mean the solver is installed.

Use a plugin in Desktop

  1. Open Settings → Plugins.
  2. Browse Core or Domain categories.
  3. Expand a plugin and inspect capabilities, inputs, metric outputs, dependencies, and Runtime requirements.
  4. Choose Install for an Available plugin.
  5. Once dependencies are satisfied, choose Enable.
  6. Create a new run and select only the capabilities needed for that study.

If dependencies are missing, the app does not run pip install for you. Review the declared version constraints, install them in the Python environment used by Scientific Agent, then reopen or refresh the Plugins page.

Use a plugin from the CLI

The plugins list accepts repository-relative directories, absolute directories, and built-in aliases:

plugins:
  - examples/plugins/three_body_solver
  - executor.local

capabilities:
  - physics.three_body.solve
  - execution.local.run

Run it normally:

scientific-agent run my-study.yaml

When starting the Control API, repeat --plugin-dir to add discovery locations:

scientific-agent serve \
  --plugin-dir ./my-plugins/one \
  --plugin-dir ./my-plugins/two

List discovered capabilities:

curl -sS http://127.0.0.1:8000/api/v1/capabilities | jq

Install a custom ZIP

In Desktop, choose Install custom plugin and select a .zip. A valid package must:

  • contain exactly one unambiguous manifest named plugin.yaml, plugin.yml, or plugin.json;
  • provide an importable in-package entrypoint;
  • contain no absolute paths, path traversal, symlinks, encrypted entries, or duplicates;
  • be at most 10 MiB compressed, 50 MiB expanded, and 512 files.

Installation validates the ZIP and manifest without importing Python code. Code is imported only when you choose Enable. Dependencies are not installed automatically.

Choose the right capability

Open capability details and focus on:

  • required_inputs: ordinary fields required on every call;
  • artifact_inputs: existing artifacts and expected types;
  • metric_outputs: acceptance metrics the capability can support;
  • example and cost_hints: valid input shape and approximate resource cost.

If several plugins implement the same abstract capability, the detail view lists each provider. The research contract records the concrete provider so an environment change cannot silently swap implementations later.

Core and Domain

  • Domain plugins express operations in a scientific or problem domain, such as three-body integration and beam tracking.
  • Core plugins provide cross-domain infrastructure such as execution, evaluation, analysis, knowledge management, and reporting.

The category aids discovery; it does not grant higher privilege. Special authority comes from the trusted_evaluator access role, which should be reserved for independent evaluators.

Security boundary

An enabled plugin runs with the same local permissions as the Scientific Agent process. It is not sandboxed code. Install only packages from sources you trust, and inspect the manifest, dependencies, and source before enabling one.

Local Executor constrains workspaces, declared inputs and outputs, and the job protocol, but it is not a container for hostile code. Use an operating-system account, container, or VM when handling unknown plugins, unknown generated code, or valuable data.

When a plugin fails

Check in this order:

  1. It is Enabled, not merely Installed.
  2. missing_dependencies is empty.
  3. The research contract selected the correct capability.
  4. Input field names and artifact types match capability details.
  5. Failure, Jobs, and logs show no load_error or execution error.

If an upgrade changes capability names or input formats, copy the old run configuration and migrate it explicitly. Never edit a research contract after its run has started.

results matching ""

    No results matching ""