metaobjects 0.9.0__py3-none-any.whl

metaobjects/meta/persistence/source/source_constants.py

@@ -0,0 +1,115 @@
+"""Source subtype vocabulary (colocated).
+
+Source v2 (ADR-0007): paradigm subtype ``rdb`` with @table/@kind/@role/@schema attrs.
+Read-only-ness is derived from @kind (view/materializedView/storedProc/tableFunction
+are read-only; table — the default — is writable). Multiple sources per object are
+allowed (write-through CQRS) but exactly one must have role == "primary".
+
+FR-016 / ADR-0018 — per-kind physical-name aliases. The source's logical name is the
+bare structural ``name`` field every MetaData node carries (NOT an @-attr; ``@name``
+would collide with ``ERR_RESERVED_ATTR``). The physical SQL name is one of the
+kind-aware aliases (@table / @view / @materializedView / @proc / @function), all
+filling the same internal slot. See :data:`PHYSICAL_NAME_ATTR_BY_KIND` and
+:meth:`MetaSource.physical_name` for the four-step resolution rule.
+"""
+from ....shared.base_types import SUBTYPE_BASE
+
+# --- Source v2 paradigm subtype --------------------------------------------
+SOURCE_SUBTYPE_RDB = "rdb"
+
+SOURCE_SUBTYPES = (SUBTYPE_BASE, SOURCE_SUBTYPE_RDB)
+
+# --- Per-kind physical-name aliases (FR-016 / ADR-0018) --------------------
+# One canonical attr key per rdb @kind. The single internal physical-name "slot"
+# on the source is filled by whichever alias matches @kind; the canonical
+# serializer emits the kind-matching alias regardless of which spelling was on
+# input.
+#: Physical SQL table name. Canonical attr for ``@kind: "table"`` (default).
+SOURCE_ATTR_TABLE = "table"
+#: Physical SQL view name. Canonical attr for ``@kind: "view"``.
+SOURCE_ATTR_VIEW = "view"
+#: Physical SQL materialized-view name. Canonical attr for ``@kind: "materializedView"``.
+SOURCE_ATTR_MATERIALIZED_VIEW = "materializedView"
+#: Physical SQL stored-procedure name. Canonical attr for ``@kind: "storedProc"``.
+SOURCE_ATTR_PROC = "proc"
+#: Physical SQL table-function name. Canonical attr for ``@kind: "tableFunction"``.
+SOURCE_ATTR_FUNCTION = "function"
+
+# --- Source attrs ----------------------------------------------------------
+SOURCE_ATTR_KIND = "kind"
+SOURCE_ATTR_ROLE = "role"
+SOURCE_ATTR_SCHEMA = "schema"
+# @parameterRef — name/FQN of an object.value describing the input shape of a
+# stored-proc / table-function source. Cross-port (FR-015). Mirrors TS
+# SOURCE_ATTR_PARAMETER_REF.
+SOURCE_ATTR_PARAMETER_REF = "parameterRef"
+
+# --- @kind values + read-only derivation ------------------------------------
+SOURCE_KIND_TABLE = "table"
+SOURCE_KIND_VIEW = "view"
+SOURCE_KIND_MATERIALIZED_VIEW = "materializedView"
+SOURCE_KIND_STORED_PROC = "storedProc"
+SOURCE_KIND_TABLE_FUNCTION = "tableFunction"
+
+SOURCE_RDB_KINDS = (
+    SOURCE_KIND_TABLE,
+    SOURCE_KIND_VIEW,
+    SOURCE_KIND_MATERIALIZED_VIEW,
+    SOURCE_KIND_STORED_PROC,
+    SOURCE_KIND_TABLE_FUNCTION,
+)
+
+# @kind default when omitted (writable table).
+DEFAULT_SOURCE_KIND = SOURCE_KIND_TABLE
+
+# Kinds whose source is read-only (codegen emits read-only model/queries/routes).
+SOURCE_READ_ONLY_KINDS = frozenset({
+    SOURCE_KIND_VIEW,
+    SOURCE_KIND_MATERIALIZED_VIEW,
+    SOURCE_KIND_STORED_PROC,
+    SOURCE_KIND_TABLE_FUNCTION,
+})
+
+# --- FR-016 / ADR-0018 — @kind → canonical physical-name attr key ----------
+#: Drives the four-step physical-name resolution rule on :class:`MetaSource`
+#: and the canonical-serializer per-kind rewrite. The single internal
+#: physical-name "slot" on a source is the value of whichever alias matches
+#: the source's @kind.
+PHYSICAL_NAME_ATTR_BY_KIND: dict[str, str] = {
+    SOURCE_KIND_TABLE:             SOURCE_ATTR_TABLE,
+    SOURCE_KIND_VIEW:              SOURCE_ATTR_VIEW,
+    SOURCE_KIND_MATERIALIZED_VIEW: SOURCE_ATTR_MATERIALIZED_VIEW,
+    SOURCE_KIND_STORED_PROC:       SOURCE_ATTR_PROC,
+    SOURCE_KIND_TABLE_FUNCTION:    SOURCE_ATTR_FUNCTION,
+}
+
+#: Every kind-aware physical-name alias key, ordered for deterministic
+#: iteration (matches the SOURCE_RDB_KINDS order). Used by the validation pass
+#: and by :meth:`MetaSource.physical_name`.
+ALL_PHYSICAL_NAME_ALIASES: tuple[str, ...] = (
+    SOURCE_ATTR_TABLE,
+    SOURCE_ATTR_VIEW,
+    SOURCE_ATTR_MATERIALIZED_VIEW,
+    SOURCE_ATTR_PROC,
+    SOURCE_ATTR_FUNCTION,
+)
+
+# --- @role values + default -------------------------------------------------
+SOURCE_ROLE_PRIMARY = "primary"
+SOURCE_ROLE_REPLICA = "replica"
+SOURCE_ROLE_INDEX = "index"
+SOURCE_ROLE_CACHE = "cache"
+SOURCE_ROLE_PUBLISH = "publish"
+SOURCE_ROLE_MIRROR = "mirror"
+
+SOURCE_ROLES = (
+    SOURCE_ROLE_PRIMARY,
+    SOURCE_ROLE_REPLICA,
+    SOURCE_ROLE_INDEX,
+    SOURCE_ROLE_CACHE,
+    SOURCE_ROLE_PUBLISH,
+    SOURCE_ROLE_MIRROR,
+)
+
+# @role default when omitted (system of record).
+DEFAULT_SOURCE_ROLE = SOURCE_ROLE_PRIMARY

