mattergraph-api 0.1.0__py3-none-any.whl

mattergraph_api/__init__.py

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

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/db/migrations/.gitkeep

@@ -0,0 +1 @@
+

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/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/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/routes/__init__.py

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

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/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/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

mattergraph_api/routes/scores.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from fastapi import APIRouter
+from mattergraph import Scorecard
+from pydantic import BaseModel, ConfigDict, Field
+
+from mattergraph_api.services import store_service
+
+router = APIRouter()
+
+
+Direction = Literal["minimize", "maximize"]
+MissingPolicy = Literal["worst", "neutral", "exclude"]
+
+
+class ObjectiveConfig(BaseModel):
+  model_config = ConfigDict(extra="forbid")
+
+  direction: Direction = "maximize"
+  weight: float = Field(default=1.0, ge=0.0)
+
+
+class ConstraintConfig(BaseModel):
+  model_config = ConfigDict(extra="forbid")
+
+  min: float | None = None
+  max: float | None = None
+  equals: bool | float | str | None = None
+
+
+class ScoreRequest(BaseModel):
+  model_config = ConfigDict(extra="forbid")
+
+  objectives: dict[str, Direction | ObjectiveConfig] = Field(
+    default_factory=dict,
+  )
+  constraints: dict[str, ConstraintConfig] = Field(default_factory=dict)
+  weights: dict[str, float] | None = None
+  missing: MissingPolicy = "worst"
+  dataset_id: str | None = None
+
+
+@router.post("/scores/rank")
+def rank(request: ScoreRequest) -> list[dict]:
+  store = store_service.resolve_store(request.dataset_id)
+  sc = _scorecard(request)
+  df = sc.rank(store.materials)
+  return df.to_dict(orient="records")
+
+
+@router.post("/scores/rank/audit")
+def rank_with_audit(request: ScoreRequest) -> dict[str, Any]:
+  store = store_service.resolve_store(request.dataset_id)
+  scorecard = _scorecard(request)
+  ranked = scorecard.rank(store.materials).to_dict(orient="records")
+  materials_by_id = {material.material_id: material for material in store.materials}
+  for row in ranked:
+    material = materials_by_id.get(str(row.get("material_id")))
+    if material is None:
+      continue
+    for property_name in request.constraints:
+      row.setdefault(property_name, material.get_numeric(property_name))
+  return {
+    "ranked": ranked,
+    "report": scorecard.report(store.materials),
+    "request": request.model_dump(mode="json"),
+  }
+
+
+def _scorecard(request: ScoreRequest) -> Scorecard:
+  payload = request.model_dump(mode="python", exclude_none=True)
+  payload.pop("dataset_id", None)
+  return Scorecard(
+    objectives=payload["objectives"],
+    constraints=payload["constraints"],
+    weights=payload.get("weights"),
+    missing=payload["missing"],
+  )

mattergraph_api/routes/search.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Query
+
+from mattergraph_api.services import store_service
+
+router = APIRouter()
+
+
+@router.get("/search")
+def search(
+  element: str | None = Query(
+    default=None, description="Filter materials whose elements contain this symbol, e.g. Fe"
+  ),
+  dataset_id: str | None = Query(default=None),
+) -> list[dict]:
+  store = store_service.resolve_store(dataset_id)
+  out = []
+  for m in store.materials:
+    if not element:
+      out.append(m.model_dump())
+      continue
+    e = element.strip()
+    if e in m.elements:
+      out.append(m.model_dump())
+  return out

mattergraph_api/routes/simulations.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException
+from mattergraph_sim.job_spec import AseJobSpec, SimulationJob
+from pydantic import BaseModel, Field
+
+from mattergraph_api.services import store_service
+from mattergraph_api.services.demo_service import get_chgnet_reference_artifact
+
+router = APIRouter()
+
+
+@router.get("/simulations/chgnet/reference/{material_id}")
+def get_chgnet_reference(material_id: str) -> dict:
+  artifact = get_chgnet_reference_artifact()
+  if artifact is None:
+    raise HTTPException(status_code=503, detail="verified CHGNet reference is unavailable")
+  if artifact["material_id"] != material_id:
+    raise HTTPException(status_code=404, detail="no CHGNet reference for this material")
+  return artifact
+
+
+class RelaxRequest(BaseModel):
+  material_id: str
+  dataset_id: str | None = None
+  spec: AseJobSpec = Field(default_factory=AseJobSpec)
+
+
+@router.post("/simulations/ase/relax")
+def run_relax(body: RelaxRequest) -> dict:
+  try:
+    from mattergraph_sim import ase_relax
+  except ImportError as e:
+    raise HTTPException(status_code=503, detail=str(e)) from e
+
+  store = store_service.resolve_store(body.dataset_id)
+  m = store.get(body.material_id)
+  if m is None or m.structure is None:
+    raise HTTPException(status_code=400, detail="material or structure missing")
+  st = m.structure
+  job = SimulationJob(
+    spec=body.spec,
+    input_structure=st.to_json_dict(),
+  )
+  out = ase_relax(job)
+  return out.model_dump()

mattergraph_api/routes/workflows.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from mattergraph_api.services.workflow_service import (
+  LeMaterialDemoWorkflowResponse,
+  build_lematerial_demo_workflow,
+)
+
+router = APIRouter()
+
+
+@router.get(
+  "/workflows/lematerial/demo",
+  response_model=LeMaterialDemoWorkflowResponse,
+)
+def lematerial_demo_workflow() -> LeMaterialDemoWorkflowResponse:
+  return build_lematerial_demo_workflow()

mattergraph_api/services/__init__.py

@@ -0,0 +1 @@
+"""Service layer for the demo API."""