Metadata-Version: 2.4
Name: matrouter
Version: 0.3.2
Summary: Local-first Python package for task-relative materials evidence routing with MCP integration.
Project-URL: Homepage, https://github.com/MatRouter/matrouter
Project-URL: Repository, https://github.com/MatRouter/matrouter
Project-URL: Issues, https://github.com/MatRouter/matrouter/issues
Author-email: Quansheng Wu <quansheng.wu@iphy.ac.cn>, Tiannian Zhu <tnzhu@iphy.ac.cn>
Maintainer-email: Quansheng Wu <quansheng.wu@iphy.ac.cn>, Quansheng Wu <wuquansheng@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: aflow,agent,c2db,materials-project,materials-science,mcp,mpds,optimade
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: fastmcp==4.0.0a2
Requires-Dist: httpx2<3,>=2.9.1
Requires-Dist: materialsgalaxy-api<0.2,>=0.1.2
Requires-Dist: matplotlib<4,>=3.11.0
Requires-Dist: mp-api<0.47,>=0.46.4
Requires-Dist: pydantic-settings<3,>=2.14.2
Requires-Dist: pydantic<3,>=2.13.4
Requires-Dist: pymatgen-core==2026.5.18
Requires-Dist: pymatgen==2026.5.4
Requires-Dist: spglib==2.7.0
Description-Content-Type: text/markdown

# MatRouter

<p align="center">
  <img src="https://raw.githubusercontent.com/MatRouter/matrouter/main/logo.png" alt="MatRouter logo" width="220">
</p>

[English](https://github.com/MatRouter/matrouter/blob/main/README.md) | [简体中文](https://github.com/MatRouter/matrouter/blob/main/README.zh-CN.md)

MatRouter is an **agent-native materials evidence substrate**. It routes explicit
`EvidenceRequirement` objects to source-qualified executable operations and
deterministically decides whether returned evidence is admissible for a
`ClaimSpec`. It does not treat retrievable data, a ready route, or a successful
source call as support for a scientific claim.

The Agent control plane—LLM, Skills, and MCP tool use—interprets natural
language, decomposes evidence needs, chooses source breadth and order, retries,
iterates, stops, and writes the narrative. The Python evidence plane owns typed
requests, capability truth, route readiness, qualified source identity,
`SourceOutcome`, canonical observations and provenance, scientific
qualification, trace, lineage, artifact integrity, and `ClaimSupportMap`.
Agents may change a plan; they may not upgrade an `incomplete`,
`incomparable`, or `conflicted` MatRouter disposition to `supported`.

MatRouter's scientific model separates **availability → execution →
admissibility**. FastMCP is one transport for the Python core, and the Agent
Skill is a control-plane recipe.

## Status

This checkout is the direct-v2 cutover. The public architecture is the
two-plane surface described above; old workflow schemas and end-to-end task
tools are migration inputs, not supported fallback APIs. A v2 contract or MCP
tool is public only when its typed module and contract tests are present.
Schemas remain versioned and may change before a stable release.
Stateful MCP composition starts with `begin_evidence_run`; its returned
process-local ID isolates the attempt ledger, and a later attempt invalidates
older bundles for the same requirements. Each stateful call holds a run-wide
lease, so an active run cannot be replaced mid-operation. Executed malformed
payloads remain failed `SourceOutcome` attempts and never become evidence.

## Quick Start

MatRouter requires Python 3.11 or newer.

Add MatRouter to a Python project:

```bash
uv add --prerelease=allow matrouter
```

Use the package directly:

```python
from matrouter import create_router

with create_router() as router:
    print(router.explain_sources())
```

Create a claim specification, collect the explicitly declared evidence
requirements through the Agent control plane, and let deterministic Python
qualification produce the claim-support map:

```python
from matrouter.claim_support import make_claim_support_request, qualify_claim_support

request = make_claim_support_request(bundle, (claim_spec,))
support_map = qualify_claim_support(request)
print(support_map.entries[0].disposition)
```

The four finite templates are retained as versioned Python policy packs, Skill
recipes, and benchmark specifications. They deterministically expand into
mandatory `EvidenceRequirement` objects; they do not choose a complete source
sequence or report preset. `EvidenceBundle` is the sole evidence truth, and
`ClaimSupportMap` exposes only the four scientific dispositions
`supported`, `conflicted`, `incomparable`, and `incomplete`. Availability
statuses such as `unsupported` remain outside that scientific algebra.

OPTIMADE and MatRouter are complementary: OPTIMADE standardizes provider-side
common-record interoperability, while MatRouter provides agent-side evidence
capability routing and scientific admissibility across native and OPTIMADE
sources. Aggregate providers are discovery scopes; executable evidence routes
retain the exact provider/database child identity. MatRouter does not replace
OPTIMADE.

Install the same package as an MCP runtime:

```bash
uv tool install --prerelease=allow matrouter
```

Or install from a source checkout:

```bash
git clone https://github.com/MatRouter/matrouter.git
cd matrouter
uv sync
```

Agent hosts can then run MatRouter as a local MCP stdio server:

```bash
matrouter
```

When running from a source checkout instead of the installed tool, use `uv run matrouter`.

For Codex and Claude Code, prefer the installable plugin path in the [user guide](https://github.com/MatRouter/matrouter/blob/main/docs/usage.md). For OpenCode or other hosts, configure MCP with `command: "matrouter"` or `command: ["matrouter"]` and install the portable skill if the host supports skills.

Most starter workflows can use public sources without MatRouter-specific credentials. Materials Project, MaterialsGalaxy structure/property routes, and MPDS require API keys supplied through the process environment or the agent host's secret storage. Do not commit keys to the repository or shared MCP client configuration.

## Documentation

- User setup, data-source configuration, MCP client examples, workflows, and troubleshooting: [user guide](https://github.com/MatRouter/matrouter/blob/main/docs/usage.md)
- Development guide, architecture notes, configuration contract, testing, and release workflow: [development guide](https://github.com/MatRouter/matrouter/blob/main/docs/development.md)
- Validation report: [test report](https://github.com/MatRouter/matrouter/blob/main/docs/test-report.md)

## Agent Skill

The public MatRouter skill source lives in [`skills/matrouter/`](https://github.com/MatRouter/matrouter/tree/main/skills/matrouter). It is for agents that have, or are being configured to have, MatRouter MCP access. It is the non-normative control-plane recipe for creating claim specifications, decomposing evidence needs, choosing routes, handling retries and gaps, and narrating deterministic MatRouter qualification without changing its disposition.

For Codex auto-discovery, install it by copying `skills/matrouter/` to `.agents/skills/matrouter/` in a repo or to `$HOME/.agents/skills/matrouter/` for personal use.

For human-facing MCP client setup, use the user guide. After setup, a useful prompt is:

```text
Use MatRouter to find the band structure of diamond and generate a plot.
```

## Contact

Authors:

- Quansheng Wu <quansheng.wu@iphy.ac.cn>
- Tiannian Zhu (朱天念) <tnzhu@iphy.ac.cn>

Maintainer:

- Quansheng Wu <wuquansheng@gmail.com>

## License

MatRouter source code is licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/MatRouter/matrouter/blob/main/LICENSE) and [NOTICE](https://github.com/MatRouter/matrouter/blob/main/NOTICE).

MatRouter does not grant rights to third-party database content. Data retrieved through MatRouter remains subject to the terms, licenses, API policies, attribution requirements, and access restrictions of the respective upstream data providers.