metaobjects/meta/presentation/layout/layout_constants.py

@@ -0,0 +1,13 @@
+"""Layout subtype vocabulary (colocated)."""
+from ....shared.base_types import SUBTYPE_BASE
+
+LAYOUT_SUBTYPE_DATA_GRID = "dataGrid"
+LAYOUT_SUBTYPES = (SUBTYPE_BASE, LAYOUT_SUBTYPE_DATA_GRID)
+
+# layout.dataGrid attrs
+LAYOUT_ATTR_COLUMNS = "columns"
+LAYOUT_ATTR_DEFAULT_SORT_FIELD = "defaultSortField"
+LAYOUT_ATTR_DEFAULT_SORT_ORDER = "defaultSortOrder"
+LAYOUT_ATTR_PAGE_SIZE = "pageSize"
+LAYOUT_ATTR_FILTERABLE = "filterable"
+LAYOUT_ATTR_FILTER = "filter"

metaobjects/meta/presentation/layout/meta_layout.py

@@ -0,0 +1,8 @@
+"""MetaLayout — layout.dataGrid / etc. node."""
+from __future__ import annotations
+
+from ...meta_data import MetaData
+
+
+class MetaLayout(MetaData):
+    pass

metaobjects/meta/presentation/view/meta_view.py

@@ -0,0 +1,8 @@
+"""MetaView — view.currency / view.text / etc. node."""
+from __future__ import annotations
+
+from ...meta_data import MetaData
+
+
+class MetaView(MetaData):
+    pass

metaobjects/meta/presentation/view/view_constants.py

