lintel-api 0.1.0a1__py3-none-any.whl

lintel/__init__.py

@@ -0,0 +1,3 @@
+"""Lintel: experimental GraphQL projection from UMF. See release limitations."""
+
+__version__ = "0.1.0a1"

lintel/experimental/projection.py

@@ -0,0 +1,121 @@
+"""S-01: read UMF itself, project a deliberately small scalar-only subset.
+
+Not an alternative UMF validator: core validity/completeness belongs to umf-core.
+This spike has no production activation path and no executor.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, cast
+
+# UMF generates Document dynamically; confine its incomplete static annotations here.
+from umf import read_document, validate_document  # pyright: ignore[reportUnknownVariableType]
+
+Ref = tuple[str, str]
+RESERVED = {"Node", "Query", "Mutation", "PageInfo", "Decimal", "UUID", "PresenceProbe"}
+
+
+class ProjectionError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Field:
+    source: Ref
+    name: str
+    scalar: str
+    optional: bool
+
+
+@dataclass(frozen=True)
+class Projection:
+    source_text: str
+    record: Ref
+    name: str
+    fields: tuple[Field, ...]
+
+
+def _name(name: str) -> None:
+    if not re.fullmatch(r"[_A-Za-z][_0-9A-Za-z]*", name) or name.startswith("__"):
+        raise ProjectionError("NAME_COLLISION: invalid or reserved GraphQL name")
+
+
+def project(source_text: str, record: Ref, name: str, fields: dict[Ref, str]) -> Projection:
+    index = _read_index(source_text)
+    _name(name)
+    if name in RESERVED or name + "Input" in RESERVED:
+        raise ProjectionError("NAME_COLLISION: generated or reserved type")
+    owner = index.get(record)
+    if owner is None or owner["kind"] != "record":
+        raise ProjectionError("INVALID_EXPOSURE: expected UMF record")
+    _subset(owner, {"id", "name", "kind", "members", "keys", "extensions"})
+    members = {(ref["module"], ref["element"]) for ref in owner["members"]}
+    projected: list[Field] = []
+    names: set[str] = set()
+    for ref, api_name in fields.items():
+        _name(api_name)
+        if api_name in names or api_name == "id":
+            raise ProjectionError("NAME_COLLISION: duplicate or Relay id field")
+        names.add(api_name)
+        field = index.get(ref)
+        if ref not in members or field is None or field["kind"] != "field":
+            raise ProjectionError("INVALID_EXPOSURE: field is not a record member")
+        _subset(
+            field,
+            {
+                "id",
+                "name",
+                "kind",
+                "scalarType",
+                "cardinality",
+                "nullability",
+                "extensions",
+                "facets",
+            },
+        )
+        _check_scalar(field)
+        projected.append(
+            Field(ref, api_name, field["scalarType"], field["nullability"] == "absent-allowed")
+        )
+    if not projected:
+        raise ProjectionError("INVALID_EXPOSURE: empty selection")
+    return Projection(source_text, record, name, tuple(sorted(projected, key=lambda f: f.name)))
+
+
+def _check_scalar(field: dict[str, Any]) -> None:
+    if field.get("scalarType") not in {"string", "boolean", "decimal", "uuid"}:
+        raise ProjectionError("UNSUPPORTED: scalar outside spike subset")
+    if field.get("cardinality") != "one":
+        raise ProjectionError("UNSUPPORTED: cardinality outside spike subset")
+    if field.get("nullability") not in {"required", "absent-allowed"}:
+        raise ProjectionError("UNSUPPORTED: availability outside spike subset")
+    if field.get("facets", {}) and (
+        field["scalarType"] != "decimal" or set(field["facets"]) - {"precision", "scale"}
+    ):
+        raise ProjectionError("UNSUPPORTED: facet outside spike subset")
+
+
+def _read_index(source_text: str) -> dict[Ref, dict[str, Any]]:
+    read_public = cast(Callable[[str], Any], read_document)
+    document = read_public(source_text)
+    validation = validate_document(document)
+    if not validation.valid or not validation.complete:
+        raise ProjectionError("UNSUPPORTED: UMF validation is invalid or incomplete")
+    # Keep generated UMF types at this public parsing boundary; no private imports.
+    data = cast(dict[str, Any], document.to_dict())
+    index: dict[Ref, dict[str, Any]] = {}
+    for module in data["modules"]:
+        for element in module["elements"]:
+            ref = (module["id"], element["id"])
+            if ref in index:
+                raise ProjectionError("AMBIGUOUS_IDENTITY: duplicate UMF reference")
+            index[ref] = element
+    return index
+
+
+def _subset(element: dict[str, Any], supported: set[str]) -> None:
+    if element.get("extensions") or set(element) - supported:
+        raise ProjectionError("UNSUPPORTED: selected meaning outside spike subset")

lintel/experimental/schema.py

@@ -0,0 +1,105 @@
+"""Dynamic Strawberry construction from a direct UMF scalar projection.
+
+The query and echo mutation are laboratory probes, not admitted UMF operations.
+They must never be mounted as a production API.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Any, NewType
+from uuid import UUID
+
+import strawberry
+from graphql import lexicographic_sort_schema, print_schema
+from strawberry.schema.config import StrawberryConfig
+
+from lintel.experimental.projection import Projection
+
+DecimalText = NewType("DecimalText", str)
+UUIDText = NewType("UUIDText", str)
+
+
+def decimal_text(value: object) -> DecimalText:
+    if not isinstance(value, str) or not re.fullmatch(
+        r"-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?", value
+    ):
+        raise ValueError("Decimal requires exact finite JSON-number text")
+    return DecimalText(value)
+
+
+def uuid_text(value: object) -> UUIDText:
+    if not isinstance(value, str) or str(UUID(value)) != value:
+        raise ValueError("UUID requires canonical lowercase hyphenated text")
+    return UUIDText(value)
+
+
+SCALARS: dict[str, Any] = {
+    "string": str,
+    "boolean": bool,
+    "decimal": DecimalText,
+    "uuid": UUIDText,
+}
+
+
+def build_probe_schema(plan: Projection, row: Mapping[str, object]) -> strawberry.Schema:
+    """No native I/O or executable imports selected by UMF content."""
+    annotations: dict[str, Any] = {}
+    input_body: dict[str, Any] = {"__annotations__": {}}
+    output_body: dict[str, Any] = {"__annotations__": annotations}
+    slots = [("field_" + str(i), field) for i, field in enumerate(plan.fields)]
+    for slot, field in slots:
+        value_type = SCALARS[field.scalar]
+        annotation = value_type | None if field.optional else value_type
+        annotations[slot] = annotation
+        input_body["__annotations__"][slot] = annotation
+        output_body[slot] = strawberry.field(name=field.name)
+        input_body[slot] = (
+            strawberry.field(name=field.name, default=strawberry.UNSET)
+            if field.optional
+            else strawberry.field(name=field.name)
+        )
+    output_type = strawberry.type(type(plan.name, (), output_body))
+    input_type = strawberry.input(type(plan.name + "Input", (), input_body))
+
+    def probe() -> Any:
+        return output_type(
+            **{slot: row.get(f.name) if f.optional else row[f.name] for slot, f in slots}
+        )
+
+    def echo(input: Any) -> PresenceProbe:
+        # Omission remains distinct from explicit null before the executor boundary.
+        return PresenceProbe(
+            omitted=any(getattr(input, slot) is strawberry.UNSET for slot, _ in slots),
+            explicit_null=any(getattr(input, slot) is None for slot, _ in slots),
+        )
+
+    probe.__annotations__["return"] = output_type
+    echo.__annotations__["input"] = input_type
+    query = strawberry.type(type("Query", (), {"probe": strawberry.field(resolver=probe)}))
+    mutation = strawberry.type(type("Mutation", (), {"echo": strawberry.mutation(resolver=echo)}))
+    return strawberry.Schema(
+        query,
+        mutation=mutation,
+        config=StrawberryConfig(auto_camel_case=False),
+        scalar_overrides={
+            DecimalText: strawberry.scalar(
+                name="Decimal", serialize=decimal_text, parse_value=decimal_text
+            ),
+            UUIDText: strawberry.scalar(name="UUID", serialize=uuid_text, parse_value=uuid_text),
+        },
+    )
+
+
+@strawberry.type
+class PresenceProbe:
+    omitted: bool
+    explicit_null: bool
+
+
+def export_sdl(schema: strawberry.Schema) -> str:
+    # Public graphql-core schema construction from public Strawberry SDL.
+    from graphql import build_schema
+
+    return print_schema(lexicographic_sort_schema(build_schema(schema.as_str()))).rstrip() + "\n"

