matrx-ai 0.5.332__tar.gz → 0.5.334__tar.gz

{matrx_ai-0.5.332 → matrx_ai-0.5.334}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-ai
-Version: 0.5.332
+Version: 0.5.334
 Summary: Unified multi-provider AI client, orchestration, and tool system
 Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
 Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current
@@ -32,12 +32,12 @@ Requires-Dist: groq>=1.2.0
 Requires-Dist: httpx
 Requires-Dist: json-repair
 Requires-Dist: matrx-assignment>=0.1.21
-Requires-Dist: matrx-connect>=0.1.110
-Requires-Dist: matrx-files>=0.2.172
-Requires-Dist: matrx-graph>=0.2.170
+Requires-Dist: matrx-connect>=0.1.111
+Requires-Dist: matrx-files>=0.2.173
+Requires-Dist: matrx-graph>=0.2.171
 Requires-Dist: matrx-runtime>=0.0.104
-Requires-Dist: matrx-scraper[browser]>=0.2.218
-Requires-Dist: matrx-utils>=2.0.43
+Requires-Dist: matrx-scraper[browser]>=0.2.220
+Requires-Dist: matrx-utils>=2.0.44
 Requires-Dist: numpy>=2.0
 Requires-Dist: openai>=2.35.1
 Requires-Dist: pathspec>=1.0.0

{matrx_ai-0.5.332 → matrx_ai-0.5.334}/matrx_ai/tools/kinds/__init__.py

@@ -70,6 +70,7 @@ from matrx_ai.tools.kinds.execution import (  # noqa: E402
     ShellExecution,
 )
 from matrx_ai.tools.kinds.fact_check import FactCheckReviewSet  # noqa: E402
