mattergraph-api 0.1.0__tar.gz

mattergraph_api-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+.coverage
+coverage.xml
+htmlcov/
+
+# Docs build output
+site/
+
+# Env
+.env
+.env.local
+*.local
+
+# Node
+node_modules/
+apps/web/dist/
+apps/web/playwright-report/
+apps/web/test-results/
+*.tsbuildinfo
+.next/
+out/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+
+# Data artifacts (keep demo/ tracked)
+data/cache/
+*.sqlite3
+
+.claude
+apps/private-platform-ui/

mattergraph_api-0.1.0/Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.12-slim
+RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
+  && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY pyproject.toml README.md /app/
+COPY _workspace_meta.py /app/
+COPY packages /app/packages
+COPY data /app/data
+RUN pip install --no-cache-dir uv
+RUN cd /app && uv sync --all-packages
+ENV PYTHONPATH=/app/packages/mattergraph-api
+EXPOSE 8000
+WORKDIR /app
+CMD ["uv", "run", "uvicorn", "mattergraph_api.main:app", "--host", "0.0.0.0", "--port", "8000"]

mattergraph_api-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: mattergraph-api
+Version: 0.1.0
+Summary: FastAPI service for the MatterGraph demo and integrations.
+Project-URL: Homepage, https://github.com/cyrusmo/MatterGraph
+Project-URL: Repository, https://github.com/cyrusmo/MatterGraph
+Project-URL: Issues, https://github.com/cyrusmo/MatterGraph/issues
+Project-URL: Changelog, https://github.com/cyrusmo/MatterGraph/blob/main/CHANGELOG.md
+Author: MatterGraph contributors
+License-Expression: Apache-2.0
+Keywords: api,fastapi,materials-informatics,materials-science
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: mattergraph-connectors~=0.1.0
+Requires-Dist: mattergraph-core~=0.1.0
+Requires-Dist: mattergraph-sim~=0.1.0
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pymatgen>=2024.1.1
+Requires-Dist: uvicorn[standard]>=0.29.0
+Description-Content-Type: text/markdown
+
+# mattergraph-api
+
+FastAPI demo service for [MatterGraph](https://github.com/cyrusmo/MatterGraph).
+
+This is a **demonstration surface**, not a production service: storage is an in-memory store loaded from a JSONL fixture, and the persistence layer under `mattergraph_api/db/` is a placeholder for installations that need one.
+
+## Routes
+
+| Route | Purpose |
+|---|---|
+| `GET /health` | Liveness |
+| `GET /materials`, `GET /materials/{mid}` | Browse normalized records |
+| `GET /search?element=` | Filter by element |
+| `POST /scores/rank` | Rank candidates with objectives, constraints, and weights |
+| `POST /simulations/ase/relax` | Run an ASE relaxation (503 if `ase` is unavailable) |
+| `GET /workflows/lematerial/demo` | End-to-end LeMat-Bulk screening walkthrough |
+
+## Install and run
+
+```bash
+pip install mattergraph-api
+export MATTERGRAPH_DEMO_DATA=data/demo/materials_sample.jsonl
+uvicorn mattergraph_api.main:app --host 0.0.0.0 --port 8000
+```
+
+## License
+
+Apache-2.0

mattergraph_api-0.1.0/README.md

@@ -0,0 +1,28 @@
+# mattergraph-api
+
+FastAPI demo service for [MatterGraph](https://github.com/cyrusmo/MatterGraph).
+
+This is a **demonstration surface**, not a production service: storage is an in-memory store loaded from a JSONL fixture, and the persistence layer under `mattergraph_api/db/` is a placeholder for installations that need one.
+
+## Routes
+
+| Route | Purpose |
+|---|---|
+| `GET /health` | Liveness |
+| `GET /materials`, `GET /materials/{mid}` | Browse normalized records |
+| `GET /search?element=` | Filter by element |
+| `POST /scores/rank` | Rank candidates with objectives, constraints, and weights |
+| `POST /simulations/ase/relax` | Run an ASE relaxation (503 if `ase` is unavailable) |
+| `GET /workflows/lematerial/demo` | End-to-end LeMat-Bulk screening walkthrough |
+
+## Install and run
+
+```bash
+pip install mattergraph-api
+export MATTERGRAPH_DEMO_DATA=data/demo/materials_sample.jsonl
+uvicorn mattergraph_api.main:app --host 0.0.0.0 --port 8000
+```
+
+## License
+
+Apache-2.0

mattergraph_api-0.1.0/mattergraph_api/__init__.py

@@ -0,0 +1 @@
+"""MatterGraph demo API package."""

mattergraph_api-0.1.0/mattergraph_api/config.py

@@ -0,0 +1,15 @@
+import os
+from pathlib import Path
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+  model_config = SettingsConfigDict(env_prefix="MATTERGRAPH_", extra="ignore")
+
+  demo_data: Path = Path(
+    os.environ.get("MATTERGRAPH_DEMO_DATA", "data/demo/materials_sample.jsonl")
+  )
+
+
+settings = Settings()

mattergraph_api-0.1.0/mattergraph_api/db/migrations/.gitkeep

@@ -0,0 +1 @@
+

mattergraph_api-0.1.0/mattergraph_api/db/models.py

@@ -0,0 +1,6 @@
+# Placeholder: SQLAlchemy models for setups that persist material records.
+
+from typing import Any
+
+# Not used in the open-source demo, which is JSONL-in-memory.
+StubModel: Any = object

mattergraph_api-0.1.0/mattergraph_api/db/session.py

@@ -0,0 +1,4 @@
+# Placeholder: database session factory for a user-provided persistence backend.
+
+def get_session() -> None:
+  return None

mattergraph_api-0.1.0/mattergraph_api/main.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from mattergraph_connectors.local_import import ImportLimitError, ImportValidationError
+
+from mattergraph_api.routes import datasets, demo, materials, scores, search, simulations, workflows
+from mattergraph_api.services.dataset_registry import (
+  DatasetBusyError,
+  DatasetCapacityError,
+  DatasetNotFoundError,
+)
+
+app = FastAPI(
+  title="MatterGraph API",
+  description=(
+    "Evidence-first demo API for provenanced materials records, reciprocal graph summaries, "
+    "audited ranking, and explicitly labeled simulation evidence."
+  ),
+  version="0.1.0",
+)
+app.add_middleware(
+  CORSMiddleware,
+  allow_origins=["*"],
+  allow_credentials=True,
+  allow_methods=["*"],
+  allow_headers=["*"],
+)
+
+app.include_router(materials.router, tags=["materials"])
+app.include_router(search.router, tags=["search"])
+app.include_router(scores.router, tags=["scores"])
+app.include_router(simulations.router, tags=["simulations"])
+app.include_router(workflows.router, tags=["workflows"])
+app.include_router(demo.router, tags=["demo"])
+app.include_router(datasets.router, tags=["datasets"])
+
+
+@app.exception_handler(DatasetNotFoundError)
+def dataset_not_found(_request: Request, error: DatasetNotFoundError) -> JSONResponse:
+  return JSONResponse(
+    status_code=404,
+    content={
+      "detail": str(error),
+      "code": "dataset_evicted" if error.evicted else "dataset_not_found",
+      "dataset_id": error.dataset_id,
+    },
+  )
+
+
+@app.exception_handler(DatasetBusyError)
+def dataset_busy(_request: Request, error: DatasetBusyError) -> JSONResponse:
+  return JSONResponse(status_code=409, content={"detail": str(error), "code": "dataset_busy"})
+
+
+@app.exception_handler(ImportLimitError)
+@app.exception_handler(DatasetCapacityError)
+def dataset_limit(_request: Request, error: Exception) -> JSONResponse:
+  return JSONResponse(status_code=413, content={"detail": str(error), "code": "dataset_limit"})
+
+
+@app.exception_handler(ImportValidationError)
+def invalid_import(_request: Request, error: ImportValidationError) -> JSONResponse:
+  return JSONResponse(
+    status_code=422,
+    content={
+      "detail": str(error),
+      "code": "invalid_import",
+      "report": error.report.model_dump(mode="json"),
+    },
+  )
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+  return {"status": "ok"}

mattergraph_api-0.1.0/mattergraph_api/routes/__init__.py

@@ -0,0 +1 @@
+"""API routes."""

mattergraph_api-0.1.0/mattergraph_api/routes/datasets.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from fastapi import APIRouter, Response
+from mattergraph import MaterialStore
+from mattergraph.datasets import DeduplicationBasis, MatterGraphDataset
+from mattergraph_connectors.local_import import (
+  DatasetImportMapping,
+  ImportReport,
+  ImportResult,
+  import_local_content,
+  inspect_local_content,
+)
+from pydantic import BaseModel, ConfigDict, Field
+
+from mattergraph_api.services.dataset_registry import dataset_registry
+from mattergraph_api.services.demo_service import graph_summary
+
+router = APIRouter(prefix="/datasets")
+
+
+class InspectRequest(BaseModel):
+  model_config = ConfigDict(extra="forbid")
+
+  filename: str
+  format: Literal["csv", "jsonl"]
+  content: str
+
+
+class ImportRequest(InspectRequest):
+  mapping: DatasetImportMapping | None = None
+  error_policy: Literal["reject_file", "skip_invalid_rows"] = "reject_file"
+
+
+class SlicePreviewRequest(BaseModel):
+  model_config = ConfigDict(extra="forbid")
+
+  include_elements: list[str] = Field(default_factory=list)
+  exclude_elements: list[str] = Field(default_factory=list)
+  max_nsites: int | None = Field(default=None, ge=1)
+  max_nelements: int | None = Field(default=None, ge=1)
+  target: str | None = None
+  deduplication_basis: DeduplicationBasis = "immutable_id"
+  allow_mixed_functionals: bool = False
+  allow_duplicate_records: bool = False
+
+
+@router.get("")
+def list_datasets() -> dict[str, Any]:
+  return {"datasets": dataset_registry.list(), "registry": dataset_registry.stats()}
+
+
+@router.post("/inspect", response_model=ImportReport)
+def inspect_dataset(request: InspectRequest) -> ImportReport:
+  return inspect_local_content(
+    filename=request.filename,
+    format=request.format,
+    content=request.content,
+  )
+
+
+@router.post("/import", response_model=ImportResult)
+def import_dataset(request: ImportRequest) -> ImportResult:
+  imported = import_local_content(
+    filename=request.filename,
+    format=request.format,
+    content=request.content,
+    mapping=request.mapping,
+    error_policy=request.error_policy,
+  )
+  dataset_registry.register(
+    imported.result.manifest,
+    imported.normalized_jsonl,
+  )
+  return imported.result.model_copy(
+    update={
+      "manifest": imported.result.manifest.model_copy(
+        update={"degraded": imported.result.manifest.degraded}
+      )
+    }
+  )
+
+
+@router.get("/{dataset_id}")
+def get_dataset(dataset_id: str) -> dict[str, Any]:
+  return dataset_registry.status(dataset_id)
+
+
+@router.delete("/{dataset_id}")
+def delete_dataset(dataset_id: str) -> dict[str, Any]:
+  manifest = dataset_registry.delete(dataset_id)
+  return {"deleted": True, "dataset_id": manifest.dataset_id}
+
+
+@router.get("/{dataset_id}/export")
+def export_dataset(dataset_id: str, format: Literal["jsonl"] = "jsonl") -> Response:
+  manifest, payload = dataset_registry.export(dataset_id)
+  return Response(
+    content=payload,
+    media_type="application/x-ndjson",
+    headers={
+      "Content-Disposition": f'attachment; filename="{manifest.dataset_id}.jsonl"',
+      "X-MatterGraph-Dataset-Id": manifest.dataset_id,
+      "X-MatterGraph-SHA256": manifest.normalized_sha256,
+      "X-MatterGraph-Record-Count": str(manifest.record_count),
+    },
+  )
+
+
+@router.post("/{dataset_id}/slices/preview")
+def preview_slice(dataset_id: str, request: SlicePreviewRequest) -> dict[str, Any]:
+  store = dataset_registry.materialize(dataset_id)
+  dataset = _dataset_from_store(dataset_id, store)
+  candidate = dataset.candidate_pool(
+    include=request.include_elements,
+    exclude=request.exclude_elements,
+    max_nsites=request.max_nsites,
+    max_nelements=request.max_nelements,
+  )
+  candidate_slice = candidate.create_slice(
+    "local_workbench_preview",
+    allow_mixed_functionals=request.allow_mixed_functionals,
+    allow_duplicate_records=request.allow_duplicate_records,
+    deduplication_basis=request.deduplication_basis,
+    target=request.target,
+  )
+  graph_ready = 0
+  graph_excluded = 0
+  material_ids = [str(value) for value in candidate_slice.frame["material_id"].tolist()]
+  materials_by_id = {material.material_id: material for material in store.materials}
+  for material_id in material_ids:
+    try:
+      graph_summary(materials_by_id[material_id], max_edges=0)
+      graph_ready += 1
+    except ValueError:
+      graph_excluded += 1
+  preview_columns = ["material_id", "formula", "nsites", "nelements"]
+  if request.target:
+    preview_columns.append(request.target)
+  frame = candidate_slice.frame
+  preview_columns = [column for column in preview_columns if column in frame.columns]
+  benchmark_preview = frame[preview_columns].head(20).where(frame.notna(), None).to_dict(
+    orient="records"
+  )
+  return {
+    "slice": candidate_slice.report(),
+    "material_ids": material_ids,
+    "graph_readiness": {"included_count": graph_ready, "excluded_count": graph_excluded},
+    "benchmark_preview": benchmark_preview,
+  }
+
+
+def _dataset_from_store(dataset_id: str, store: MaterialStore) -> MatterGraphDataset:
+  records: list[dict[str, Any]] = []
+  property_columns: set[str] = set()
+  property_units: dict[str, str] = {}
+  for material in store.materials:
+    record: dict[str, Any] = {
+      "material_id": material.material_id,
+      "formula": material.formula,
+      "reduced_formula": material.reduced_formula,
+      "elements": material.elements,
+      "structure": material.structure,
+      "immutable_id": material.material_id,
+      "provenance": material.provenance,
+    }
+    for property_value in material.properties:
+      record[property_value.name] = property_value.value
+      property_columns.add(property_value.name)
+      if property_value.unit:
+        property_units.setdefault(property_value.name, property_value.unit)
+    records.append(record)
+  return MatterGraphDataset.from_records(
+    records,
+    source_dataset=dataset_id,
+    source_subset="local_import",
+    metadata={
+      "default_deduplication_basis": "immutable_id",
+      "property_columns": sorted(property_columns),
+      "property_units": property_units,
+      "provenance_fields": ["immutable_id", "provenance"],
+    },
+  )

mattergraph_api-0.1.0/mattergraph_api/routes/demo.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter
+
+from mattergraph_api.services import store_service
+from mattergraph_api.services.demo_service import (
+  DEFAULT_CONSTRAINTS,
+  DEFAULT_OBJECTIVES,
+  FIXTURE_DISCLAIMER,
+  FIXTURE_RELATIVE_PATH,
+  capability_catalog,
+  chgnet_state,
+  get_default_material_id,
+  get_default_scorecard,
+  get_demo_manifest,
+  graph_summary,
+  simulation_readiness,
+)
+
+router = APIRouter()
+
+
+@router.get("/capabilities")
+def capabilities() -> dict[str, list[dict[str, Any]]]:
+  return {"capabilities": capability_catalog()}
+
+
+@router.get("/demo/preflight")
+def demo_preflight() -> dict[str, Any]:
+  store = store_service.get_store()
+  graph_ready = 0
+  graph_excluded = 0
+  graph_invalid = 0
+  for material in store.materials:
+    try:
+      summary = graph_summary(material, max_edges=0)
+      graph_ready += 1
+      if summary["validation"]["state"] != "valid":
+        graph_invalid += 1
+    except ValueError:
+      graph_excluded += 1
+
+  scorecard = get_default_scorecard()
+  score_report = scorecard.report(store.materials)
+  simulation_targets = {
+    material.material_id: simulation_readiness(material) for material in store.materials
+  }
+  default_material_id = get_default_material_id()
+  manifest = get_demo_manifest()
+  ml_state = chgnet_state()
+  checks = [
+    {
+      "id": "fixture",
+      "status": "pass" if store.materials else "fail",
+      "detail": f"{len(store.materials)} normalized records",
+    },
+    {
+      "id": "graphs",
+      "status": "pass" if graph_ready and not graph_invalid else "fail",
+      "detail": (
+        f"{graph_ready} graph-ready; {graph_excluded} excluded; {graph_invalid} invalid"
+      ),
+    },
+    {
+      "id": "ranking",
+      "status": "pass" if score_report["ranked_count"] >= 3 else "warn",
+      "detail": (
+        f"{score_report['ranked_count']} rank-eligible; "
+        f"{score_report['excluded_by_constraints']} excluded"
+      ),
+    },
+    {
+      "id": "ml_reference",
+      "status": "pass" if ml_state["reference_available"] else "warn",
+      "detail": str(ml_state["detail"]),
+    },
+  ]
+  overall = "ready" if all(check["status"] == "pass" for check in checks) else "degraded"
+  return {
+    "status": overall,
+    "fixture": {
+      "path": FIXTURE_RELATIVE_PATH,
+      "kind": "checksummed_real_snapshot",
+      "disclaimer": FIXTURE_DISCLAIMER,
+      "dataset": manifest["dataset"],
+      "subset": manifest["subset"],
+      "upstream_revision": manifest["upstream_revision"],
+      "hull_dataset": manifest["hull_dataset"],
+      "hull_revision": manifest["hull_revision"],
+      "license": manifest["license"],
+      "citation_doi": manifest["citation_doi"],
+      "snapshot_sha256": manifest["snapshot_sha256"],
+      "source_population": manifest["source_population"],
+      "field_sources": manifest["field_sources"],
+    },
+    "record_count": len(store.materials),
+    "graph": {
+      "included_count": graph_ready,
+      "excluded_count": graph_excluded,
+      "invalid_count": graph_invalid,
+      "validation_state": "valid" if graph_ready and not graph_invalid else "invalid",
+    },
+    "ranking": {
+      "ranked_count": score_report["ranked_count"],
+      "excluded_by_constraints": score_report["excluded_by_constraints"],
+      "binary_normalization": score_report["binary_normalization"],
+      "objectives": DEFAULT_OBJECTIVES,
+      "constraints": DEFAULT_CONSTRAINTS,
+    },
+    "default_material_id": default_material_id,
+    "chgnet": ml_state,
+    "simulation_targets": simulation_targets,
+    "checks": checks,
+  }

mattergraph_api-0.1.0/mattergraph_api/routes/materials.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException, Query
+from mattergraph import Material
+
+from mattergraph_api.services import store_service
+from mattergraph_api.services.demo_service import graph_summary
+
+router = APIRouter()
+
+
+@router.get("/materials")
+def list_materials(dataset_id: str | None = Query(default=None)) -> list[dict]:
+  store = store_service.resolve_store(dataset_id)
+  return [m.model_dump() for m in store.materials]
+
+
+@router.get("/materials/{mid}")
+def get_material(mid: str, dataset_id: str | None = Query(default=None)) -> dict:
+  store = store_service.resolve_store(dataset_id)
+  m: Material | None = store.get(mid)
+  if m is None:
+    raise HTTPException(status_code=404, detail="not found")
+  return m.model_dump()
+
+
+@router.get("/materials/{mid}/graph-summary")
+def get_material_graph_summary(
+  mid: str, dataset_id: str | None = Query(default=None)
+) -> dict:
+  store = store_service.resolve_store(dataset_id)
+  material: Material | None = store.get(mid)
+  if material is None:
+    raise HTTPException(status_code=404, detail="not found")
+  try:
+    return graph_summary(material)
+  except ValueError as exc:
+    raise HTTPException(status_code=422, detail=str(exc)) from exc