Metadata-Version: 2.5
Name: matrouter
Version: 0.10.2
Summary: Agent-native routing and provenance-preserving aggregation substrate for materials data.
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.0b1
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
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 routing and aggregation substrate for materials
data**. It turns an explicit data need into executable routes across heterogeneous
sources, then assembles returned records, structures, properties, artifacts,
provenance, and execution outcomes into one `EvidenceBundle`.

The Agent (LLM + MCP + Skill) chooses source and record scope and owns planning,
retries, scientific interpretation, and prose. MatRouter owns capability truth, source-qualified
execution, normalization, provenance, and bundle integrity. It preserves the
context needed for downstream reasoning without turning retrieval into a
scientific verdict.

## Install

MatRouter requires Python 3.11 or newer.

```bash
# Python dependency
uv add --prerelease=allow matrouter

# Standalone MCP command
uv tool install --prerelease=allow matrouter
```

From a checkout:

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

## Python

```python
from matrouter import create_router

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

`EvidenceBundle` is the core output and the sole record of what was requested,
attempted, returned, or missing. The single MCP surface also exposes explicit
methods for exact-input structure matching, frame-safe phase-diagram
calculation/plotting, and rendering acquired band-structure or DOS artifacts.
Retrieval never renders implicitly. Method results retain their exact inputs,
parameters, provenance, and limitations; they are not general scientific
verdicts.

## Agent plugin

Codex and Claude Code can install the bundled plugin; other MCP hosts can run
`matrouter` as a local stdio server and use the portable Skill when supported.
See the [user guide](https://github.com/MatRouter/matrouter/blob/main/docs/usage.md)
for the current installation and configuration procedure.

The sole distributable Skill source is
[`plugins/matrouter/skills/matrouter/`](https://github.com/MatRouter/matrouter/tree/main/plugins/matrouter/skills/matrouter).

## Scope

MatRouter does not mirror upstream databases, infer missing values, impose a
fixed research workflow, embed scientific assessment rules, or decide scientific
truth. OPTIMADE remains
complementary: OPTIMADE standardizes provider-side common records; MatRouter
orchestrates native and OPTIMADE sources on the Agent side and preserves their
source-specific context in a common bundle.

## Documentation

- [User guide](https://github.com/MatRouter/matrouter/blob/main/docs/usage.md): installation, configuration, MCP, sources, and usage.
- [Development guide](https://github.com/MatRouter/matrouter/blob/main/docs/development.md): architecture, contracts, and maintenance.
- [Verification report](https://github.com/MatRouter/matrouter/blob/main/docs/test-report.md): current tested surface and limits.
- [Plugin guide](https://github.com/MatRouter/matrouter/blob/main/plugins/matrouter/README.md): agent-host installation.

## Contact

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

## License

MatRouter is licensed under Apache-2.0; see [LICENSE](https://github.com/MatRouter/matrouter/blob/main/LICENSE)
and [NOTICE](https://github.com/MatRouter/matrouter/blob/main/NOTICE). Retrieved
data remains subject to each upstream provider's terms, licenses, attribution
requirements, and access restrictions.
