jutul-agent 0.1.0__tar.gz

jutul_agent-0.1.0/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+
+# uv.lock is committed for reproducible installs (see [tool.uv] in pyproject.toml).
+
+# Generated by hatch-vcs at build time from the latest git tag (see pyproject.toml).
+src/jutul_agent/_version.py
+
+# Secrets and local editor config
+.env
+.env.*
+!.env.example
+.mcp.json
+
+# Project state
+.jutul-agent/
+
+# Julia lockfiles
+src/jutul_agent/**/Manifest.toml
+
+# The shared JutulAgent package synced into a sim env template for in-place
+# instantiate (CI/tests). The canonical source lives in julia_runtime/ and the
+# per-sim JutulAgent<Sim> packages are tracked; only these synced copies are not.
+src/jutul_agent/simulators/*/julia_env/JutulAgent/
+
+# IDE
+.vscode/
+.idea/
+
+# Claude Code: share project commands, keep local settings/worktrees out.
+.claude/*
+!.claude/commands/
+.claude/settings.local.json
+
+# Scratch findings the `/review-mine` command writes before ingesting.
+.jutul-review/
+
+# OS
+.DS_Store
+Thumbs.db
+site/
+
+# Local scratch / lab output
+.jutul-review/
+lab-out/

jutul_agent-0.1.0/AGENTS.md

@@ -0,0 +1,142 @@
+# jutul-agent
+
+## Purpose
+
+jutul-agent is an assistant for Julia scientific simulation work on the Jutul
+ecosystem, built on Deep Agents.
+
+## Working rules
+
+- Prefer the live Julia session and simulator source code over model memory.
+- Use the persistent Julia REPL incrementally. Run the smallest useful probe
+  first, inspect the result, then extend.
+- Treat the installed simulator packages as the source of truth for APIs and
+  examples.
+- Keep Julia execution serialized unless the runtime explicitly supports
+  concurrency.
+- Prefer Deep Agents memory and skills for reusable guidance; keep custom
+  Python focused on Julia execution, simulator inspection, and trace capture.
+
+## Validation
+
+- Default suite (no Julia): `uv run pytest -q -m "not integration"`
+- Integration suite (requires Julia + an instantiated env): `uv run pytest -q -m integration`.
+  Envs instantiate from `Project.toml` + `[sources]`.
+  `tests/test_simulators_smoke.py` loads each simulator with `using <Sim>`.
+- Live LLM (humans only, needs API key): `uv run pytest tests/live/`
+- Update transcript / report snapshots after renderer changes:
+  `uv run pytest --snapshot-update tests/test_transcript_html.py tests/test_transcript.py tests/test_report_renderer.py`
+- Python style (matches CI): `uv run ruff check .` then `uv run ruff format .`
+- After editing Python, run `uv run ruff format` on touched paths (or rely on
+  format-on-save / pre-commit if installed).
+- Web UI (React + TypeScript in `interfaces/server/webapp`): `npm install`, then
+  `npm test` (vitest) and `npm run typecheck`. It ships **pre-built** — after any
+  change under `webapp/src`, run `npm run build` and commit the regenerated
+  `interfaces/server/web_dist`. That committed bundle is what the server serves,
+  so end users install with `uv`/`pip` and never need Node.
+
+## Continuous integration
+
+Two GitHub Actions workflows:
+
+- `ci.yml`: every push/PR. `lint` (ruff); `test` across Linux/Windows/macOS
+  (`pytest -m "not integration"`, no Julia); `julia-integration` (Linux only:
+  runs `test_juliakernel.py` against base Julia, which needs no env).
+- `simulators.yml`: per-simulator smoke matrix (`jutuldarcy`, `battmo`,
+  `fimbul`, `mocca`; Linux). On PR + push to `main`, a weekly Monday run
+  (catches upstream breakage), and manual dispatch. Each job instantiates the
+  env from `Project.toml` and runs `test_simulators_smoke.py`.
+
+## Local git hooks
+
+One-time per clone: `uv run pre-commit install`. Commits then run Ruff format
+and check on staged `.py` files. To verify the whole tree like CI:
+`uv run pre-commit run --all-files`.
+
+## Important paths
+
+- `src/jutul_agent/paths.py`: the three runtime anchors (`PACKAGE_ROOT`
+  (install), `workspace_root()` (CWD), `state_home()` (sessions)) and the path
+  policy (`resolve_in_workspace`, `is_host_path`), the one place that maps
+  agent-visible paths to real files.
+- `src/jutul_agent/workspace.py`: workspace config
+  (`.jutul-agent/config.toml`), simulator auto-detect, Julia-env bootstrap.
+- `src/jutul_agent/session.py`: `Session`, the unit of work for one
+  invocation.
+- `src/jutul_agent/models.py`: provider metadata and the model catalog
+  discovery. `src/jutul_agent/display.py`: display detection and Xvfb
+  management for headless plotting.
+- `src/jutul_agent/agent/builder.py`: deepagents wiring (composite backend,
+  HarnessProfile registration, `build_agent` entry point). Custom tools sit
+  alongside (`tools.py`, `plot_julia.py`, `memory.py`, `approval.py`,
+  `turns.py`, and `added_dirs.py`, which records `/add-dir` folders);
+  `tool_labels.py` holds the one friendly name per tool shared by the TUI,
+  approval prompt, and transcript. The Julia-side plot capture lives in the
+  `julia_runtime/JutulAgent` package. The full system prompt is assembled in
+  `prompts.py` (each rule stated once).
+- `src/jutul_agent/simulators/`: adapter dataclass, registry, env bootstrap +
+  launch-time preparation (`env_setup.prepare_workspace_env`), shared skills,
+  and one folder per simulator (see below).
+- `src/jutul_agent/julia/`: the `JuliaSession` Protocol (`session.py`) and the
+  Julia toolchain checks (`requirements.py`).
+- `src/jutul_agent/juliakernel/`: the backend, a self-contained, supervised
+  Julia runtime (`kernel.py` + stdlib-only `server.jl`) with live output and
+  SIGINT interrupt. Splittable into a standalone package.
+- `src/jutul_agent/trace/`: SQLite event log and `TraceRecorder` middleware.
+- `src/jutul_agent/transcript/`: renderers that consume a trace
+  (HTML transcript, markdown transcript, investigation report).
+- `src/jutul_agent/interfaces/tui/approval.py`: HITL decision policy and the
+  approval card markdown.
+- `src/jutul_agent/interfaces/`: `cli`, the Textual `tui`, and the `server`
+  (FastAPI REST + per-session WebSocket). The browser UI is a React + TypeScript
+  app in `server/webapp/` (see its README), built into `server/web_dist/`
+  (committed and shipped, so an install needs no Node).
+- `tests/`: end-to-end, chat, CLI, and tool coverage. `tests/integration/`
+  needs Julia; `tests/live/` needs an LLM provider key.
+
+## Per-simulator layout
+
+Each simulator lives under `src/jutul_agent/simulators/<name>/` and owns
+exactly three things:
+
+- `adapter.py`: constructs the `SimulatorAdapter`. Set
+  `module_dir = Path(__file__).resolve().parent` so the base class can
+  derive `julia_env_template_path` and `skills_dir`.
+- `julia_env/`: `Project.toml` declaring the deps the agent can `using`, plus a
+  per-simulator `JutulAgent<Sim>/` warm package (a local `[sources]` path dep whose
+  `@recompile_invalidations` + `@compile_workload` bakes that simulator's
+  GLMakie-aware solve/plot into the precompile cache, so the first solve is fast).
+  The shared, sim-agnostic `JutulAgent` package (figure capture, ensemble helpers,
+  generic-Makie warm-up) has a single source in `src/jutul_agent/julia_runtime/` and
+  is copied into the env at bootstrap (also a relative `[sources]` dep). The
+  `Manifest.toml` is generated on instantiate (gitignored). The whole `julia_env/`
+  folder is copied into a workspace on bootstrap, so the relative `[sources]` paths
+  keep resolving.
+- `skills/<skill-name>/SKILL.md`: markdown skills surfaced via the
+  deep-agents skill system.
+
+Add a simulator by creating that folder and one entry in
+`simulators/registry.py`. Custom subagent factories, when they land, go on
+the adapter's `subagent_factories` tuple.
+
+## deepagents / langgraph private-surface contacts
+
+We pin deepagents (see `[tool.uv] exclude-newer` in `pyproject.toml`) and
+touch a few non-public surfaces. When bumping the pin, re-verify each:
+
+- `agent/tools.py`: reads `langgraph.pregel._tools._tool_call_writer`
+  (ContextVar) to stream live Julia output as tool-output deltas.
+  Import-guarded: if it moves, streaming silently disables.
+- `agent/turns.py` + `tests/fakes.py`: consume the v3 `astream_events`
+  typed projections (`run.messages` / `run.tool_calls` / `run.interrupts` /
+  `run.output`); the fakes mirror that shape, so a projection change shows up
+  as test failures.
+- `agent/backend.py`: subclasses `CompositeBackend` (overriding `grep`/`glob`
+  so patterns recurse) and `LocalShellBackend` (overriding `write`/`edit`/
+  `execute` to refuse depot writes, reading `cwd` to resolve relative paths).
+  A subclass breaks loudly if a base method's signature moves. After the
+  real-paths refactor nothing routes through a mount, so `added_dirs.py` only
+  records the added folders; every tool already reaches them by absolute path.
+- `tests/test_builder.py`: imports
+  `deepagents.profiles.harness.harness_profiles._harness_profile_for_model`
+  to assert our profile resolves for built model instances.

jutul_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SINTEF
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jutul_agent-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: jutul-agent
+Version: 0.1.0
+Summary: Specialized scientific agent for AD-enabled simulators built on the Jutul framework.
+Project-URL: Homepage, https://github.com/SINTEF-agentlab/jutul-agent
+Project-URL: Documentation, https://sintef-agentlab.github.io/jutul-agent/
+Project-URL: Repository, https://github.com/SINTEF-agentlab/jutul-agent
+Project-URL: Issues, https://github.com/SINTEF-agentlab/jutul-agent/issues
+Author-email: Jakob Torben <jakob.torben@sintef.no>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.12
+Requires-Dist: deepagents>=0.6.10
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: langchain-google-genai>=4.2.2
+Requires-Dist: langchain-ollama>=1.1.0
+Requires-Dist: langchain-openai>=0.2
+Requires-Dist: langgraph-checkpoint-sqlite>=3.1.0
+Requires-Dist: markdown-it-py[linkify]>=4.0
+Requires-Dist: pillow>=12.2.0
+Requires-Dist: pygments>=2.17
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: textual>=8.2.6
+Requires-Dist: uvicorn[standard]>=0.30
+Provides-Extra: eval
+Requires-Dist: anthropic>=0.105.0; extra == 'eval'
+Requires-Dist: inspect-ai<0.4,>=0.3.238; extra == 'eval'
+Requires-Dist: openai>=2.40.0; extra == 'eval'
+Description-Content-Type: text/markdown
+
+# jutul-agent
+
+[![CI](https://github.com/SINTEF-agentlab/jutul-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/SINTEF-agentlab/jutul-agent/actions/workflows/ci.yml)
+[![Simulators](https://github.com/SINTEF-agentlab/jutul-agent/actions/workflows/simulators.yml/badge.svg)](https://github.com/SINTEF-agentlab/jutul-agent/actions/workflows/simulators.yml)
+[![Docs](https://img.shields.io/badge/docs-website-0f4c5c)](https://sintef-agentlab.github.io/jutul-agent/)
+[![PyPI](https://img.shields.io/pypi/v/jutul-agent.svg)](https://pypi.org/project/jutul-agent/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A scientific AI agent for differentiable simulators built on the
+[Jutul](https://github.com/sintefmath/Jutul.jl) framework. Ask for a
+simulation in plain language. The agent sets it up, runs it, analyses and
+plots the results, and iterates: fixing mistakes and refining the next run.
+
+<p align="center">
+  <a href="https://github.com/sintefmath/JutulDarcy.jl"><img src="https://raw.githubusercontent.com/sintefmath/JutulDarcy.jl/main/docs/src/assets/logo_wide.png" alt="JutulDarcy" height="42"></a>&nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/BattMoTeam/BattMo.jl"><img src="https://raw.githubusercontent.com/BattMoTeam/BattMo.jl/main/docs/src/assets/battmologo_text.png" alt="BattMo" height="74"></a>&nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/sintefmath/Fimbul.jl"><img src="https://raw.githubusercontent.com/sintefmath/Fimbul.jl/main/docs/src/assets/logo_text_wide.png" alt="Fimbul" height="50"></a>&nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/sintefmath/Mocca.jl"><img src="https://raw.githubusercontent.com/sintefmath/Mocca.jl/main/docs/src/assets/mocca_small_transparent.png" alt="Mocca" height="62"></a>
+</p>
+
+<p align="center">
+  <img src="docs/images/web-fimbul.png" alt="jutul-agent web UI: a Fimbul geothermal doublet with the 3D temperature field over time" width="47%">
+  &nbsp;&nbsp;&nbsp;
+  <img src="docs/images/web-battmo.png" alt="jutul-agent web UI: a BattMo discharge-rate investigation with plots and a report" width="47%">
+</p>
+<p align="center"><sub>The browser UI (<code>jutul-agent web</code>): chat on the left; interactive plots and reports pinned in a canvas on the right. On the left, a Fimbul geothermal doublet showing the 3D temperature field around the wells over time. On the right, a BattMo C-rate study with voltage curves, an attempts map, and a written report.</sub></p>
+
+## Quickstart
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and Julia
+(via [juliaup](https://github.com/JuliaLang/juliaup)). Then:
+
+```sh
+uv tool install jutul-agent
+jutul-agent key openai            # save a provider key (Anthropic and Google work too)
+
+mkdir my-study && cd my-study
+jutul-agent init --sim battmo     # jutuldarcy | battmo | fimbul | mocca
+jutul-agent web                   # browser UI, or: tui, or run "<prompt>"
+```
+
+Local models through [Ollama](https://ollama.com) need no key. `init`
+precompiles the Julia and plotting stacks once (a few minutes), so sessions
+then start in seconds, and `jutul-agent doctor` checks the setup if anything
+looks wrong. Keep it current with `jutul-agent upgrade`.
+
+One folder is bound to one simulator and its Julia environment, so use a
+separate folder for each. The browser UI opens at <http://127.0.0.1:8742> and
+runs locally for a single trusted user. The full [installation and usage
+guide](https://sintef-agentlab.github.io/jutul-agent/usage/) covers workspaces,
+interfaces, and models; to work on jutul-agent itself, clone the repo (see
+[Development](#development)).
+
+## Supported simulators
+
+| `--sim` | Package | Domain |
+|---|---|---|
+| `jutuldarcy` | [JutulDarcy.jl](https://github.com/sintefmath/JutulDarcy.jl) | Reservoir / multi-phase flow |
+| `battmo` | [BattMo.jl](https://github.com/BattMoTeam/BattMo.jl) | Lithium-ion (and other) battery cells |
+| `fimbul` | [Fimbul.jl](https://github.com/sintefmath/Fimbul.jl) | Geothermal (ATES, BTES, doublet, EGS) |
+| `mocca` | [Mocca.jl](https://github.com/sintefmath/Mocca.jl) | Adsorption-based CO₂ capture (PSA / VSA / TSA) |
+
+## What makes it work for scientific computing
+
+- A persistent Julia REPL per session. State, loaded packages, and compiled
+  methods carry across turns, and a first solve is fast because each
+  simulator ships a precompiled warm package.
+- The agent reads real source. Every package in the environment is on disk at
+  its real `pkgdir` path (read-only in the shared depot), so answers come from
+  the installed version, not from memory.
+- Everything is recorded. Each session writes a trace of every message, tool
+  call, and artifact. Transcripts and the benchmark grade against it.
+- Models are interchangeable: OpenAI, Anthropic, Google, or local models via
+  Ollama, switchable mid-session.
+
+## Documentation
+
+The full documentation lives at
+[sintef-agentlab.github.io/jutul-agent](https://sintef-agentlab.github.io/jutul-agent/)
+(source in [docs/](docs/)): using the agent, how it works (architecture,
+the Julia kernel, the trace), and extending it (adding a simulator,
+improving the agent, evaluation).
+
+## Development
+
+Work from a clone instead of a tool install. `uv run` resolves the
+`jutul-agent` command from the checkout, so run every command through it
+(`uv run jutul-agent ...`); upgrade with `git pull && uv sync`.
+
+```sh
+git clone https://github.com/SINTEF-agentlab/jutul-agent
+cd jutul-agent
+uv sync --extra eval
+uv run pre-commit install
+
+uv run ruff check .              # lint
+uv run pytest                    # unit tests (integration and live skipped)
+uv run pytest -m integration     # adds the Julia-requiring tests
+uv run jutul-agent eval canary   # bench canary
+```
+
+Developed at [SINTEF](https://www.sintef.no/en/).

jutul_agent-0.1.0/README.md

@@ -0,0 +1,102 @@
+# jutul-agent
+
+[![CI](https://github.com/SINTEF-agentlab/jutul-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/SINTEF-agentlab/jutul-agent/actions/workflows/ci.yml)
+[![Simulators](https://github.com/SINTEF-agentlab/jutul-agent/actions/workflows/simulators.yml/badge.svg)](https://github.com/SINTEF-agentlab/jutul-agent/actions/workflows/simulators.yml)
+[![Docs](https://img.shields.io/badge/docs-website-0f4c5c)](https://sintef-agentlab.github.io/jutul-agent/)
+[![PyPI](https://img.shields.io/pypi/v/jutul-agent.svg)](https://pypi.org/project/jutul-agent/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A scientific AI agent for differentiable simulators built on the
+[Jutul](https://github.com/sintefmath/Jutul.jl) framework. Ask for a
+simulation in plain language. The agent sets it up, runs it, analyses and
+plots the results, and iterates: fixing mistakes and refining the next run.
+
+<p align="center">
+  <a href="https://github.com/sintefmath/JutulDarcy.jl"><img src="https://raw.githubusercontent.com/sintefmath/JutulDarcy.jl/main/docs/src/assets/logo_wide.png" alt="JutulDarcy" height="42"></a>&nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/BattMoTeam/BattMo.jl"><img src="https://raw.githubusercontent.com/BattMoTeam/BattMo.jl/main/docs/src/assets/battmologo_text.png" alt="BattMo" height="74"></a>&nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/sintefmath/Fimbul.jl"><img src="https://raw.githubusercontent.com/sintefmath/Fimbul.jl/main/docs/src/assets/logo_text_wide.png" alt="Fimbul" height="50"></a>&nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/sintefmath/Mocca.jl"><img src="https://raw.githubusercontent.com/sintefmath/Mocca.jl/main/docs/src/assets/mocca_small_transparent.png" alt="Mocca" height="62"></a>
+</p>
+
+<p align="center">
+  <img src="docs/images/web-fimbul.png" alt="jutul-agent web UI: a Fimbul geothermal doublet with the 3D temperature field over time" width="47%">
+  &nbsp;&nbsp;&nbsp;
+  <img src="docs/images/web-battmo.png" alt="jutul-agent web UI: a BattMo discharge-rate investigation with plots and a report" width="47%">
+</p>
+<p align="center"><sub>The browser UI (<code>jutul-agent web</code>): chat on the left; interactive plots and reports pinned in a canvas on the right. On the left, a Fimbul geothermal doublet showing the 3D temperature field around the wells over time. On the right, a BattMo C-rate study with voltage curves, an attempts map, and a written report.</sub></p>
+
+## Quickstart
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and Julia
+(via [juliaup](https://github.com/JuliaLang/juliaup)). Then:
+
+```sh
+uv tool install jutul-agent
+jutul-agent key openai            # save a provider key (Anthropic and Google work too)
+
+mkdir my-study && cd my-study
+jutul-agent init --sim battmo     # jutuldarcy | battmo | fimbul | mocca
+jutul-agent web                   # browser UI, or: tui, or run "<prompt>"
+```
+
+Local models through [Ollama](https://ollama.com) need no key. `init`
+precompiles the Julia and plotting stacks once (a few minutes), so sessions
+then start in seconds, and `jutul-agent doctor` checks the setup if anything
+looks wrong. Keep it current with `jutul-agent upgrade`.
+
+One folder is bound to one simulator and its Julia environment, so use a
+separate folder for each. The browser UI opens at <http://127.0.0.1:8742> and
+runs locally for a single trusted user. The full [installation and usage
+guide](https://sintef-agentlab.github.io/jutul-agent/usage/) covers workspaces,
+interfaces, and models; to work on jutul-agent itself, clone the repo (see
+[Development](#development)).
+
+## Supported simulators
+
+| `--sim` | Package | Domain |
+|---|---|---|
+| `jutuldarcy` | [JutulDarcy.jl](https://github.com/sintefmath/JutulDarcy.jl) | Reservoir / multi-phase flow |
+| `battmo` | [BattMo.jl](https://github.com/BattMoTeam/BattMo.jl) | Lithium-ion (and other) battery cells |
+| `fimbul` | [Fimbul.jl](https://github.com/sintefmath/Fimbul.jl) | Geothermal (ATES, BTES, doublet, EGS) |
+| `mocca` | [Mocca.jl](https://github.com/sintefmath/Mocca.jl) | Adsorption-based CO₂ capture (PSA / VSA / TSA) |
+
+## What makes it work for scientific computing
+
+- A persistent Julia REPL per session. State, loaded packages, and compiled
+  methods carry across turns, and a first solve is fast because each
+  simulator ships a precompiled warm package.
+- The agent reads real source. Every package in the environment is on disk at
+  its real `pkgdir` path (read-only in the shared depot), so answers come from
+  the installed version, not from memory.
+- Everything is recorded. Each session writes a trace of every message, tool
+  call, and artifact. Transcripts and the benchmark grade against it.
+- Models are interchangeable: OpenAI, Anthropic, Google, or local models via
+  Ollama, switchable mid-session.
+
+## Documentation
+
+The full documentation lives at
+[sintef-agentlab.github.io/jutul-agent](https://sintef-agentlab.github.io/jutul-agent/)
+(source in [docs/](docs/)): using the agent, how it works (architecture,
+the Julia kernel, the trace), and extending it (adding a simulator,
+improving the agent, evaluation).
+
+## Development
+
+Work from a clone instead of a tool install. `uv run` resolves the
+`jutul-agent` command from the checkout, so run every command through it
+(`uv run jutul-agent ...`); upgrade with `git pull && uv sync`.
+
+```sh
+git clone https://github.com/SINTEF-agentlab/jutul-agent
+cd jutul-agent
+uv sync --extra eval
+uv run pre-commit install
+
+uv run ruff check .              # lint
+uv run pytest                    # unit tests (integration and live skipped)
+uv run pytest -m integration     # adds the Julia-requiring tests
+uv run jutul-agent eval canary   # bench canary
+```
+
+Developed at [SINTEF](https://www.sintef.no/en/).

jutul_agent-0.1.0/docs/README.md

@@ -0,0 +1,107 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+<div class="ja-hero" markdown>
+<div class="ja-hero-text" markdown>
+<h1>jutul-agent</h1>
+<p class="ja-tagline">A scientific AI agent for differentiable simulators built
+on the <a href="https://github.com/sintefmath/Jutul.jl">Jutul</a> framework.
+Ask for a simulation in plain language. The agent sets it up, runs it in a
+persistent Julia session, analyses and plots the results, and iterates:
+fixing mistakes and refining the next run.</p>
+
+[Get started](usage.md){ .md-button .md-button--primary }
+[How it works](architecture.md){ .md-button }
+</div>
+<div class="ja-terminal">
+<div class="ja-terminal-bar"><span></span><span></span><span></span>
+<div class="ja-terminal-title">jutul-agent · my-battery-run</div></div>
+<pre><code><span class="ja-t-dim">$</span> jutul-agent tui
+<span class="ja-t-prompt">&gt;</span> Set up a constant-current discharge for the
+  chen_2020 cell and plot the voltage curve.
+
+<span class="ja-t-tool">run_julia</span>  output = solve(cell_setup)
+<span class="ja-t-tool">plot_julia</span>  voltage vs time
+<span class="ja-t-ok">saved</span> artifacts/voltage_curve.png</code></pre>
+</div>
+</div>
+
+<p align="center">
+  <img src="images/web-fimbul.png" alt="jutul-agent web UI: a Fimbul geothermal doublet with the 3D temperature field over time" width="47%">
+  &nbsp;&nbsp;&nbsp;
+  <img src="images/web-battmo.png" alt="jutul-agent web UI: a BattMo discharge-rate investigation with plots and a report" width="47%">
+</p>
+<p align="center" markdown><small>The browser UI (`jutul-agent web`): chat on the left; interactive plots and
+reports pinned in a canvas on the right.</small></p>
+
+<div class="grid cards" markdown>
+
+-   :material-rocket-launch:{ .lg .middle } **Usage**
+
+    ---
+
+    Install, initialise a workspace, drive the TUI, pick models.
+
+    [:octicons-arrow-right-24: Installation and usage](usage.md) ·
+    [CLI](cli.md) ·
+    [Configuration](configuration.md) ·
+    [Models](models.md) ·
+    [Approval and safety](approval.md)
+
+-   :material-cog-outline:{ .lg .middle } **How it works**
+
+    ---
+
+    The component map and the pieces behind it: the persistent Julia
+    kernel, the filesystem, memory, context, and the trace.
+
+    [:octicons-arrow-right-24: Architecture](architecture.md) ·
+    [Turns](turns.md) ·
+    [Kernel](julia-kernel.md) ·
+    [Filesystem](filesystem.md) ·
+    [Memory](memory.md) ·
+    [Context](context.md) ·
+    [Trace](trace.md)
+
+-   :material-puzzle-plus:{ .lg .middle } **Extending the agent**
+
+    ---
+
+    Add a simulator as data, improve behavior with the right lever, and
+    prove every change against the benchmark.
+
+    [:octicons-arrow-right-24: Adding a simulator](adding-a-simulator.md) ·
+    [Improving the agent](improving-the-agent.md) ·
+    [Evaluation](evaluation.md)
+
+-   :material-flask-outline:{ .lg .middle } **Development**
+
+    ---
+
+    Repo layout, the test tiers and what CI runs, dependency policy, and
+    the agent-first working method behind it all.
+
+    [:octicons-arrow-right-24: Development](development.md) ·
+    [Testing](testing.md) ·
+    [Agent-first](agent-first.md)
+
+</div>
+
+## Supported simulators
+
+<p class="ja-logos">
+  <a href="https://github.com/sintefmath/JutulDarcy.jl"><img src="https://raw.githubusercontent.com/sintefmath/JutulDarcy.jl/main/docs/src/assets/logo_wide.png" alt="JutulDarcy" style="height:1.6rem"></a>
+  <a href="https://github.com/BattMoTeam/BattMo.jl"><img src="https://raw.githubusercontent.com/BattMoTeam/BattMo.jl/main/docs/src/assets/battmologo_text.png" alt="BattMo" style="height:2.8rem"></a>
+  <a href="https://github.com/sintefmath/Fimbul.jl"><img src="https://raw.githubusercontent.com/sintefmath/Fimbul.jl/main/docs/src/assets/logo_text_wide.png" alt="Fimbul" style="height:1.9rem"></a>
+  <a href="https://github.com/sintefmath/Mocca.jl"><img src="https://raw.githubusercontent.com/sintefmath/Mocca.jl/main/docs/src/assets/mocca_small_transparent.png" alt="Mocca" style="height:2.4rem"></a>
+</p>
+
+| Simulator | Package | Domain |
+|---|---|---|
+| `jutuldarcy` | [JutulDarcy.jl](https://github.com/sintefmath/JutulDarcy.jl) | Reservoir / multi-phase flow |
+| `battmo` | [BattMo.jl](https://github.com/BattMoTeam/BattMo.jl) | Lithium-ion (and other) battery cells |
+| `fimbul` | [Fimbul.jl](https://github.com/sintefmath/Fimbul.jl) | Geothermal (ATES, BTES, doublet, EGS) |
+| `mocca` | [Mocca.jl](https://github.com/sintefmath/Mocca.jl) | Adsorption-based CO₂ capture |