Metadata-Version: 2.4
Name: matrouter
Version: 0.3.3
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 operations and uses
deterministic Python operators to decide whether returned evidence is admissible
for a `ClaimSpec`.

The Agent control plane (LLM + MCP + Skill) plans and writes. The Python evidence
plane owns capability truth, execution outcomes, provenance, scientific gates,
and `ClaimSupportMap`. MatRouter therefore keeps **availability → execution →
admissibility** separate: retrievable data or a successful API call is not by
itself support for a scientific claim.

## 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.explain_sources())
```

`EvidenceBundle` is the sole evidence truth. Deterministic qualification returns
exactly four scientific dispositions: `supported`, `conflicted`,
`incomparable`, and `incomplete`. An Agent may revise its plan but may not
upgrade a MatRouter disposition.

## 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 scientific context,
or impose a fixed end-to-end research workflow. OPTIMADE remains complementary:
OPTIMADE standardizes provider-side common records; MatRouter supplies
agent-side evidence routing and task-relative scientific admissibility across
native and OPTIMADE sources.

## 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.
