modelspec-dev 0.1.0__py3-none-any.whl

schema/graph.py

@@ -0,0 +1,406 @@
+"""FalkorDB graph schema — node types, edge types, and Cypher operations.
+
+This module defines the complete ontology and provides functions to:
+  - Create indexes
+  - Ingest a ModelCard into the graph as nodes + edges
+  - Run common traversal queries
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from .enums import DeviceClass
+
+
+# ═══════════════════════════════════════════════════════════════
+# Edge type registry
+# ═══════════════════════════════════════════════════════════════
+
+class EdgeType(str, Enum):
+    """All relationship types in the graph."""
+    # Factual (directly observed)
+    MADE_BY = "MADE_BY"
+    DERIVED_FROM = "DERIVED_FROM"
+    MERGED_FROM = "MERGED_FROM"
+    LICENSED_AS = "LICENSED_AS"
+    HAS_CAPABILITY = "HAS_CAPABILITY"
+    SCORED_ON = "SCORED_ON"
+    FITS_ON = "FITS_ON"
+    AVAILABLE_AS = "AVAILABLE_AS"
+    RUNS_ON = "RUNS_ON"
+    AVAILABLE_ON = "AVAILABLE_ON"
+    TAGGED_WITH = "TAGGED_WITH"
+    SUITED_FOR = "SUITED_FOR"
+    PUBLISHED_BY = "PUBLISHED_BY"
+    SUPPORTS_RUNTIME = "SUPPORTS_RUNTIME"
+    TESTS_CAPABILITY = "TESTS_CAPABILITY"
+    REQUIRED_BY = "REQUIRED_BY"
+    HOSTS = "HOSTS"                    # (:Host)-[:HOSTS]->(:Hardware), unified hosts only
+
+    # Derived (computed by ranking engine)
+    COMPETES_WITH = "COMPETES_WITH"
+    OUTPERFORMS = "OUTPERFORMS"
+    SIMILAR_TO = "SIMILAR_TO"
+    UPGRADE_PATH = "UPGRADE_PATH"
+    BEST_FOR = "BEST_FOR"
+    PARETO_OPTIMAL = "PARETO_OPTIMAL"
+
+    # Institutional (organization-specific overlay)
+    APPROVED_BY = "APPROVED_BY"
+    EXCLUDED_BY = "EXCLUDED_BY"
+    REVIEWED_BY = "REVIEWED_BY"
+    PREFERRED_BY = "PREFERRED_BY"
+
+
+# ═══════════════════════════════════════════════════════════════
+# Index definitions
+# ═══════════════════════════════════════════════════════════════
+
+INDEXES = [
+    "CREATE INDEX ON :Model(id)",
+    "CREATE INDEX ON :Model(model_type)",
+    "CREATE INDEX ON :Model(status)",
+    "CREATE INDEX ON :Model(origin_country)",
+    "CREATE INDEX ON :Model(open_weights)",
+    "CREATE INDEX ON :Model(total_parameters)",
+    "CREATE INDEX ON :Model(arena_elo_overall)",
+    "CREATE INDEX ON :Model(cost_input)",
+    "CREATE INDEX ON :Model(context_window)",
+    "CREATE INDEX ON :Model(release_date)",
+    "CREATE INDEX ON :Provider(id)",
+    "CREATE INDEX ON :Platform(id)",
+    "CREATE INDEX ON :Platform(category)",
+    "CREATE INDEX ON :Capability(id)",
+    "CREATE INDEX ON :Capability(category)",
+    "CREATE INDEX ON :Hardware(id)",
+    "CREATE INDEX ON :Hardware(memory_gb)",
+    # "which models fit datacentre hardware" is a class filter before it is a
+    # traversal, so the class is indexed like any other node grouping key.
+    "CREATE INDEX ON :Hardware(device_class)",
+    "CREATE INDEX ON :Host(id)",
+    "CREATE INDEX ON :Benchmark(id)",
+    "CREATE INDEX ON :Benchmark(category)",
+    "CREATE INDEX ON :License(id)",
+    "CREATE INDEX ON :UseCase(id)",
+    "CREATE INDEX ON :DownselectProfile(id)",
+    "CREATE INDEX ON :Runtime(id)",
+    "CREATE INDEX ON :Quantization(id)",
+    "CREATE INDEX ON :Tag(id)",
+]
+
+
+def create_indexes(graph) -> None:
+    """Create all indexes on a FalkorDB graph instance."""
+    for idx in INDEXES:
+        try:
+            graph.query(idx)
+        except Exception:
+            pass  # Index may already exist
+
+
+# ═══════════════════════════════════════════════════════════════
+# Ingestion: ModelCard → Graph nodes + edges
+# ═══════════════════════════════════════════════════════════════
+
+def device_class_of(hw_id: str, device_classes: Mapping[str, str] | None) -> str | None:
+    """The class of the device `hw_id` names, or None when nothing knows it.
+
+    `hardware/*.yaml` is the only source of a device class, and this module is
+    below the loader that reads it, so the caller passes the mapping in. A card
+    may key a hardware profile on anything, including the four legacy ids the
+    card schema still defaults to (`nvidia_5090_32gb` and friends), which name
+    no device record. Those get no class rather than a guessed one: a Hardware
+    node wrongly labelled `datacentre` is worse than one a class filter skips.
+
+    A value outside `DeviceClass` is a typo in a record, not a new class, and
+    is refused here so it cannot reach the export and split a group in two.
+    """
+    if not device_classes:
+        return None
+    value = device_classes.get(hw_id)
+    if value is None:
+        return None
+    return DeviceClass(value).value
+
+
+def ingest_model_card(graph, card, *,
+                      device_classes: Mapping[str, str] | None = None) -> dict[str, int]:
+    """Ingest a ModelCard into FalkorDB, creating/merging all nodes and edges.
+
+    `device_classes` maps a device id to its `DeviceClass` value (from
+    `pipeline.hardware.device_classes`). It is optional so the FalkorDB ingest
+    and the ranking CLI keep working without the hardware records; when it is
+    given, the Hardware nodes this derives carry `device_class` and can be
+    grouped by it.
+
+    Returns a dict with counts: {"nodes_created": N, "edges_created": M}
+    """
+    from .card import ModelCard
+
+    # Accept either a sink or a raw FalkorDB handle, so existing callers such
+    # as scripts/ingest_all.py keep working unchanged.
+    sink = graph if hasattr(graph, "node") else CypherSink(graph)
+
+    stats = {"nodes_created": 0, "edges_created": 0}
+    ident = card.identity
+    arch = card.architecture
+    lic = card.licensing
+
+    # ── 1. Upsert the :Model node ──────────────────────────
+    model_props = {
+        "id": ident.model_id,
+        "display_name": ident.display_name,
+        "model_type": ident.model_type.value if ident.model_type else None,
+        "status": ident.status.value,
+        "release_date": ident.release_date,
+        "family": ident.family,
+        "origin_country": lic.origin_country,
+        "open_weights": lic.open_weights,
+        "total_parameters": arch.total_parameters,
+        "active_parameters": arch.active_parameters,
+        "architecture_type": arch.type.value if arch.type else None,
+        "context_window": card.modalities.text.context_window,
+        "max_input": card.modalities.text.max_input_tokens,
+        "max_output": card.modalities.text.max_output_tokens,
+        "cost_input": card.cost.input,
+        "cost_output": card.cost.output,
+        "arena_elo_overall": card.benchmarks.scores.get("arena_elo_overall"),
+        "custom_score": card.downselect.custom_score,
+        "embedding_dimensions": arch.embedding_dimensions,
+        "reasoning": card.capabilities.reasoning.chain_of_thought,
+        "tool_call": card.capabilities.tool_use.function_calling,
+        "vision_input": card.modalities.vision.supported,
+        "multilingual": card.capabilities.language.multilingual,
+        "model_subtypes": ",".join(st.value for st in ident.model_subtypes) if ident.model_subtypes else None,
+    }
+
+    # Filter out None values for cleaner Cypher
+    props = {k: v for k, v in model_props.items() if v is not None}
+    sink.node("Model", "id", ident.model_id, props)
+    stats["nodes_created"] += 1
+
+    # ── 2. Upsert :Provider and :MADE_BY ───────────────────
+    if ident.provider:
+        sink.node("Provider", "id", ident.provider, {
+            "id": ident.provider,
+            "display_name": ident.provider_display or ident.provider,
+            "country": lic.origin_country,
+        })
+        sink.edge("Model", ident.model_id, "MADE_BY", "Provider", ident.provider)
+        stats["nodes_created"] += 1
+        stats["edges_created"] += 1
+
+    # ── 3. Upsert :License and :LICENSED_AS ────────────────
+    if lic.license_type:
+        license_id = lic.license_type.value
+        sink.node("License", "id", license_id, {
+            "id": license_id,
+            "name": license_id,
+            # A UsePermission since MODEL-77, not a bool: "restricted"
+            # is the answer for 169 cards and had nowhere to go before.
+            "commercial_ok": lic.commercial_use.value,
+            "defense_ok": lic.defense_use.value,
+            "government_ok": lic.government_use.value,
+        })
+        sink.edge("Model", ident.model_id, "LICENSED_AS", "License", license_id)
+        stats["edges_created"] += 1
+
+    # ── 4. Upsert :DERIVED_FROM (lineage) ──────────────────
+    if card.lineage.base_model:
+        sink.node("Model", "id", card.lineage.base_model, {
+            "id": card.lineage.base_model,
+        })
+        edge_props = {}
+        if card.lineage.base_model_relation:
+            edge_props["relation"] = card.lineage.base_model_relation.value
+        sink.edge("Model", ident.model_id, "DERIVED_FROM",
+                     "Model", card.lineage.base_model, edge_props)
+        stats["edges_created"] += 1
+
+    # ── 5. Capabilities → :HAS_CAPABILITY edges ───────────
+    cap_map = _extract_capabilities(card.capabilities)
+    for cap_id, tier in cap_map.items():
+        category = cap_id.split(":")[0] if ":" in cap_id else "general"
+        sink.node("Capability", "id", cap_id, {
+            "id": cap_id,
+            "category": category,
+            "name": cap_id.split(":")[-1].replace("_", " ").title(),
+        })
+        sink.edge("Model", ident.model_id, "HAS_CAPABILITY",
+                     "Capability", cap_id, {"tier": tier})
+        stats["edges_created"] += 1
+
+    # ── 6. Benchmarks → :SCORED_ON edges ───────────────────
+    for bench_id, value in card.benchmarks.scores.items():
+        if isinstance(value, (int, float)):
+            sink.node("Benchmark", "id", bench_id, {
+                "id": bench_id,
+                "name": bench_id.replace("_", " ").title(),
+            })
+            sink.edge("Model", ident.model_id, "SCORED_ON",
+                         "Benchmark", bench_id, {
+                             "value": float(value),
+                             "date": card.benchmarks.benchmark_as_of,
+                         })
+            stats["edges_created"] += 1
+
+    # ── 7. Hardware profiles → :FITS_ON edges ──────────────
+    for hw_id, profile in card.deployment.hardware_profiles.items():
+        if profile.fits:
+            hw_props = {"id": hw_id, "display_name": hw_id}
+            hw_class = device_class_of(hw_id, device_classes)
+            if hw_class is not None:
+                hw_props["device_class"] = hw_class
+            sink.node("Hardware", "id", hw_id, hw_props)
+            edge_props = {k: v for k, v in {
+                "quantization": profile.best_quant,
+                "vram_usage_gb": profile.vram_usage_gb or profile.ram_usage_gb,
+                "tokens_per_sec": profile.tokens_per_sec,
+                "ttft_ms": profile.ttft_ms,
+                "max_context_tokens": profile.max_context_at_quant,
+                "inference_engine": profile.inference_engine,
+            }.items() if v}
+            sink.edge("Model", ident.model_id, "FITS_ON",
+                         "Hardware", hw_id, edge_props)
+            stats["edges_created"] += 1
+
+    # ── 8. Platform availability → :AVAILABLE_ON edges ─────
+    for field_name, field_value in card.availability:
+        if isinstance(field_value, PlatformEntry_type()) and field_value.available:
+            platform_id = field_name
+            sink.node("Platform", "id", platform_id, {
+                "id": platform_id,
+                "display_name": field_name.replace("_", " ").title(),
+                "url": field_value.url,
+            })
+            edge_props = {k: v for k, v in {
+                "model_id_on_platform": field_value.model_id,
+                "fine_tuning": field_value.fine_tuning,
+                "gated": field_value.gated,
+                "notes": field_value.notes,
+            }.items() if v}
+            sink.edge("Model", ident.model_id, "AVAILABLE_ON",
+                         "Platform", platform_id, edge_props)
+            stats["edges_created"] += 1
+
+    # ── 9. Tags → :TAGGED_WITH edges ──────────────────────
+    for tag in ident.tags:
+        sink.node("Tag", "id", tag, {"id": tag})
+        sink.edge("Model", ident.model_id, "TAGGED_WITH", "Tag", tag)
+        stats["edges_created"] += 1
+
+    return stats
+
+
+def PlatformEntry_type():
+    """Lazy import to avoid circular dependency."""
+    from .card import PlatformEntry
+    return PlatformEntry
+
+
+# ═══════════════════════════════════════════════════════════════
+# Helpers
+# ═══════════════════════════════════════════════════════════════
+
+class CypherSink:
+    """Writes the derived graph into FalkorDB, one MERGE at a time."""
+
+    def __init__(self, graph) -> None:
+        self.graph = graph
+
+    def node(self, label: str, key_field: str, key_value: str, props: dict[str, Any]) -> None:
+        extra_props = {k: v for k, v in props.items() if k != key_field}
+        if extra_props:
+            prop_str = ", ".join(f"n.{k} = ${k}" for k in extra_props)
+            query = f"MERGE (n:{label} {{{key_field}: ${key_field}}}) SET {prop_str}"
+        else:
+            query = f"MERGE (n:{label} {{{key_field}: ${key_field}}})"
+        self.graph.query(query, props)
+
+    def edge(self, from_label: str, from_id: str, edge_type: str,
+             to_label: str, to_id: str, props: dict[str, Any] | None = None) -> None:
+        if props:
+            prop_str = " {" + ", ".join(f"{k}: ${k}" for k in props) + "}"
+        else:
+            prop_str = ""
+        params = {"from_id": from_id, "to_id": to_id, **(props or {})}
+        query = (
+            f"MATCH (a:{from_label} {{id: $from_id}}) "
+            f"MATCH (b:{to_label} {{id: $to_id}}) "
+            f"MERGE (a)-[:{edge_type}{prop_str}]->(b)"
+        )
+        self.graph.query(query, params)
+
+
+class CollectingSink:
+    """Accumulates the derived graph in memory, with no database.
+
+    This is what lets the build emit the graph as JSON. It reproduces MERGE
+    semantics: a node seen twice keeps the union of its properties, later
+    non-null values winning, so a model referenced as another model's base
+    before its own card is read still ends up complete.
+    """
+
+    def __init__(self) -> None:
+        self.nodes: dict[tuple[str, str], dict[str, Any]] = {}
+        self.edges: list[dict[str, Any]] = []
+
+    def node(self, label: str, key_field: str, key_value: str, props: dict[str, Any]) -> None:
+        existing = self.nodes.setdefault((label, key_value), {key_field: key_value})
+        for key, value in props.items():
+            if value is not None:
+                existing[key] = value
+
+    def edge(self, from_label: str, from_id: str, edge_type: str,
+             to_label: str, to_id: str, props: dict[str, Any] | None = None) -> None:
+        self.edges.append({
+            "type": edge_type,
+            "from": from_id,
+            "from_label": from_label,
+            "to": to_id,
+            "to_label": to_label,
+            **({"props": props} if props else {}),
+        })
+
+
+def derive_graph(cards, device_classes: Mapping[str, str] | None = None) -> CollectingSink:
+    """Derive the whole graph from model cards, without touching a database.
+
+    `device_classes` is passed straight to `ingest_model_card`; see there.
+    """
+    sink = CollectingSink()
+    for card in cards:
+        ingest_model_card(sink, card, device_classes=device_classes)
+    return sink
+
+
+def _extract_capabilities(caps) -> dict[str, str]:
+    """Extract capability IDs and tiers from the Capabilities model."""
+    result = {}
+
+    def _process_section(prefix: str, section):
+        for field_name, _ in section:
+            value = getattr(section, field_name)
+            if field_name == "overall" and value:
+                result[prefix] = value.value if hasattr(value, "value") else str(value)
+            elif isinstance(value, bool) and value:
+                cap_id = f"{prefix}:{field_name}"
+                # Boolean capabilities get tier from their section's overall
+                overall = getattr(section, "overall", None)
+                tier = overall.value if overall and hasattr(overall, "value") else "tier-2"
+                result[cap_id] = tier
+
+    _process_section("coding", caps.coding)
+    _process_section("reasoning", caps.reasoning)
+    _process_section("tool_use", caps.tool_use)
+    _process_section("language", caps.language)
+    _process_section("creative", caps.creative)
+    _process_section("safety", caps.safety_alignment)
+    _process_section("domain", caps.domain_specific)
+    _process_section("agent", caps.agent_capabilities)
+
+    return result

schema/suppliers.py

@@ -0,0 +1,72 @@
+"""Organisations ModelSpec buys from, and what a purchase costs us (MODEL-101).
+
+ModelSpec pays TypeSafe for API access and runs **Jev — TypeSafe's own model —**
+over ambiguous creator attributions (`scripts/attribution.py`). Then the
+catalogue acquired a TypeSafe card, so the supplier is now also a subject.
+
+Money flows *to* the vendor, so nothing in `neutrality_commitment()`
+(`api/ranking/engine.py`) is contradicted: no referral fee, no paid placement,
+no provider-paid visibility, and a purchase buys a supplier nothing in a
+ranking. Two things follow anyway, and neither is a promise — both are
+mechanisms:
+
+1. **The reader is told.** A card whose provider is named here carries the
+   disclosure on its page, derived from this table rather than authored per
+   card, so it cannot be left off the next one (`pipeline/render.py`).
+2. **A supplier's model never writes a field on that supplier's card.**
+   `scripts/attribution.py` refuses the judgment before it is asked, and
+   refuses a stored one before it is applied. `tests/test_attribution.py`
+   fails if either refusal is removed.
+
+What is *not* refused: deterministic attribution. An id prefix that names
+TypeSafe is code reading a string — no model call and no opinion — and it stays
+allowed. The rule is about the judgment, and the judgment alone.
+
+One table, two readers, so the org the page discloses and the org the guard
+protects cannot drift apart.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Supplier:
+    """A vendor ModelSpec pays, that the catalogue also documents."""
+
+    #: The catalogue's provider slug: `models/<slug>/`.
+    slug: str
+    display: str
+    #: What we buy. Shown to a reader, so it is a sentence, not a label.
+    relationship: str
+    #: The rule that follows from it, in the same words on the page and here.
+    rule: str
+
+
+SUPPLIERS: dict[str, Supplier] = {
+    "typesafe": Supplier(
+        slug="typesafe",
+        display="TypeSafe AI",
+        relationship=(
+            "ModelSpec is a paying TypeSafe customer. The catalogue's own pipeline sends "
+            "ambiguous creator attributions to Jev and pays per input token for the answer "
+            "(scripts/attribution.py, MODEL-82)."
+        ),
+        rule=(
+            "No field on a TypeSafe card may be written by a Jev judgment. TypeSafe listings "
+            "are attributed by code or by a person, or they are left unattributed; the "
+            "judgment is refused before it is asked."
+        ),
+    ),
+}
+
+#: Provider slugs under the rule. The guard and the page read the same set.
+SUPPLIER_SLUGS: frozenset[str] = frozenset(SUPPLIERS)
+
+
+def supplier_for(provider: str | None) -> Supplier | None:
+    """The supplier a card's `provider` names, or `None` for every other card."""
+    if not provider:
+        return None
+    return SUPPLIERS.get(str(provider).strip().lower())