metaobjects 0.9.0__tar.gz → 0.10.0__tar.gz

{metaobjects-0.9.0 → metaobjects-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaobjects
-Version: 0.9.0
+Version: 0.10.0
 Summary: Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port.
 Project-URL: Homepage, https://metaobjects.dev
 Project-URL: Repository, https://github.com/metaobjectsdev/metaobjects

{metaobjects-0.9.0 → metaobjects-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "0.9.0"
+version = "0.10.0"
 description = "Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -75,6 +75,12 @@ exclude = ["**/KNOWN_GAPS.md"]
 # falls back to walking up to the monorepo agent-context/.
 [tool.hatch.build.hooks.custom]
 
+# FR-033 — the 15 shared spec/metamodel/*.json files are COMMITTED copies under
+# src/metaobjects/spec_metamodel/ (not build-time-generated), so hatchling's default
+# package inclusion ships them in both the sdist and the wheel (read via
+# importlib.resources, AOT-safe). A byte-identity gate
+# (tests/conformance/test_spec_metamodel_embed.py) keeps the copies from drifting
+# from the repo-root spec/metamodel/ source.
 [tool.hatch.build]
 artifacts = ["src/metaobjects/agent_context/_content/**"]
 
@@ -93,4 +99,13 @@ exclude = ["tests/codegen/golden/"]
 [dependency-groups]
 dev = [
     "pytest>=9.0.3",
+    # `uv run` installs THIS group (PEP 735), not [project.optional-dependencies].
+    # The validator-parity corpus (tests/codegen/test_validation_conformance.py)
+    # imports pydantic to exercise the generated Pydantic models, so it must be here
+    # or the CI `uv run pytest` collection fails with ModuleNotFoundError.
+    "pydantic>=2",
+    # ruff is the Python codegen format pass (src/metaobjects/codegen/format.py); the
+    # cli-registry corpus runs codegen, so without ruff in the group `uv run pytest`
+    # fails at format time with "No module named ruff".
+    "ruff>=0.6",
 ]

{metaobjects-0.9.0 → metaobjects-0.10.0}/src/metaobjects/agent_context/_content/skills/metaobjects-authoring/SKILL.md

@@ -34,7 +34,7 @@ subtype — there is **no** separate `subType` body key.
 { "object.entity": { "name": "User" } }
 { "field.string": { "name": "email", "@required": true } }
 { "field.enum":   { "name": "status", "@values": ["OPEN", "CLOSED"] } }
-{ "identity.primary": { "@fields": ["id"] } }
+{ "identity.primary": { "name": "id", "@fields": ["id"] } }
 ```
 
 A complete entity in canonical JSON:
@@ -52,7 +52,7 @@ A complete entity in canonical JSON:
             { "field.long":   { "name": "id" } },
             { "field.string": { "name": "name", "@required": true, "@maxLength": 200 } },
             { "field.string": { "name": "bio",  "@maxLength": 2000 } },
-            { "identity.primary": { "@fields": ["id"], "@generation": "increment" } }
+            { "identity.primary": { "name": "id", "@fields": ["id"], "@generation": "increment" } }
           ]
         }
       }
@@ -74,7 +74,7 @@ metadata:
           - field.long:   { name: id }
           - field.string: { name: name, required: true, maxLength: 200 }
           - field.string: { name: bio, maxLength: 2000 }
-          - identity.primary: { fields: id, generation: increment }
+          - identity.primary: { name: id, fields: id, generation: increment }
 ```
 
 ## Reserved structural keys vs. attributes
@@ -206,8 +206,8 @@ reference for navigation/typing/codegen only. Referential actions
 `relationship.*` node (see Relationships below).
 
 ```json
-{ "identity.primary":   { "@fields": ["id"], "@generation": "increment" } }
-{ "identity.secondary": { "@fields": ["email"] } }
+{ "identity.primary":   { "name": "id", "@fields": ["id"], "@generation": "increment" } }
+{ "identity.secondary": { "name": "byEmail", "@fields": ["email"] } }
 { "identity.reference": { "name": "fkAuthor", "@fields": ["authorId"], "@references": "Author", "@enforce": true } }
 ```
 
@@ -251,8 +251,15 @@ each with a `@role`, exactly one `primary`.
 { "source.rdb": { "@kind": "view", "@table": "v_author", "@schema": "blog" } }
 ```
 
-A `view`-kind entity's fields carry `origin.*` children (`passthrough` /
-`aggregate` / `collection`) declaring where each value comes from.
+**An entity's PRIMARY source must be writable** (`table`) — read-only kinds are
+legal only in non-primary roles (e.g. table `primary` + view `replica` for
+read-through). A derived read model over a view/proc is an **`object.projection`**
+(FR-024): its fields `extends` entity fields (`extends: "Author.id"` — dotted
+child traversal, package only on the root segment) and/or carry `origin.*`
+children (`passthrough` / `aggregate` / `collection`) declaring assembly; its
+identity passes through via `extends` (`identity.primary: { name: id, extends:
+"Author.id" }`); it is read-only by construction and the declared field set IS
+the exposure (fail-closed).
 
 ## Abstracts + `extends` (deferred resolution) + `overlay`
 
@@ -275,7 +282,7 @@ change.
     children:
       - source.rdb: { table: authors }
       - field.string: { name: name, required: true }
-      - identity.primary: { fields: id }
+      - identity.primary: { name: id, fields: id }
 ```
 
 Resolution facts:

metaobjects-0.10.0/src/metaobjects/apidocs/__init__.py

@@ -0,0 +1,91 @@
+"""Python native SDK / API-reference docs (the ``api/python`` surface).
+
+Tier-1, idiomatic per-language reference for the generated Python SDK (Pydantic
+model / FastAPI routes / repository ``Protocol`` data-access / validation /
+extractor / render helper / payload / output-format prompt / output parser /
+filter allowlist). Accurate-by-construction: every documented symbol name comes
+from the :mod:`metaobjects.apidocs.naming` seam — the SAME seam the real
+generators delegate to — so docs can never claim a name the generators do not
+emit. Distinct from the model docs (Tier-2, neutral, TS-owned). See
+``docs/superpowers/specs/2026-06-13-cross-port-sdk-docs-conformance-design.md``.
+
+The builder / renderer symbols are exposed lazily (via :pep:`562` module
+``__getattr__``) so that a generator importing the lightweight
+:mod:`metaobjects.apidocs.naming` seam does NOT pull in the builder (which imports
+those same generators) — that would be a circular import at module-init time.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+# Path math is leaf-level (no generator imports) — safe to expose eagerly.
+from metaobjects.apidocs.paths import (
+    Layout,
+    doc_page_output_path,
+    model_cross_href,
+    package_to_path,
+    surface_cross_href,
+)
+
+if TYPE_CHECKING:  # pragma: no cover - import-time only for type checkers
+    from metaobjects.apidocs.api_model import (
+        ApiModel,
+        ApiSymbol,
+        ApiSymbolKind,
+        ApiUnit,
+        FieldShape,
+        UnitExample,
+    )
+    from metaobjects.apidocs.builder import PythonApiModelBuilder, build_api_model
+    from metaobjects.apidocs.renderer import (
+        PythonApiDocsRenderer,
+        render_agent_api,
+        render_index,
+        render_unit_page,
+    )
+
+# Lazily-resolved exports → their defining submodule.
+_LAZY: dict[str, str] = {
+    "ApiModel": "api_model",
+    "ApiSymbol": "api_model",
+    "ApiSymbolKind": "api_model",
+    "ApiUnit": "api_model",
+    "FieldShape": "api_model",
+    "UnitExample": "api_model",
+    "PythonApiModelBuilder": "builder",
+    "build_api_model": "builder",
+    "PythonApiDocsRenderer": "renderer",
+    "render_unit_page": "renderer",
+    "render_index": "renderer",
+    "render_agent_api": "renderer",
+}
+
+__all__ = [
+    "ApiModel",
+    "ApiSymbol",
+    "ApiSymbolKind",
+    "ApiUnit",
+    "FieldShape",
+    "UnitExample",
+    "PythonApiModelBuilder",
+    "build_api_model",
+    "PythonApiDocsRenderer",
+    "render_unit_page",
+    "render_index",
+    "render_agent_api",
+    "Layout",
+    "doc_page_output_path",
+    "model_cross_href",
+    "package_to_path",
+    "surface_cross_href",
+]
+
+
+def __getattr__(name: str) -> Any:
+    submodule = _LAZY.get(name)
+    if submodule is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    mod = importlib.import_module(f"{__name__}.{submodule}")
+    return getattr(mod, name)

metaobjects-0.10.0/src/metaobjects/apidocs/api_model.py

@@ -0,0 +1,111 @@
+"""The Python native SDK api-surface IR (intermediate representation).
+
+Mirrors the Java ``JavaApiModel`` IR (server/java/.../apidocs), the C#
+``CSharpApiModel``, and the TS ``api-model.ts``, idiomatic to the Python
+(Pydantic / FastAPI / ObjectManager) generated surface: Pydantic model /
+``ObjectManager`` data-access / FastAPI routes / validation / extractor /
+render helper / payload model / output-format prompt / output parser / filter
+allowlist.
+
+NAMES on every symbol come from the :mod:`metaobjects.apidocs.naming` seam (never
+re-concatenated in the builder), so what this model documents == what the real
+generators emit.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class ApiSymbolKind(str, Enum):
+    """The generated-category axis a documented symbol belongs to (Python /
+    Pydantic + FastAPI flavored)."""
+
+    #: The Pydantic v2 model class (entity) or value-object model.
+    MODEL = "model"
+    #: Data access — the consumer-implemented repository ``Protocol`` seam.
+    DATA_ACCESS = "data_access"
+    #: A FastAPI route (named ``"VERB path"``).
+    REST = "rest"
+    #: Pydantic field validation on the create/update shape.
+    VALIDATION = "validation"
+    #: The tolerant + strict extractor for a template payload.
+    EXTRACTOR = "extractor"
+    #: The typed render helper wrapping the render engine.
+    RENDER = "render"
+    #: The typed payload model bound to a template.
+    PAYLOAD = "payload"
+    #: The output-format prompt fragment.
+    PROMPT = "prompt"
+    #: The output parser (``parse_*``) back into the typed payload.
+    OUTPUT_PARSER = "output_parser"
+    #: The per-entity sort/filter allowlist.
+    FILTER = "filter"
+
+
+@dataclass(frozen=True)
+class FieldShape:
+    """A documented field: name + Python type + optionality + an optional note
+    (e.g. enum values)."""
+
+    name: str
+    type: str
+    optional: bool
+    note: str | None = None
+
+
+@dataclass(frozen=True)
+class UnitExample:
+    """A worked example for a unit (reserved for later phases; carried for
+    cross-port IR parity)."""
+
+    title: str
+    code: str
+
+
+@dataclass(frozen=True)
+class ApiSymbol:
+    """One documented symbol of the generated Python SDK surface.
+
+    :param name: the emitted Python identifier (or ``"VERB path"`` for a REST route).
+    :param kind: which generated category this symbol belongs to.
+    :param module: the import line / module path the symbol lives in.
+    :param signature: a human-readable Python signature line.
+    :param usage: a one-line "what you use this for".
+    :param returns: the symbol's return surface, or ``None``.
+    :param fields: per-field shapes for model/validation/payload symbols (may be empty).
+    """
+
+    name: str
+    kind: ApiSymbolKind
+    module: str
+    signature: str
+    usage: str
+    returns: str | None = None
+    fields: list[FieldShape] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ApiUnit:
+    """One documented unit (an entity / value object, or a template) + its symbols.
+
+    :param node: the unit's short name (the doc-page basename).
+    :param package: the unit's metadata package (e.g. ``acme::shop``).
+    :param kind: ``"entity"`` | ``"value"`` | ``"template"``.
+    :param symbols: the documented symbols, in canonical IR order.
+    :param example: an optional unit-level worked example (reserved).
+    """
+
+    node: str
+    package: str
+    kind: str
+    symbols: list[ApiSymbol]
+    example: UnitExample | None = None
+
+
+@dataclass(frozen=True)
+class ApiModel:
+    """The full per-project Python SDK api surface IR."""
+
+    project: str
+    units: list[ApiUnit]