+from matrx_ai.tools.kinds.google import GOOGLE_TOOL_RESULT_KINDS  # noqa: E402
 from matrx_ai.tools.kinds.filesystem import (  # noqa: E402
     DirectoryCreateResult,
     DirectoryListing,
@@ -251,6 +252,12 @@ TOOL_RESULT_KINDS: dict[str, type[KindModel]] = {
     # image verification pair — ONE kind each, shared with the workflow nodes
     # web.google.reverse_image_search / image.metadata.read (no twin slugs).
     **MEDIA_FORENSICS_TOOL_RESULT_KINDS,
+    # the two Google tools (2026-09-17, google-native PLAN §5.8). ONE union kind
+    # each — google_workspace_result was a PLACEHOLDER declared beside the other
+    # agent-ops shapes and bound to nothing, so the tool it describes stamped no
+    # __kind at all; google_marketing_result is new with its tool. The twelve-
+    # action `google_read` these two replaced had no kind and no row here.
+    **GOOGLE_TOOL_RESULT_KINDS,
     # scope_system (aidream/services/scope_system/tools.py): render actions
     # reshaped from a bare string into `context` (a scalar cannot carry __kind).
     "scope_system": ScopeSystemResult,

{matrx_ai-0.5.332 → matrx_ai-0.5.334}/matrx_ai/tools/kinds/agent_ops.py

@@ -208,49 +208,6 @@ class OfficeToolResult(KindModel):
 __all__ = ["SelfPromptResult", "RulebookToolResult", "ResearchRunState", "OfficeToolResult"]
 
 
-@kind(
-    "google_workspace_result",
-    label="Google Workspace Result",
-    family="google_workspace",
-    example={"created": True, "file_id": "1AbC", "name": "Notes", "kind": "google_document", "open_in_google": "https://docs.google.com/…"},
-    # PLACEHOLDER — list_resources/create/read/append (Docs), read/write
-    # (Sheets) and prepare_email (which NEVER sends) receipts.
-    maturity="placeholder",
-)
-class GoogleWorkspaceResult(KindModel):
-    #: `list_resources`.
-    resources: list[dict] | None = None
-    count: int | None = None
-    note: str | None = None
-    #: create receipts.
-    created: bool | None = None
-    file_id: str | None = None
-    name: str | None = None
-    kind: str | None = None
-    open_in_google: str | None = None
-    #: document read/append window.
-    title: str | None = None
-    text: str | None = None
-    total_chars: int | None = None
-    showing_chars: str | None = None
-    has_more: bool | None = None
-    next_start_char: int | None = None
-    appended: bool | None = None
-    #: sheet read/write window.
-    tab: str | None = None
-    range: str | None = None
-    rows: list[list[JsonValue]] | None = None
-    row_count: int | None = None
-    sheet_size: str | None = None
-    next_range_a1: str | None = None
-    written: bool | None = None
-    #: `prepare_email` — a draft for the HUMAN send step; never sent here.
-    sent: bool | None = None
-    draft: dict | None = None
-    from_email: str | None = None
-    next_step: str | None = None
-
-
 @kind(
     "tool_result_page",
     label="Tool Result Page",

matrx_ai-0.5.334/matrx_ai/tools/kinds/google.py

@@ -0,0 +1,230 @@
+"""Kinds for the two Google agent tools — ``google_workspace`` · ``google_marketing``.
+
+ONE union kind per tool, the ``cms_*`` / ``topical_map`` precedent: an
+action-dispatched tool returns one shape whose branch-only keys are optional,
+and every branch validates against it before the result leaves the tool
+(a key the kind does not declare is a TOOL DEFECT, never an untyped
+pass-through).
+
+* ``google_workspace_result`` — Docs, Sheets, the prepared (never sent) email,
+  and the read/import halves of Calendar, Contacts and Tasks. Promoted from the
+  placeholder tier on 2026-09-17 when the tool was rebuilt to the convention
+  (``common-docs/projects/google-native/PLAN.md`` §5.8): every mutating action
+  gained ``dry_run``, so the kind now declares the PREVIEW branches too — the
+  block an append would land and where, the cells a write would replace, the
+  fields an import would mint, the field map a contact import would apply, and
+  which of a task set is already here.
+* ``google_marketing_result`` — the six read-only marketing reads. Every branch
+  carries ``source`` (persisted vs live Google), the ``bounds`` it was asked
+  for, and the truthful truncation trio, because a marketing number read
+  without its bounds is how a partial window becomes a reported total.
+
+The models live HERE, not in aidream, because ``TOOL_RESULT_KINDS`` may never
+import aidream (``scripts/check_package_boundaries.py``) and the tool
+implementations import these models to validate with.
+
+Publish: ``scripts/publish_kind_catalog.py matrx_ai.tools.kinds.google --apply``.
+"""
+
+from __future__ import annotations
+
+from matrx_graph.content_ir.model import KindModel
+from matrx_graph.content_ir.sdk import kind
+from pydantic import JsonValue
+
+# ---------------------------------------------------------------------------
+# google_workspace_result
+# ---------------------------------------------------------------------------
+
+
+@kind(
+    "google_workspace_result",
+    label="Google Workspace Result",
+    family="google_workspace",
+    example={
+        "action": "append_document",
+        "dry_run": True,
+        "file_id": "1AbC",
+        "title": "Q3 Plan",
+        "would_append": {
+            "position": "end_of_document",
+            "heading": "## 2026-09-17",
+            "text": "Three risks remain open.",
+            "after_char": 4211,
+        },
+        "note": "Nothing was written. Re-run without dry_run to append exactly this block.",
+        "open_in_google": "https://docs.google.com/document/d/1AbC",
+    },
+)
+class GoogleWorkspaceResult(KindModel):
+    #: Every result names the action that produced it (the union's own label).
+    action: str = ""
+    #: Which connected Google account answered. Present on every live read.
+    google_account: str | None = None
+    note: str | None = None
+
+    # ── list_resources: the files AI Matrx can reach + the health of the
+    # accounts behind them (what `google_read.list_capabilities` used to answer).
+    resources: list[dict] | None = None
+    count: int | None = None
+    accounts: list[dict] | None = None
+
+    # ── create receipts (Doc or Sheet).
+    created: bool | None = None
+    file_id: str | None = None
+    name: str | None = None
+    kind: str | None = None
+    open_in_google: str | None = None
+
+    # ── document read / append window.
+    title: str | None = None
+    text: str | None = None
+    total_chars: int | None = None
+    showing_chars: str | None = None
+    has_more: bool | None = None
+    next_start_char: int | None = None
+    appended: bool | None = None
+
+    # ── sheet read / write window.
+    tab: str | None = None
+    range: str | None = None
+    rows: list[list[JsonValue]] | None = None
+    row_count: int | None = None
+    sheet_size: str | None = None
+    next_range_a1: str | None = None
+    written: bool | None = None
+
+    # ── dry_run previews. `dry_run: true` means NOTHING was written; each
+    # preview is the exact change the same call without dry_run would make.
+    dry_run: bool | None = None
+    #: append_document — the block and where it lands.
+    would_append: dict | None = None
+    #: write_sheet — the cells that would be replaced and what would replace them.
+    would_write: dict | None = None
+    #: create_document / create_sheet — the file that would be created.
+    would_create: dict | None = None
+
+    # ── import_sheet_as_table.
+    #: One field per header-row column, with the column letter it came from.
+    fields: list[dict] | None = None
+    header_row: int | None = None
+    #: A step only the browser can take, named exactly. Never a fake success.
+    needs_client: dict | None = None
+
+    # ── prepare_email — a draft for the HUMAN send step; never sent here.
+    sent: bool | None = None
+    draft: dict | None = None
+    from_email: str | None = None
+    next_step: str | None = None
+
+    # ── read_calendar.
+    events: list[dict] | None = None
+    window_start: str | None = None
+    window_end: str | None = None
+
+    # ── read_contacts / import_contact.
+    contacts: list[dict] | None = None
+    #: import_contact — per Person field, where the value came from.
+    field_map: list[dict] | None = None
+    person: dict | None = None
+    imported: bool | None = None
+    matched_by: str | None = None
+
+    # ── read_tasks / import_tasks.
+    task_lists: list[dict] | None = None
+    tasks: list[dict] | None = None
+    #: import_tasks — what landed, what was already here, what was skipped.
+    imported_tasks: list[dict] | None = None
+    already_imported: list[dict] | None = None
+    skipped: list[dict] | None = None
+
+    # ── the human-in-the-loop branch. An organization can require a person to
+    # approve a write or an import before it happens (the ``hitl.google.*``
+    # knobs). When it does, the tool runs its OWN dry run, queues that exact
+    # preview in the one approval queue, and returns the preview WITH these two
+    # keys set — so the model is told, in the result rather than in prose, that
+    # nothing was written and where the change is waiting.
+    #: True when the change was PROPOSED, not made. Never present otherwise.
+    awaiting_approval: bool | None = None
+    #: The queue item: ``approval_id``, the ``mode`` it runs in, the ``knob``
+    #: that decided, whether the run was ``attended``, and who it waits with.
+    approval: dict | None = None
+
+    # ── the honesty trio every bounded read carries.
+    bounds: dict | None = None
+    truncated: bool | None = None
+    limit_note: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# google_marketing_result
+# ---------------------------------------------------------------------------
+
+
+@kind(
+    "google_marketing_result",
+    label="Google Marketing Result",
+    family="google_marketing",
+    example={
+        "action": "read_search_console",
+        "source": "persisted",
+        "site_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+        "bounds": {"start_date": "2026-08-01", "end_date": "2026-08-28", "limit": 1000},
+        "returned_count": 412,
+        "count_unit": "rows",
+        "truncated": False,
+        "completeness": "complete_within_requested_bound",
+        "limit_note": "Persisted Search Console rows are bounded by the requested limit.",
+        "data": {"rows": []},
+    },
+)
+class GoogleMarketingResult(KindModel):
+    action: str = ""
+    #: `persisted` = our own stored facts (no hidden sync); `live_google` = a
+    #: bounded call to Google made for this request. Never absent.
+    source: str = ""
+    #: Which connected Google account answered a live read.
+    google_account: str | None = None
+    site_id: str | None = None
+    channel_id: str | None = None
+
+    #: What was ASKED for — the window, the limit, the profile.
+    bounds: dict | None = None
+    returned_count: int | None = None
+    count_unit: str | None = None
+    #: True/False when the provider or our own cap says so; null when unknowable.
+    truncated: bool | None = None
+    completeness: str | None = None
+    limit_note: str | None = None
+    #: How old the numbers are, in words, when the source lags (GSC ~3 days).
+    freshness: str | None = None
+    note: str | None = None
+
+    #: The read's payload, under the shape the underlying reader returns.
+    data: JsonValue | None = None
+
+    # ── tracking_health: the plain-English verdict, the three graded checks, and
+    # what the read could not see. The check shape and the three booleans are the
+    # SAME vocabulary the stored snapshot declares (`web.tag_manager_snapshot`
+    # findings → `tag_manager_findings`, migration 0763), so this answer can be
+    # persisted verbatim rather than translated into a second set of words.
+    verdict: str | None = None
+    checks: list[dict] | None = None
+    has_ga4: bool | None = None
+    has_conversion_tag: bool | None = None
+    has_consent: bool | None = None
+    caveats: list[str] | None = None
+    containers: list[dict] | None = None
+
+
+GOOGLE_TOOL_RESULT_KINDS: dict[str, type[KindModel]] = {
+    "google_workspace": GoogleWorkspaceResult,
+    "google_marketing": GoogleMarketingResult,
+}
+
+
+__all__ = [
+    "GOOGLE_TOOL_RESULT_KINDS",
+    "GoogleMarketingResult",
+    "GoogleWorkspaceResult",
+]

{matrx_ai-0.5.332 → matrx_ai-0.5.334}/matrx_ai/tools/kinds/topical_map.py

@@ -10,7 +10,7 @@ doctrine forbids).
 EVERY key is typed: the tool validates each result against this model before
 returning it, so a database contract change that adds, drops or reshapes a key
 fails loudly as `result_kind_mismatch` instead of reaching an agent untyped.
-The shapes are the database's as of `seo_topical_map_18`:
+The shapes are the database's as of `seo_topical_map_19_page_intents`:
 
 * an associated item the caller cannot open is ABSENT from every listing (no
   entry, no count); a facet value's `ref` to such a row is `null`, the same as no
@@ -185,6 +185,103 @@ class PageMapping(KindSubModel):
     error: str | None = None
 
 
+# ── page intents (`page_intents`, `set_page_intents`) ────────────────────────
+
+
+class IntentPage(EntityRef):
+    """`seo.list_page_intents` page projection + its Search Console totals."""
+
+    site_id: str | None = None
+    clicks: int | None = None
+    impressions: int | None = None
+    #: the window the totals were summed over (the `performance_window_days` knob).
+    performance_window_days: int | None = None
+
+
+class IntentTopicRef(KindSubModel):
+    slug: str
+    name: str
+
+
+class CoveredTopic(KindSubModel):
+    """A `covers` edge: where the page sits TODAY."""
+
+    slug: str
+    name: str
+    confidence: int | None = None
+    #: mapper | human | agent — who asserted the coverage.
+    source: str | None = None
+
+
+class PageIntent(KindSubModel):
+    """The one `intent` edge of a page: where it is GOING and what happens to it."""
+
+    topic: IntentTopicRef
+    #: keep | move | merge | redirect | rewrite | delete.
+    disposition: str
+    #: proposed | accepted | done.
+    state: str | None = None
+    source: str | None = None
+    note: str | None = None
+    #: merge / redirect only: the live page or planned page it points at. Null when
+    #: the destination row is one the caller cannot open — the same as no destination.
+    into: EntityRef | None = None
+    updated_at: str | None = None
+
+
+class PageIntentRow(KindSubModel):
+    page: IntentPage
+    current_topics: list[CoveredTopic]
+    #: null when the page carries `covers` edges but no intent yet.
+    intent: PageIntent | None = None
+
+
+# ── gaps, history, planned pages (`topic_gaps`, `map_history`, `create_planned_page`) ──
+
+
+class TopicGap(KindSubModel):
+    """A topic of the map carrying no live page and no planned page."""
+
+    slug: str
+    name: str
+    status: str
+    depth: int
+    keyword_count: int
+
+
+class MapHistoryRow(KindSubModel):
+    """A topic the map no longer shows — rejected or retired — and who changed it.
+
+    `changed_at` / `changed_by` come from `history.row_versions`, so they are the
+    platform's record of the change, not a column a writer could set."""
+
+    slug: str
+    name: str
+    status: str
+    description: str | None = None
+    parent_slug: str | None = None
+    version: int | None = None
+    attachments: Attachments | None = None
+    changed_at: str | None = None
+    changed_by: str | None = None
+    #: user | agent | code — the actor tier the change was made under.
+    changed_by_tier: str | None = None
+
+
+class PlannedPage(KindSubModel):
+    """The `plan.node` `create_planned_page` had the content plan create. `slug` and
+    `route` are the plan's own derivations, never ours."""
+
+    id: str | None = None
+    site_id: str | None = None
+    label: str | None = None
+    slug: str | None = None
+    route: str | None = None
+    node_type: str | None = None
+    page_type: str | None = None
+    status: str | None = None
+
+
 # ── graph ────────────────────────────────────────────────────────────────────
 
 
@@ -359,6 +456,32 @@ class TopicalMapResult(KindModel):
     mapped: int | None = None
     failed: int | None = None
 
+    # page intents
+    #: `page_intents`: one row per page carrying an intent OR a `covers` edge.
+    #: Each listing keeps its OWN key — three shapes under one `items` would make an
+    #: agent guess which one it is holding, and would widen a published kind's field.
+    items: list[PageIntentRow] | None = None
+    #: `page_intents`: the unpaged count, and the window actually applied.
+    total: int | None = None
+    limit: int | None = None
+    offset: int | None = None
+    performance_window_days: int | None = None
+    #: `page_intents`: extra `intent` edges beyond the one per page that should exist —
+    #: nonzero is a data defect, never hidden.
+    duplicate_intents: int | None = None
+    #: `set_page_intents`: how many intents were written (`failed` counts the rest).
+    set: int | None = None
+
+    # proposals and planned pages
+    #: `reject_topics`: the proposals moved to `status = 'rejected'` — kept, never lost.
+    rejected: list[RemovedTopic] | None = None
+    #: `create_planned_page`: the node the content plan created (or would create).
+    node: PlannedPage | None = None
+    #: `topic_gaps`: topics with no live page and no planned page.
+    gaps: list[TopicGap] | None = None
+    #: `map_history`: topics the map no longer shows, newest change first.
+    history: list[MapHistoryRow] | None = None
+
 
 TopicNode.model_rebuild()
 

{matrx_ai-0.5.332 → matrx_ai-0.5.334}/matrx_ai/tools/kinds/workflow_tools.py

@@ -134,6 +134,19 @@ class WorkflowAuthorResult(KindModel):
     #: folded into the prose hint.
     warnings: list[dict] | None = None
     hint: str | None = None
+    #: The saved row's fresh concurrency token (ISO-8601), so a client that
+    #: already holds the row can adopt it without a second read.
+    updated_at: str | None = None
+    #: update/patch only — the RECEIPT of the write: the ids of the steps and
+    #: connections it added, changed or removed (``nodes_added`` /
+    #: ``nodes_updated`` / ``nodes_removed`` / ``edges_added`` /
+    #: ``edges_updated`` / ``edges_removed``), each list capped, with
+    #: ``truncated`` naming any list that was cut. The Studio reveals exactly
+    #: these on the canvas instead of diffing a re-read (Conductor mode,
+    #: 2026-09-17). Added to the KIND the same day it was added to the tool:
+    #: an undeclared key fails ``extra="forbid"`` and the whole result loses
+    #: its ``__kind`` stamp.
+    changed: dict[str, list[str]] | None = None
 
 
 @kind(

{matrx_ai-0.5.332 → matrx_ai-0.5.334}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-ai"
-version = "0.5.332"
+version = "0.5.334"
 description = "Unified multi-provider AI client, orchestration, and tool system"
 readme = "README.md"
 license = { text = "MIT" }
@@ -65,15 +65,15 @@ dependencies = [
     "asyncpg>=0.31.0",
     # --- Matrx ecosystem ---
     # media/media_persistence.py imports VisibilityLiteral, first exported by 2.0.7.
-    "matrx-utils>=2.0.43",
-    "matrx-files>=0.2.172",
+    "matrx-utils>=2.0.44",
+    "matrx-files>=0.2.173",
     # 0.1.26+ exports the Masterwork* event models used here (renamed 2026-08-17;
     # the next matrx-connect release is the first tag that exports the new names).
-    "matrx-connect>=0.1.110",
+    "matrx-connect>=0.1.111",
     # actions.register_node is imported at module scope and first shipped in 0.1.22.
-    "matrx-graph>=0.2.170",
+    "matrx-graph>=0.2.171",
     # tools.implementations imports the browser implementation eagerly.
-    "matrx-scraper[browser]>=0.2.218",
+    "matrx-scraper[browser]>=0.2.220",
     # matrx-runtime (the Request Management Layer): the conversation executor
     # (orchestrator/conversation_runtime.py) is a CONSUMER of its ExecutionEngine —
     # one conversation = one global_execution. ai → runtime is the acyclic edge.