Synthia

Synthia is an agent companion for working with Synthesizer.

Synthia bundles an Agent Skill with a local MCP server so Claude Code, OpenCode, and other MCP-capable agents can answer Synthesizer questions from the user's actual installation, and from the project's Syndex data catalogue, rather than inflating context and relying on incomplete local memory. Note that it is not designed as a replacement for a human user but simply aims to make learning and using Synthesizer a frictionless experience. For more on these mechanisms see the MCP documentation and, for Agent Skills, agentskills.io.

Installation

Synthia requires Synthesizer to be installed first. You'll need to install Synthia in the same environment containing Synthesizer, and you'll need to launch your agent from that same environment.

For agent-assisted installation, send your coding agent this prompt:

Read https://raw.githubusercontent.com/synthesizer-project/synthia/main/INSTALL.md and install Synthia for me.

Or install it directly (which is essentially all the install prompt does):

pip install cosmos-synthia
synthia-install

To install an unreleased change, point pip at the repository instead:

pip install 'git+https://github.com/synthesizer-project/synthia.git'

In case you care what the install does...

synthia-install links the bundled skill at ~/.claude/skills/synthia (which OpenCode also loads, so one copy serves both clients), registers synthia-mcp with Claude Code when the claude CLI is available, and adds it to OpenCode's ~/.config/opencode/opencode.json. --dry-run shows what it would change, --uninstall reverses it. Restart your client afterwards: skills load per session, but MCP servers only load at client start.

Usage

Synthia has no interface of its own. Once installed, ask your agent about Synthesizer in plain language: the skill triggers on the subject matter, and the agent calls the MCP tools when it needs an exact local fact, a published catalogue record, or a support operation.

cd ~/my-analysis
claude # or opencode

> Compare the spectra of a parametric stellar population with little and with
> heavy dust attenuation, and plot them.

What sort of thing can Synthia help with?

• "Do any of my local grids cover the metallicity range I need, and do they contain H-beta?" — answered from the actual grid files you have, not from memory and without delving into the online documentation.
• "Is there a published BPASS grid with emission lines, and does it reach Z = 1e-5?" — answered from the Syndex catalogue, including axes, spectra, lines, size, checksum and citations, without downloading the file. Synthia then hands you the synthesizer-download command to run yourself.
• "Why is spectra['total'] a KeyError after I built a TotalEmission model with fesc=0?" — a documented Synthesizer emission model initialisation trap.
• "Show me what my BPASS v2.2.1 grid's spectra look like at 10 Myr and Z=0.01." — renders a figure with known plotting methods and returns its path.
• "Adapt this script to the Synthesizer version I actually have installed." — take outdated scripts and update them for your specific Synthesizer install.
• "Generate a young and old galaxy with black holes and produce plots showing whether JWST can detect the AGN contribution for a set of reasonable redshifts and galaxy properties." — render a complex astrophysics question by applying its knowledge of the local installation and available grids without the need to build up the quick script yourself.

Synthia is at its most useful where an answer depends on your specific installation: which version, which grids, which spectra those grids hold — and on what the project has published that you do not have yet. It is least useful for pure astrophysics questions not specific to Synthesizer, which the model can answer without it.

Synthia can also answer questions about the Syndex catalogue, the project's database of published grids, instruments and test data: what exists, what a grid contains, and which release to take. Downloading stays with synthesizer-download, which Synthia gives you the command for rather than running.

Performance

The benchmarks directory contains a series of tests for common Synthia prompts. These were run on a bare agent (i.e. no plugins, MCPs, or skills) using Sonnet 5 with and without Synthia. Below is a comparison of the usage and runtime, measured over the 15 cases that predate the catalogue tools.

Note that every Synthia script produced a correct result or a runnable script while baseline did in all but one case. Synthia is designed to be correct more often but importantly it'll get to the correct answer with less resource and often faster.

Development

See CONTRIBUTING.md for the full development workflow.

Licence

GNU General Public License v3.0.