Jacobian

Pure mathematics for agents: search for examples and counterexamples, compute exactly, and independently check what a result proves.

Jacobian is a collection of mathematical operations for AI agents. It runs as an MCP server and is also available as a CLI and Python library. Agents can use it to compute invariants, search for examples or counterexamples, work with solver artifacts, and check formal proofs.

Quickstart

For a one-time setup:

npx jacobian setup

For a guided user-local install:

curl -fsSL https://raw.githubusercontent.com/morluto/jacobian/main/npm/install.sh | sh

The installer resolves an npm release to an exact version, installs the small launcher without lifecycle scripts, configures selected MCP clients, and verifies the local server. The Python package environment is approximately 160 MB; if Python 3.12 is not already available, uv's managed Python adds about 110 MB. Add --defer-runtime to postpone both until first use:

curl -fsSL https://raw.githubusercontent.com/morluto/jacobian/main/npm/install.sh | \
  sh -s -- --client codex --yes --defer-runtime

For repeated use:

npm install -g jacobian
jacobian setup
jacobian upgrade
jacobian doctor

For the Python distribution:

python -m pip install jacobian

That package includes Jacobian's exact maintained Python backend stack: SymPy, NetworkX, Z3, Python-FLINT, and cvc5. A normal Python or npm installation therefore exposes the same built-in Python-backed operation portfolio. The tested binary-install contract is CPython 3.12 or 3.13 on glibc Linux x86-64; the release gate installs the built wheel and starts Jacobian on both Python versions. Other systems may have compatible upstream wheels, but are not part of the tested release contract yet. In particular, Alpine/musl cannot install the complete mandatory stack from PyPI.

The launcher supports Claude, Codex, Cursor, Gemini, and OpenCode. It requires Node.js 18 or newer plus CPython 3.12/3.13 or uv; the guided installer can install its pinned uv release after confirmation. Run jacobian mcp to start the server directly.

The Python distribution contains the mathematical kernel, CLI, and MCP server. The npm package is a sub-100 KB thin launcher and MCP client installer for that same implementation; it is not a separate JavaScript API. It bundles one TOML parser for fail-closed Codex configuration updates and runs no install-time scripts. The larger download is the local Python mathematical runtime, not a JavaScript dependency tree.

To run the exact code in a clone, follow Configure an agent from a source checkout.

Compute, then check when needed

An ordinary operation returns mathematics first. For example, matrix.determinant.compute accepts one exact rational matrix and returns its determinant inline. If independent replay matters, the agent may separately run matrix.determinant.verify with that exact input and candidate result.

The producer and checker are distinct catalog IDs with independent implementations. Computation does not certify itself, and a timeout, cancellation, error, or incomplete bounded search remains a non-conclusion.

The introductory tutorial runs this determinant pair through the public MCP surface.

Available mathematics

The installed operations vary with optional external providers, but the maintained portfolio covers work in:

• polynomial maps and polynomial algebra;
• exact linear algebra;
• graphs, paths, colorings, and isomorphism;
• SAT and SMT models and proof artifacts;
• finite and universal algebra;
• polytopes; and
• Lean declaration discovery and proof checking.

Some operations require optional native or formal backends. Catalog membership means an operation is installed and invocable; it does not grant verification authority. Read capability://catalog or use math.find to inspect the current environment. Use math.run to invoke a selected operation.

See the domain operation library for the maintained operation portfolio and native and formal provider setup for provider requirements.

Verification model

Jacobian separates mathematical production from independent checking. A producer cannot certify its own output.

Subject + Candidate → Independent checker → Bound record

Only an operator-authorized checker may emit a verified record, bound to the exact subject, candidate, evidence, protocol, scope, semantics, certificate format, and checker identity. Availability and provider provenance do not grant that authority.

No witness is not proof. A failed search, timeout, cancellation, error, or completed bounded search without a witness leaves the claim UNKNOWN.

The architecture document describes the complete trust boundary.

Status

Jacobian 0.11.0 is a pre-stable release. Its published package, capability, and artifact contracts describe the current supported surface; ongoing capability research may change experimental contracts between releases.

Documentation

• Documentation home — tutorials, how-to guides, reference, and explanations
• First verified result — a complete runnable example
• Architecture — runtime structure and trust boundaries
• Product model — capability contracts, ownership, and project boundaries
• Tool reference — MCP resources and invocation contracts
• Native and formal providers — provider and Lean setup
• Remote deployment — HTTP deployment and authentication

Contributing

Jacobian uses Python 3.12, uv, and a small Makefile:

make setup
make test-unit
make check

Read CONTRIBUTING.md before changing code. It documents focused test commands, verification rules, documentation placement, and pull-request expectations.

License

MIT