@@ -0,0 +1,22 @@
+"""View subtype vocabulary (colocated).
+
+The view's subType IS the UI control type.
+
+SP-G Phase1 Unit3 (B-2): the 11 generic web-presentation control kinds
+(text/textarea/date/month/hotlink/dropdown/radio/checkbox/number/password/
+hidden/web) are TS-web-presentation-only — they have NO backend / codegen /
+render consumer in Python, so they are dead vocab here and were DEREGISTERED.
+They remain registered in TypeScript (the web client + TS form codegen require
+them for authoring). Only ``base`` + ``currency`` (the cross-port currency
+``@locale`` wire contract) are registered cross-port.
+"""
+from ....shared.base_types import SUBTYPE_BASE
+
+VIEW_SUBTYPE_CURRENCY = "currency"
+VIEW_SUBTYPES = (
+    SUBTYPE_BASE,
+    VIEW_SUBTYPE_CURRENCY,
+)
+
+# view.currency attrs — @locale (BCP 47). Only on view.currency; defaults to "en-US".
+VIEW_ATTR_LOCALE = "locale"

metaobjects/meta/template/meta_template.py

@@ -0,0 +1,46 @@
+"""MetaTemplate — template.* metatype (FR-004).
+
+Cross-port parity with Java's `MetaTemplate` / `PromptTemplate` / `OutputTemplate`
+and C#'s `MetaObjects.Render` template tier.
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ..meta_data import MetaData
+from . import template_constants as tc
+
+
+class MetaTemplate(MetaData):
+    """Concrete container for `template.prompt` / `template.output`.
+
+    Own-only accessors — read each attr off the node itself, never the super
+    chain (the loader's effective-attr walk is for codegen, not validation).
+    """
+
+    def payload_ref(self) -> str | None:
+        v = self.attr(tc.TEMPLATE_ATTR_PAYLOAD_REF)
+        return v if isinstance(v, str) and v else None
+
+    def text_ref(self) -> str | None:
+        v = self.attr(tc.TEMPLATE_ATTR_TEXT_REF)
+        return v if isinstance(v, str) and v else None
+
+    def response_ref(self) -> str | None:
+        v = self.attr(tc.TEMPLATE_ATTR_RESPONSE_REF)
+        return v if isinstance(v, str) and v else None
+
+    def format_(self) -> str:
+        v = self.attr(tc.TEMPLATE_ATTR_FORMAT)
+        return v if isinstance(v, str) and v else tc.TEMPLATE_FORMAT_DEFAULT
+
+    def required_slots(self) -> Sequence[str] | None:
+        v = self.attr(tc.TEMPLATE_ATTR_REQUIRED_SLOTS)
+        if isinstance(v, str):
+            return tuple(s.strip() for s in v.split(",") if s.strip())
+        if isinstance(v, (list, tuple)):
+            return tuple(str(x) for x in v)
+        return None
+
+    def is_prompt(self) -> bool:
+        return self.sub_type == tc.TEMPLATE_SUBTYPE_PROMPT

metaobjects/meta/template/template_constants.py

@@ -0,0 +1,112 @@
+"""Template subtype vocabulary (FR-004 cross-language prompt construction)."""
+from ...shared.base_types import SUBTYPE_BASE
+
+TEMPLATE_SUBTYPE_PROMPT = "prompt"
+TEMPLATE_SUBTYPE_OUTPUT = "output"
+# template.toolcall — ADR-0011: LLM tool-call envelope (no renderable body —
+# the body IS the structured output schema resolved via @payloadRef).
+TEMPLATE_SUBTYPE_TOOLCALL = "toolcall"
+TEMPLATE_SUBTYPES = (
+    SUBTYPE_BASE,
+    TEMPLATE_SUBTYPE_PROMPT,
+    TEMPLATE_SUBTYPE_OUTPUT,
+    TEMPLATE_SUBTYPE_TOOLCALL,
+)
+
+# Shared attrs across template.prompt and template.output (NOT inherited by
+# template.toolcall — see ADR-0011).
+TEMPLATE_ATTR_PAYLOAD_REF = "payloadRef"
+TEMPLATE_ATTR_TEXT_REF = "textRef"
+TEMPLATE_ATTR_FORMAT = "format"
+TEMPLATE_ATTR_MAX_CHARS = "maxChars"
+TEMPLATE_ATTR_OWNER = "owner"
+TEMPLATE_ATTR_SINCE = "since"
+TEMPLATE_ATTR_REQUIRED_TAGS = "requiredTags"
+
+# --- @kind + email part-refs (template.output only) ---
+#
+# A template.output is either a plain document (renders @textRef in @format ->
+# one string) or an email (renders subject + html + optional text -> a
+# structured EmailDocument). @kind is a closed enum; the email part-refs are
+# 2-layer logical (group/source) textRefs resolved by a provider at render time.
+# Cross-field rules live in validation_passes._validate_templates:
+#   - @kind="email"            -> require @subjectRef AND @htmlBodyRef (textRef unused; @textBodyRef optional)
+#   - @kind="document"/absent  -> require @textRef
+# Must match TS / Java exactly (Tier-1 invariant).
+TEMPLATE_ATTR_KIND = "kind"
+TEMPLATE_KIND_DOCUMENT = "document"
+TEMPLATE_KIND_EMAIL = "email"
+TEMPLATE_KIND_DEFAULT = TEMPLATE_KIND_DOCUMENT
+ALLOWED_KINDS = (
+    TEMPLATE_KIND_DOCUMENT,
+    TEMPLATE_KIND_EMAIL,
+)
+
+TEMPLATE_ATTR_SUBJECT_REF = "subjectRef"
+TEMPLATE_ATTR_HTML_BODY_REF = "htmlBodyRef"
+TEMPLATE_ATTR_TEXT_BODY_REF = "textBodyRef"
+
+# Prompt-overlay attrs (template.prompt only).
+TEMPLATE_ATTR_MAX_TOKENS = "maxTokens"
+TEMPLATE_ATTR_REQUIRED_SLOTS = "requiredSlots"
+TEMPLATE_ATTR_MODEL = "model"
+# @responseRef — peer of @payloadRef on template.prompt ONLY (NOT shared, NOT on
+# template.output): names the typed VO an LLM RESPONSE is extracted into, driving
+# the derived voResponse jsonb trace column (AI LLM-call trace persistence).
+# Cross-port vocabulary (registered in all five ports).
+TEMPLATE_ATTR_RESPONSE_REF = "responseRef"
+
+# Toolcall-specific attrs (template.toolcall only — see ADR-0011).
+# Vendor-agnostic in core; vendor wire details (retry semantics, fallback
+# shapes, parallel invocation, cache hints) added by consumer providers via
+# registry.extend("template", "toolcall", attributes=[...]).
+#
+# @description is intentionally NOT declared here — it's already a documentation
+# common attr added to every type by the doc provider. Tool descriptions
+# surfaced to the LLM read the same @description common attr.
+#
+# @textRef is intentionally NOT required — a tool-call has no renderable text
+# body. The body IS the structured output schema resolved via @payloadRef.
+TEMPLATE_ATTR_TOOL_NAME = "toolName"
+
+# Closed-set values for @format. Cross-port invariant.
+TEMPLATE_FORMAT_TEXT = "text"
+TEMPLATE_FORMAT_HTML = "html"
+TEMPLATE_FORMAT_XML = "xml"
+TEMPLATE_FORMAT_CSV = "csv"
+TEMPLATE_FORMAT_JSON = "json"
+TEMPLATE_FORMAT_MARKDOWN = "markdown"
+TEMPLATE_FORMAT_SPREADSHEET = "spreadsheet"
+ALLOWED_FORMATS = (
+    TEMPLATE_FORMAT_TEXT,
+    TEMPLATE_FORMAT_HTML,
+    TEMPLATE_FORMAT_XML,
+    TEMPLATE_FORMAT_CSV,
+    TEMPLATE_FORMAT_JSON,
+    TEMPLATE_FORMAT_MARKDOWN,
+    TEMPLATE_FORMAT_SPREADSHEET,
+)
+TEMPLATE_FORMAT_DEFAULT = TEMPLATE_FORMAT_TEXT
+
+# FR-010 artifact-1: output-format prompt presentation style (template.output only).
+# Closed enum, enforced via allowed_values exactly like @format. Default "guide".
+# Guidance is NEVER carried in comments. Set project-wide via an abstract template
+# base + extends, with a render-time PromptOverrides.style on top.
+TEMPLATE_ATTR_PROMPT_STYLE = "promptStyle"
+PROMPT_STYLE_GUIDE = "guide"
+PROMPT_STYLE_INLINE = "inline"
+PROMPT_STYLE_EXAMPLE_ONLY = "exampleOnly"
+PROMPT_STYLE_DEFAULT = PROMPT_STYLE_GUIDE
+PROMPT_STYLES = (
+    PROMPT_STYLE_GUIDE,
+    PROMPT_STYLE_INLINE,
+    PROMPT_STYLE_EXAMPLE_ONLY,
+)
+
+# @xmlText — a FIELD-level marker (boolean) for the tolerant extract engine: this field
+# receives its element's TEXT CONTENT when a template.output response is parsed from XML
+# (JAXB @XmlValue / Jackson @JacksonXmlText / .NET [XmlText]). Registered on field.* by
+# template_provider (the prompt/output domain owns this extract concern — NOT a core field
+# property). No effect for @format: json. Mirrors Java TemplateConstants.ATTR_XML_TEXT,
+# TS FIELD_ATTR_XML_TEXT, and C# TemplateConstants.ATTR_XML_TEXT.
+TEMPLATE_ATTR_XML_TEXT = "xmlText"

metaobjects/meta/template/template_provider.py

@@ -0,0 +1,43 @@
+"""template_provider — the template/output (serialization) MetaDataTypeProvider
+(cross-port ``metaobjects-template``).
+
+Registers the ``@xmlText`` field marker (XML text-content extraction) by EXTENDING the
+core-registered field types via :meth:`TypeRegistry.extend`. ``@xmlText`` is an
+output/extract concern, NOT a core field property, so it lives HERE in the prompt/output
+domain — mirroring Java's ``TemplateTypesMetaDataProvider`` field extension, TS's
+``templateProvider``, and C#'s ``TemplateTypesProvider``, and following the same pattern
+as ``db_provider``.
+"""
+from __future__ import annotations
+
+from ...provider import Provider
+from ...registry import AttrSchema, TypeRegistry
+from ...shared.base_types import TYPE_FIELD
+from ..core.attr.attr_constants import ATTR_SUBTYPE_BOOLEAN
+from ..core.field import field_constants as fc
+from .template_constants import TEMPLATE_ATTR_XML_TEXT
+
+# Every field subtype @xmlText applies to: the shared FIELD_SUBTYPES tuple (which
+# deliberately excludes ``enum`` — registered separately in core_types) PLUS ``field.enum``.
+# Mirrors the TS templateProvider's FIELD_SUBTYPES loop.
+_XML_TEXT_FIELD_SUBTYPES: tuple[str, ...] = (*fc.FIELD_SUBTYPES, fc.FIELD_SUBTYPE_ENUM)
+
+# @xmlText — when true, the field receives its element's XML text content during tolerant
+# extract instead of a same-named child. On every field subtype. No effect for JSON.
+_XML_TEXT_SCHEMA = AttrSchema(
+    name=TEMPLATE_ATTR_XML_TEXT, value_type=ATTR_SUBTYPE_BOOLEAN, required=False
+)
+
+
+def _register(registry: TypeRegistry) -> None:
+    for sub_type in _XML_TEXT_FIELD_SUBTYPES:
+        registry.extend(TYPE_FIELD, sub_type, attributes=[_XML_TEXT_SCHEMA])
+
+
+def _make_template_provider() -> Provider:
+    p = Provider("metaobjects-template", dependencies=("metaobjects-core-types",))
+    p.on_register(_register)
+    return p
+
+
+template_provider = _make_template_provider()