lintel_api-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: lintel-api
+Version: 0.1.0a1
+Summary: UMF-driven GraphQL interoperability spikes (not a production runtime)
+Project-URL: Repository, https://github.com/DocumentDrivenDX/lintel
+Project-URL: Issues, https://github.com/DocumentDrivenDX/lintel/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: graphql-core==3.3.1
+Requires-Dist: strawberry-graphql==0.339.1
+Requires-Dist: umf-core==0.10.0
+Description-Content-Type: text/markdown
+
+# Lintel
+
+Dynamic GraphQL + Relay APIs from UMF, with an embeddable Python/FastAPI runtime
+and generated TypeScript operation/fragment artifacts for Batten applications.
+
+## Install the experimental alpha
+
+```sh
+pip install lintel-api==0.1.0a1
+```
+
+Import `project` from `lintel.experimental.projection` and
+`build_probe_schema` / `export_sdl` from `lintel.experimental.schema`.
+These expose the bounded S-01 scalar projection: string, boolean, exact decimal
+text and canonical UUID, with optional-field omission preserved. Supply UMF JSON
+and explicit record/field references; the example below uses the task-board model
+in the source distribution.
+
+```python
+from pathlib import Path
+from lintel.experimental.projection import project
+from lintel.experimental.schema import build_probe_schema
+
+plan = project(
+    Path("docs/helix/02-design/examples/task-board.umf.json").read_text(),
+    ("board", "Task"), "Task", {("board", "title"): "title"},
+)
+schema = build_probe_schema(plan, {"title": "Fabricated task"})
+assert schema.execute_sync("{ probe { title } }").data == {
+    "probe": {"title": "Fabricated task"}
+}
+```
+
+The alpha contains laboratory `probe` and `echo` roots. Do not mount them as a
+production API. Native execution/admission, Relay identity/pagination, TypeScript
+clients and Batten embedding are not provided by this wheel. Native qualification
+harnesses and governed specifications are included in the source archive, without
+installing PostgreSQL or its tools as library dependencies. Experimental APIs may
+change between alpha releases. Python 3.11 is the initial qualified interpreter.
+
+Lintel is a provisional name. This repository currently contains the HELIX
+specifications and a bounded [direct UMF interoperability spike](docs/helix/02-design/spikes/SPIKE-001-direct-umf.md).
+The spike reads UMF JSON through the public umf-core reader/validator and builds
+a dynamic Strawberry schema. It is not a production API service.
+
+Run `uv sync --locked --group spike --python 3.11`, then
+`uv run --locked --group spike python -m spikes.direct_umf.run`.
+[Verification and limits](docs/helix/04-build/direct-umf-spike.md) distinguish
+this proof from native execution, Relay clients and Batten embedding.
+
+Start with [the project packet](docs/helix/README.md),
+[scope and MVP](docs/helix/01-frame/prd.md), and
+[architecture](docs/helix/02-design/architecture.md).
+
+The intended family documentation location is
+[documentdrivendx.github.io/lintel](https://documentdrivendx.github.io/lintel/).
+The [source repository](https://github.com/DocumentDrivenDX/lintel) is created;
+family-catalog registration and documentation-site publication remain pending.
+
+
+The [native read spike](docs/helix/02-design/spikes/SPIKE-002-native-reads.md)
+measures pagination, declared-key batching and request consistency on disposable
+PostgreSQL 18. Run `uv sync --locked --group spike --group native-spike`, then
+`uv run --locked --group spike --group native-spike python -m spikes.native_reads.run`.
+Use both dependency groups for `python scripts/check_quality.py` on the current tree.
+[Results and gaps](docs/helix/04-build/native-read-spike.md) keep unsupported
+execution guarantees explicit; no upstream schema API is introduced.

lintel_api-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,8 @@
+lintel/__init__.py,sha256=wMUmapWR_AZgKY0svcgD-anKRrmDVn44cVdNceUyA64,106
+lintel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lintel/experimental/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lintel/experimental/projection.py,sha256=uYxe5t-oY94cgzM2IsYdSFvX90wgMDOuEqaEkY_a1iI,4556
+lintel/experimental/schema.py,sha256=bGPg67BbR8XA9MGm0KU-KhZNQq_sOCMEUpJALvU90tk,3812
+lintel_api-0.1.0a1.dist-info/METADATA,sha256=X80LTYQMDJxf_sFBoQH1C0TcMPrYGyQP1ETa240pFYM,3898
+lintel_api-0.1.0a1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+lintel_api-0.1.0a1.dist-info/RECORD,,

lintel_api-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any