mceg 0.1.1__tar.gz

mceg-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hajime Kawahara
+
+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.

mceg-0.1.1/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: mceg
+Version: 0.1.1
+Summary: Experimental scientific model contracts and evidence links
+Author: Hajime Kawahara
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/HajimeKawahara/mceg
+Project-URL: Documentation, https://github.com/HajimeKawahara/mceg/blob/main/README.md
+Project-URL: Issues, https://github.com/HajimeKawahara/mceg/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: PyYAML<7,>=6
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx<10,>=7; extra == "docs"
+Requires-Dist: myst-parser<6,>=4; extra == "docs"
+Dynamic: license-file
+
+# MCEG: Model Contracts and Evidence Graphs
+
+**Model Contracts and Evidence Graphs (MCEG)** is a framework for making the claims, assumptions, applicability domains, and supporting evidence of computational scientific models explicit, traceable, and auditable by both humans and AI systems.
+
+By systematically representing what a scientific model claims, under which conditions those claims hold, and what evidence supports them, MCEG facilitates scientifically informed decisions throughout model development, validation, and use.
+
+Rather than automatically guaranteeing the correctness of scientific models, MCEG provides a transparent foundation for humans and AI systems to continuously examine their scientific validity, limitations, and supporting evidence.
+
+Human and LLM reviewers also use these records to resume investigations, compare
+sources and justify model changes. The [investigation design](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/design_questions.md#investigations-by-human-and-llm-reviewers)
+describes this workflow and the proposed next improvements.
+
+Two design commitments guide that workflow: an LLM without the previous
+conversation must be able to follow the evidence and resume an investigation;
+humans must also be able to inspect the evidence and model contracts themselves.
+[MCEG Viewer](https://github.com/HajimeKawahara/mceg/blob/main/viewer/README.md) provides a small bilingual interface for that
+inspection. It consumes exported Graph JSON; MCEG itself does not depend on it.
+
+## Start with the package you use
+
+After [installing MCEG](#install), start by inspecting your scientific package:
+
+```bash
+mceg explain --package exogibbs
+```
+
+This shows all models and evidence records indexed by the installed package,
+including documented differences, limitations and open questions. You do not
+need to know a model ID or suspect a particular molecule first.
+
+Once you find a topic to investigate, narrow the report:
+
+```bash
+mceg explain --package exogibbs --species HCN
+```
+
+From a provider checkout, gather a selected record's related sources, completed
+reviews and remaining tasks in one report:
+
+```bash
+mceg explain mceg/contracts/model.yaml --evidence source_review --investigation --json
+```
+
+Use the contract path and Evidence ID reported by your provider. See the
+[investigation guide](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/checks.md#resume-an-investigation) for selection
+boundaries and the distinction between completed work and scientific support.
+
+The package commands above work from any directory and require a provider version that
+includes an evidence catalog. For editable installations or explicit catalog
+files, see [packaged evidence catalogs](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/package_evidence.md).
+The report describes recorded evidence, not an evaluation of your calculation's
+conditions. ExoGibbs itself works without MCEG installed.
+
+If your package has no MCEG records yet, start with
+[LLM or manual setup](#add-mceg-to-an-existing-package).
+
+## Main commands
+
+The package command above reads an installed distribution. Run the repository
+commands below from a provider checkout after installing MCEG.
+
+| Task | Command |
+| --- | --- |
+| Start a model contract and inventory entry | `mceg init MODEL_ID --source PATH --symbol NAME` |
+| Check discovered contracts and saved evidence | `mceg check` |
+| Explain gaps and the next review steps | `mceg explain` |
+| Discover an installed provider's model evidence | `mceg explain --package exogibbs` |
+| Resume a recorded investigation | `mceg explain CONTRACT --evidence EVIDENCE_ID --investigation --json` |
+| Find inventory, contract and source-review gaps | `mceg coverage .` |
+| Generate RST for repository documentation | `mceg docs --config mceg/docs.yaml` |
+| Export an installed provider's graph | `mceg graph --package exogibbs` |
+| Export one contract's graph | `mceg graph CONTRACT` |
+| Export a calculation's graph | `mceg graph --case CASE` |
+| Validate one contract's structure | `mceg path/to/contract.yaml` |
+| Compare recorded conditions with a context | `mceg assess CONTRACT --context CONTEXT --subject ID --output NEW_FILE` |
+| Preserve a v0.1 contract in v0.2 format | `mceg migrate CONTRACT --output NEW_FILE` |
+| Trace an evidence record's sources | `mceg --trace EVIDENCE_ID CONTRACT` |
+
+Use `mceg COMMAND -h` for options. `check`, `explain` and `coverage` offer JSON
+reports; `check` and `explain` also accept `--lang ja`.
+The [Graph JSON API](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/graph.md) exports contracts, scoped judgments,
+investigation records and calculation connections for viewers and other tools.
+
+[Packaged evidence catalogs](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/package_evidence.md) let users inspect a
+provider's model/species records without cloning its repository or importing its
+code. The provider supplies the catalog as data and need not depend on MCEG.
+This reports recorded evidence; it does not evaluate a user's run conditions.
+
+## Install
+
+Install from PyPI using Python 3.10+:
+
+```bash
+python -m pip install mceg
+```
+
+For development from this checkout:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+Runtime dependencies are Pydantic 2 and PyYAML 6. The `mceg` command is equivalent
+to `python -m mceg`.
+
+## Add MCEG to an existing package
+
+Work in the scientific package's source checkout (the **provider**), with the
+[MCEG environment](#install) active. Keep MCEG as an optional authoring tool,
+outside the provider's runtime dependencies. Start with one model.
+
+### With an LLM
+
+Give a coding assistant access to both checkouts and replace the placeholders:
+
+```text
+Add MCEG to <provider checkout>, starting with <model or module>.
+Follow <MCEG checkout>/docs/en/initialization.md and provider_onboarding.md
+in the same directory. Inspect code, data, docs and tests to identify model
+boundaries and choices, then use mceg init to create a v0.2 draft and inventory.
+Document model conventions and evidence from inspected sources; record only
+tests actually run. Keep missing support unknown and list concrete follow-ups.
+Expand source_roots to the intended package scope and keep review_pending true
+until human review. Preserve numerical behavior and keep MCEG optional.
+Run mceg check, mceg explain and mceg coverage . from the provider root.
+Summarize changed files, checks, remaining gaps and required human review.
+```
+
+### Manually
+
+Choose the model boundary and its local Python definition after reading the code,
+data, docs and tests. Replace the example names and choices with your own:
+
+```bash
+cd /path/to/provider
+mceg init mypkg.water.power_law \
+  --source src/mypkg/water.py --symbol gibbs_j \
+  --setting water_model=power_law
+```
+
+`init` creates a v0.2 draft under `mceg/contracts/` and adds its code/contract
+mapping to `mceg/models.yaml`. Edit the draft's `TODO` fields to describe units,
+assumptions, model choices and inspected evidence. Run relevant provider tests
+separately and retain their results before recording numerical support; leave
+missing scientific support `unknown` with follow-ups.
+
+The initial inventory scans the selected file only. Expand `source_roots` to
+cover the intended package, classify and hash reviewed files, and clear
+`review_pending` only after human review of model boundaries and links. Then run:
+
+```bash
+mceg check mceg/contracts/mypkg.water.power_law.yaml
+mceg explain mceg/contracts/mypkg.water.power_law.yaml --evidence implementation
+mceg coverage .
+```
+
+`coverage` returns **1** while review or registration gaps remain. Structural
+validation does not establish scientific support. Save the records and link them
+from the provider's docs. See the [setup guide](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/initialization.md) for both
+workflows and the [provider workflow](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/provider_onboarding.md) for evidence
+review. Installed-package discovery additionally needs a
+[packaged catalog](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/package_evidence.md).
+
+## Inspect existing contracts
+
+`check` and `explain` discover YAML contracts under `mceg/contracts/` or
+`contracts/`. Filter by name or give an explicit path:
+
+```bash
+mceg check -k water
+mceg explain -k water --lang ja
+mceg check mceg/contracts/water.yaml --json
+```
+
+A **PASS** applies to the named check and its scope. **UNKNOWN** identifies missing
+support or an unresolved review. Numerical agreement, registered model mappings
+and physical accuracy are separate questions. A stored result is not a fresh
+solver run. For a recorded v0.2 Assessment, `--assessment ID --root .` also checks
+its selected source and artifact hashes; see the [check guide](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/checks.md).
+
+## Export relationship graphs
+
+From this MCEG checkout, export a model's evidence and judgments or a calculation's
+component connections:
+
+```bash
+mceg graph examples/v02/h2_solubility.yaml --provider mceg > model-graph.json
+mceg graph --case examples/html/case.yaml --provider mceg > case-graph.json
+```
+
+For an installed provider with an evidence catalog:
+
+```bash
+mceg graph --package exogibbs > package-graph.json
+```
+
+To select the catalog directly from an ExoGibbs checkout:
+
+```bash
+mceg graph --catalog /path/to/exogibbs/src/exogibbs/data/mceg/index.json > package-graph.json
+```
+
+To run MCEG directly from its checkout, prepend its `src` directory to
+`PYTHONPATH`, keeping any existing entries:
+
+```bash
+PYTHONPATH="/path/to/mceg/src${PYTHONPATH:+:$PYTHONPATH}" \
+  python -m mceg graph --package exogibbs > package-graph.json
+```
+
+Package lookup also handles source-manifest paths in legacy `src`-layout editable
+installs. Use `mceg graph --catalog PATH` for an explicit catalog or editable
+installs whose metadata does not list the catalog. Local contract and case paths
+resolve from `--root`, which defaults to the current directory. JSON retains
+source identities, scoped judgments and explicit selections for viewers and LLM tools. See the
+[Graph JSON API](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/graph.md) for Python examples and relationship meanings.
+
+## Documentation and examples
+
+For interactive inspection, run the standalone viewer (Node.js 22.12+):
+
+```bash
+cd viewer
+npm ci
+npm run dev
+```
+
+Open the printed local URL, choose **Open graph JSON**, and select an export
+from `mceg graph`. The bundled H2 example can also be opened from the welcome
+screen. Switch between English and Japanese in the header. See the
+[viewer guide](https://github.com/HajimeKawahara/mceg/blob/main/viewer/README.md) for navigation and interpretation boundaries.
+
+To publish the viewer on a static web server, run this from the same `viewer/`
+directory:
+
+```bash
+npm run build
+```
+
+Upload **all contents of `viewer/dist/`** (`index.html`, `assets/`,
+`viewer-export.json` and `example-graph.json`) to the server's public directory.
+PHP, Node.js, Python and MCEG are not required on the server. Visitors open their graph JSON in the
+browser; the build does not bundle a graph previously opened in the viewer.
+See [static hosting instructions](https://github.com/HajimeKawahara/mceg/blob/main/viewer/README.md#static-hosting) for deployment
+and local preview.
+
+To publish a specific graph, open it in the viewer and click **Save as HTML**.
+Upload the downloaded file to the server; it includes the complete graph and
+interactive viewer, so visitors do not need to select a JSON file. See the
+[HTML export guide](https://github.com/HajimeKawahara/mceg/blob/main/viewer/README.md#save-a-graph-as-a-standalone-html-page).
+
+For a browsable model catalog and linked calculation/evidence graphs, see the
+[HTML guide](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/html.md). Build it with Graphviz installed:
+
+```bash
+python -m pip install -e '.[docs]'
+./update_doc.sh -W --keep-going
+```
+
+Open `docs/_build/html/index.html` and select **Calculation cases** for the H2
+connection. The build reads saved records; it runs no scientific calculation.
+Run `mceg docs --config mceg/docs.yaml` to generate RST and CSS for a provider.
+Each repository builds HTML with its own Sphinx configuration and update script.
+
+| Topic | Guides |
+| --- | --- |
+| Model registration | [LLM and manual setup](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/initialization.md), [inventory coverage](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/coverage.md), [provider workflow](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/provider_onboarding.md) |
+| Checks and source review | [CLI checks](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/checks.md), [provenance](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/provenance.md), [evidence audit](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/evidence_audit.md) |
+| Relationship graphs | [Graph JSON API](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/graph.md), [HTML documentation](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/html.md) |
+| Contract formats | [v0.2](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/v02.md), [v0.1](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/schema.md), [compatibility](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/versioning.md) |
+| Worked connections | [H2 solubility](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/h2_solubility.md), [provider trials](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/provider_trials.md), [provider-owned pilot](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/provider_pilot.md) |
+| Evidence studies | [H2 sources](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/h2_primary_audit.md), [curated gas](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/curated_assessment.md), [assessment lifecycle](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/assessment_lifecycle.md) |
+| Design questions | [English](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/design_questions.md), [Japanese](https://github.com/HajimeKawahara/mceg/blob/main/docs/ja/design_questions.md) |
+
+Browse [example contracts](https://github.com/HajimeKawahara/mceg/tree/main/contracts) and [saved examples](https://github.com/HajimeKawahara/mceg/tree/main/examples).
+The current package release is **`0.1.1`**. It reads both v0.1 and v0.2 contracts;
+package versions and schema versions are separate. The frozen `v0.1.0` baseline
+remains unchanged, and the v0.2 schema remains experimental.
+See the [changelog](https://github.com/HajimeKawahara/mceg/blob/main/CHANGELOG.md) for changes and the
+[release guide](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/releasing.md) for publishing instructions.
+
+## Development
+
+```bash
+python -m pip install -e '.[test]'
+python -m pytest
+```

mceg-0.1.1/README.md

@@ -0,0 +1,289 @@
+# MCEG: Model Contracts and Evidence Graphs
+
+**Model Contracts and Evidence Graphs (MCEG)** is a framework for making the claims, assumptions, applicability domains, and supporting evidence of computational scientific models explicit, traceable, and auditable by both humans and AI systems.
+
+By systematically representing what a scientific model claims, under which conditions those claims hold, and what evidence supports them, MCEG facilitates scientifically informed decisions throughout model development, validation, and use.
+
+Rather than automatically guaranteeing the correctness of scientific models, MCEG provides a transparent foundation for humans and AI systems to continuously examine their scientific validity, limitations, and supporting evidence.
+
+Human and LLM reviewers also use these records to resume investigations, compare
+sources and justify model changes. The [investigation design](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/design_questions.md#investigations-by-human-and-llm-reviewers)
+describes this workflow and the proposed next improvements.
+
+Two design commitments guide that workflow: an LLM without the previous
+conversation must be able to follow the evidence and resume an investigation;
+humans must also be able to inspect the evidence and model contracts themselves.
+[MCEG Viewer](https://github.com/HajimeKawahara/mceg/blob/main/viewer/README.md) provides a small bilingual interface for that
+inspection. It consumes exported Graph JSON; MCEG itself does not depend on it.
+
+## Start with the package you use
+
+After [installing MCEG](#install), start by inspecting your scientific package:
+
+```bash
+mceg explain --package exogibbs
+```
+
+This shows all models and evidence records indexed by the installed package,
+including documented differences, limitations and open questions. You do not
+need to know a model ID or suspect a particular molecule first.
+
+Once you find a topic to investigate, narrow the report:
+
+```bash
+mceg explain --package exogibbs --species HCN
+```
+
+From a provider checkout, gather a selected record's related sources, completed
+reviews and remaining tasks in one report:
+
+```bash
+mceg explain mceg/contracts/model.yaml --evidence source_review --investigation --json
+```
+
+Use the contract path and Evidence ID reported by your provider. See the
+[investigation guide](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/checks.md#resume-an-investigation) for selection
+boundaries and the distinction between completed work and scientific support.
+
+The package commands above work from any directory and require a provider version that
+includes an evidence catalog. For editable installations or explicit catalog
+files, see [packaged evidence catalogs](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/package_evidence.md).
+The report describes recorded evidence, not an evaluation of your calculation's
+conditions. ExoGibbs itself works without MCEG installed.
+
+If your package has no MCEG records yet, start with
+[LLM or manual setup](#add-mceg-to-an-existing-package).
+
+## Main commands
+
+The package command above reads an installed distribution. Run the repository
+commands below from a provider checkout after installing MCEG.
+
+| Task | Command |
+| --- | --- |
+| Start a model contract and inventory entry | `mceg init MODEL_ID --source PATH --symbol NAME` |
+| Check discovered contracts and saved evidence | `mceg check` |
+| Explain gaps and the next review steps | `mceg explain` |
+| Discover an installed provider's model evidence | `mceg explain --package exogibbs` |
+| Resume a recorded investigation | `mceg explain CONTRACT --evidence EVIDENCE_ID --investigation --json` |
+| Find inventory, contract and source-review gaps | `mceg coverage .` |
+| Generate RST for repository documentation | `mceg docs --config mceg/docs.yaml` |
+| Export an installed provider's graph | `mceg graph --package exogibbs` |
+| Export one contract's graph | `mceg graph CONTRACT` |
+| Export a calculation's graph | `mceg graph --case CASE` |
+| Validate one contract's structure | `mceg path/to/contract.yaml` |
+| Compare recorded conditions with a context | `mceg assess CONTRACT --context CONTEXT --subject ID --output NEW_FILE` |
+| Preserve a v0.1 contract in v0.2 format | `mceg migrate CONTRACT --output NEW_FILE` |
+| Trace an evidence record's sources | `mceg --trace EVIDENCE_ID CONTRACT` |
+
+Use `mceg COMMAND -h` for options. `check`, `explain` and `coverage` offer JSON
+reports; `check` and `explain` also accept `--lang ja`.
+The [Graph JSON API](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/graph.md) exports contracts, scoped judgments,
+investigation records and calculation connections for viewers and other tools.
+
+[Packaged evidence catalogs](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/package_evidence.md) let users inspect a
+provider's model/species records without cloning its repository or importing its
+code. The provider supplies the catalog as data and need not depend on MCEG.
+This reports recorded evidence; it does not evaluate a user's run conditions.
+
+## Install
+
+Install from PyPI using Python 3.10+:
+
+```bash
+python -m pip install mceg
+```
+
+For development from this checkout:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+Runtime dependencies are Pydantic 2 and PyYAML 6. The `mceg` command is equivalent
+to `python -m mceg`.
+
+## Add MCEG to an existing package
+
+Work in the scientific package's source checkout (the **provider**), with the
+[MCEG environment](#install) active. Keep MCEG as an optional authoring tool,
+outside the provider's runtime dependencies. Start with one model.
+
+### With an LLM
+
+Give a coding assistant access to both checkouts and replace the placeholders:
+
+```text
+Add MCEG to <provider checkout>, starting with <model or module>.
+Follow <MCEG checkout>/docs/en/initialization.md and provider_onboarding.md
+in the same directory. Inspect code, data, docs and tests to identify model
+boundaries and choices, then use mceg init to create a v0.2 draft and inventory.
+Document model conventions and evidence from inspected sources; record only
+tests actually run. Keep missing support unknown and list concrete follow-ups.
+Expand source_roots to the intended package scope and keep review_pending true
+until human review. Preserve numerical behavior and keep MCEG optional.
+Run mceg check, mceg explain and mceg coverage . from the provider root.
+Summarize changed files, checks, remaining gaps and required human review.
+```
+
+### Manually
+
+Choose the model boundary and its local Python definition after reading the code,
+data, docs and tests. Replace the example names and choices with your own:
+
+```bash
+cd /path/to/provider
+mceg init mypkg.water.power_law \
+  --source src/mypkg/water.py --symbol gibbs_j \
+  --setting water_model=power_law
+```
+
+`init` creates a v0.2 draft under `mceg/contracts/` and adds its code/contract
+mapping to `mceg/models.yaml`. Edit the draft's `TODO` fields to describe units,
+assumptions, model choices and inspected evidence. Run relevant provider tests
+separately and retain their results before recording numerical support; leave
+missing scientific support `unknown` with follow-ups.
+
+The initial inventory scans the selected file only. Expand `source_roots` to
+cover the intended package, classify and hash reviewed files, and clear
+`review_pending` only after human review of model boundaries and links. Then run:
+
+```bash
+mceg check mceg/contracts/mypkg.water.power_law.yaml
+mceg explain mceg/contracts/mypkg.water.power_law.yaml --evidence implementation
+mceg coverage .
+```
+
+`coverage` returns **1** while review or registration gaps remain. Structural
+validation does not establish scientific support. Save the records and link them
+from the provider's docs. See the [setup guide](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/initialization.md) for both
+workflows and the [provider workflow](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/provider_onboarding.md) for evidence
+review. Installed-package discovery additionally needs a
+[packaged catalog](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/package_evidence.md).
+
+## Inspect existing contracts
+
+`check` and `explain` discover YAML contracts under `mceg/contracts/` or
+`contracts/`. Filter by name or give an explicit path:
+
+```bash
+mceg check -k water
+mceg explain -k water --lang ja
+mceg check mceg/contracts/water.yaml --json
+```
+
+A **PASS** applies to the named check and its scope. **UNKNOWN** identifies missing
+support or an unresolved review. Numerical agreement, registered model mappings
+and physical accuracy are separate questions. A stored result is not a fresh
+solver run. For a recorded v0.2 Assessment, `--assessment ID --root .` also checks
+its selected source and artifact hashes; see the [check guide](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/checks.md).
+
+## Export relationship graphs
+
+From this MCEG checkout, export a model's evidence and judgments or a calculation's
+component connections:
+
+```bash
+mceg graph examples/v02/h2_solubility.yaml --provider mceg > model-graph.json
+mceg graph --case examples/html/case.yaml --provider mceg > case-graph.json
+```
+
+For an installed provider with an evidence catalog:
+
+```bash
+mceg graph --package exogibbs > package-graph.json
+```
+
+To select the catalog directly from an ExoGibbs checkout:
+
+```bash
+mceg graph --catalog /path/to/exogibbs/src/exogibbs/data/mceg/index.json > package-graph.json
+```
+
+To run MCEG directly from its checkout, prepend its `src` directory to
+`PYTHONPATH`, keeping any existing entries:
+
+```bash
+PYTHONPATH="/path/to/mceg/src${PYTHONPATH:+:$PYTHONPATH}" \
+  python -m mceg graph --package exogibbs > package-graph.json
+```
+
+Package lookup also handles source-manifest paths in legacy `src`-layout editable
+installs. Use `mceg graph --catalog PATH` for an explicit catalog or editable
+installs whose metadata does not list the catalog. Local contract and case paths
+resolve from `--root`, which defaults to the current directory. JSON retains
+source identities, scoped judgments and explicit selections for viewers and LLM tools. See the
+[Graph JSON API](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/graph.md) for Python examples and relationship meanings.
+
+## Documentation and examples
+
+For interactive inspection, run the standalone viewer (Node.js 22.12+):
+
+```bash
+cd viewer
+npm ci
+npm run dev
+```
+
+Open the printed local URL, choose **Open graph JSON**, and select an export
+from `mceg graph`. The bundled H2 example can also be opened from the welcome
+screen. Switch between English and Japanese in the header. See the
+[viewer guide](https://github.com/HajimeKawahara/mceg/blob/main/viewer/README.md) for navigation and interpretation boundaries.
+
+To publish the viewer on a static web server, run this from the same `viewer/`
+directory:
+
+```bash
+npm run build
+```
+
+Upload **all contents of `viewer/dist/`** (`index.html`, `assets/`,
+`viewer-export.json` and `example-graph.json`) to the server's public directory.
+PHP, Node.js, Python and MCEG are not required on the server. Visitors open their graph JSON in the
+browser; the build does not bundle a graph previously opened in the viewer.
+See [static hosting instructions](https://github.com/HajimeKawahara/mceg/blob/main/viewer/README.md#static-hosting) for deployment
+and local preview.
+
+To publish a specific graph, open it in the viewer and click **Save as HTML**.
+Upload the downloaded file to the server; it includes the complete graph and
+interactive viewer, so visitors do not need to select a JSON file. See the
+[HTML export guide](https://github.com/HajimeKawahara/mceg/blob/main/viewer/README.md#save-a-graph-as-a-standalone-html-page).
+
+For a browsable model catalog and linked calculation/evidence graphs, see the
+[HTML guide](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/html.md). Build it with Graphviz installed:
+
+```bash
+python -m pip install -e '.[docs]'
+./update_doc.sh -W --keep-going
+```
+
+Open `docs/_build/html/index.html` and select **Calculation cases** for the H2
+connection. The build reads saved records; it runs no scientific calculation.
+Run `mceg docs --config mceg/docs.yaml` to generate RST and CSS for a provider.
+Each repository builds HTML with its own Sphinx configuration and update script.
+
+| Topic | Guides |
+| --- | --- |
+| Model registration | [LLM and manual setup](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/initialization.md), [inventory coverage](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/coverage.md), [provider workflow](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/provider_onboarding.md) |
+| Checks and source review | [CLI checks](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/checks.md), [provenance](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/provenance.md), [evidence audit](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/evidence_audit.md) |
+| Relationship graphs | [Graph JSON API](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/graph.md), [HTML documentation](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/html.md) |
+| Contract formats | [v0.2](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/v02.md), [v0.1](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/schema.md), [compatibility](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/versioning.md) |
+| Worked connections | [H2 solubility](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/h2_solubility.md), [provider trials](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/provider_trials.md), [provider-owned pilot](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/provider_pilot.md) |
+| Evidence studies | [H2 sources](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/h2_primary_audit.md), [curated gas](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/curated_assessment.md), [assessment lifecycle](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/assessment_lifecycle.md) |
+| Design questions | [English](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/design_questions.md), [Japanese](https://github.com/HajimeKawahara/mceg/blob/main/docs/ja/design_questions.md) |
+
+Browse [example contracts](https://github.com/HajimeKawahara/mceg/tree/main/contracts) and [saved examples](https://github.com/HajimeKawahara/mceg/tree/main/examples).
+The current package release is **`0.1.1`**. It reads both v0.1 and v0.2 contracts;
+package versions and schema versions are separate. The frozen `v0.1.0` baseline
+remains unchanged, and the v0.2 schema remains experimental.
+See the [changelog](https://github.com/HajimeKawahara/mceg/blob/main/CHANGELOG.md) for changes and the
+[release guide](https://github.com/HajimeKawahara/mceg/blob/main/docs/en/releasing.md) for publishing instructions.
+
+## Development
+
+```bash
+python -m pip install -e '.[test]'
+python -m pytest
+```

mceg-0.1.1/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mceg"
+version = "0.1.1"
+description = "Experimental scientific model contracts and evidence links"
+authors = [{name = "Hajime Kawahara"}]
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["pydantic>=2,<3", "PyYAML>=6,<7"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/HajimeKawahara/mceg"
+Documentation = "https://github.com/HajimeKawahara/mceg/blob/main/README.md"
+Issues = "https://github.com/HajimeKawahara/mceg/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+docs = ["sphinx>=7,<10", "myst-parser>=4,<6"]
+
+[project.scripts]
+mceg = "mceg.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mceg = ["data/curated_gas/*.json", "_static/*.css"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]