mindgraph-sdk 0.7.0__tar.gz → 0.9.0__tar.gz

mindgraph_sdk-0.9.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install (with dev deps)
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check mindgraph/
+
+      # Offline contract tests only. The live prod-mutating E2E
+      # (tests/test_integration.py) SKIPS here because MINDGRAPH_E2E is unset,
+      # so no API key / network is required.
+      - name: Test (offline)
+        run: pytest -q

mindgraph_sdk-0.9.0/.github/workflows/e2e.yml

@@ -0,0 +1,33 @@
+name: Live E2E (manual)
+
+# Manual-only. This runs the LIVE, PROD-MUTATING integration suite
+# (tests/test_integration.py): it creates/updates/tombstones real nodes in the
+# org the key belongs to. NEVER point MINDGRAPH_E2E_API_KEY at a customer org —
+# use a DEDICATED TEST ORG key. Set it in repo secrets as MINDGRAPH_E2E_API_KEY.
+on:
+  workflow_dispatch:
+    inputs:
+      base_url:
+        description: 'API base URL to target (test org)'
+        required: false
+        default: 'https://api.mindgraph.cloud'
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install (with dev deps)
+        run: pip install -e ".[dev]"
+
+      - name: Live integration tests (mutates the test org)
+        env:
+          MINDGRAPH_E2E: '1'
+          API_KEY: ${{ secrets.MINDGRAPH_E2E_API_KEY }}
+          BASE_URL: ${{ github.event.inputs.base_url }}
+        run: pytest tests/test_integration.py -v

mindgraph_sdk-0.9.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Verify tag matches package version
+        if: github.event_name == 'push'
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION="$(python3 -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")"
+          echo "Tag version:     $TAG_VERSION"
+          echo "Package version: $PKG_VERSION"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag ($TAG_VERSION) does not match pyproject.toml version ($PKG_VERSION). Aborting publish."
+            exit 1
+          fi
+
+      - run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check mindgraph/
+
+      - name: Test
+        run: pytest
+
+      - run: pip install build
+      - run: python -m build
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

{mindgraph_sdk-0.7.0 → mindgraph_sdk-0.9.0}/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.9.0 (2026-06-29)
+
+### Added
+
+- `ingest_document()` gains optional `page_offsets`, `page_count`, `mime_type`, and
+  `force_reingest`. `page_offsets` entries are `{"page", "char_start"}` where
+  `char_start` is a UTF-8 **byte** offset into `content`. Identical content reuses the
+  existing Document (response `deduplicated`). Server ≥ 1.5.0.
+- `retrieve_context()` responses: Claim/graph nodes may carry `source_chunks`
+  (citation provenance: chunk offsets, page range, matched quote, anchor selector)
+  and `believed_by` (per-agent assertion stance: `agent_uid`, `agent_label`,
+  `confidence`). Documented in the method docstring.
+- `backfill_anchors()` — start the `/backfill/anchors` job (populate
+  `ExtractedFrom.location` selectors for pre-existing edges).
+
+## 0.8.0 (2026-06-17)
+
+### Added
+
+- `list_ontology_tools()` — the generated read-tool manifest
+  (`GET /v1/ontology/tools`): per active object type, descriptors for
+  `search_<objs>` / `get_<obj>` / `summarize_<obj>` that an MCP server (or your
+  own agent loop) renders into tools. `summarize_<obj>` returns the object —
+  whether mapped from a connected SQL database or extracted from documents —
+  plus its cognitive context. Parity with the TypeScript SDK.
+- `backing` kwarg on ontology object-type creation — bind a type to an external
+  SQL source (Layer 7 semantic contract). Connection management itself stays in
+  the dashboard.
+
 ## 0.7.0 (2026-06-14)
 
 ### Added

mindgraph_sdk-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Shuruheel Ahamed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{mindgraph_sdk-0.7.0 → mindgraph_sdk-0.9.0}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: mindgraph-sdk
-Version: 0.7.0
+Version: 0.9.0
 Summary: Python client for the MindGraph Cloud API
 License-Expression: MIT
+License-File: LICENSE
 Keywords: agent,ai,cognitive,knowledge-graph,mindgraph
 Requires-Python: >=3.9
 Requires-Dist: httpx>=0.25
@@ -142,6 +143,27 @@ job = graph.run_synthesis(project["uid"])
 status = graph.get_job(job["job_id"])
 ```
 
+### Operational Ontology (Layer 7)
+
+Define typed domain objects (Customer, Order, Contract…) as a semantic contract and either **bind them to a SQL database** or extract them from documents — fused onto one object. Connecting a database (credentials/sync) is done in the dashboard; the SDK proposes/reviews schemas, queries, and lists the generated agent read tools.
+
+| Method | Description |
+|--------|-------------|
+| `propose_ontology_schema(...)` | Draft a schema from a description (+ optional sample docs); returns `{"schema_id", "job_id"}` |
+| `activate_ontology_schema(id)` / `get_ontology_schema(id)` / `list_ontology_schemas()` | Schema lifecycle |
+| `list_ontology_proposals(...)` / `approve_ontology_proposal(id)` / `reject_ontology_proposal(id)` | Review extracted-object proposals |
+| `query_ontology(query=..., schema_id=...)` | Typed retrieval with the cognitive overlay fused in |
+| `list_ontology_tools()` | The generated read-tool manifest (`search_/get_/summarize_<obj>`) the MCP server renders |
+
+```python
+res = graph.propose_ontology_schema(description="Clients, orders, contracts.")
+graph.activate_ontology_schema(res["schema_id"])
+tools = graph.list_ontology_tools()
+ctx = graph.query_ontology(query="Which customers are a churn risk?", schema_id=res["schema_id"])
+```
+
+See the [Operational Ontology](https://mindgraph.cloud/docs/ontology) and [Connect a database](https://mindgraph.cloud/docs/connect) docs.
+
 ### CRUD
 
 | Method | Description |

{mindgraph_sdk-0.7.0 → mindgraph_sdk-0.9.0}/README.md

@@ -128,6 +128,27 @@ job = graph.run_synthesis(project["uid"])
 status = graph.get_job(job["job_id"])
 ```
 
+### Operational Ontology (Layer 7)
+
+Define typed domain objects (Customer, Order, Contract…) as a semantic contract and either **bind them to a SQL database** or extract them from documents — fused onto one object. Connecting a database (credentials/sync) is done in the dashboard; the SDK proposes/reviews schemas, queries, and lists the generated agent read tools.
+
+| Method | Description |
+|--------|-------------|
+| `propose_ontology_schema(...)` | Draft a schema from a description (+ optional sample docs); returns `{"schema_id", "job_id"}` |
+| `activate_ontology_schema(id)` / `get_ontology_schema(id)` / `list_ontology_schemas()` | Schema lifecycle |
+| `list_ontology_proposals(...)` / `approve_ontology_proposal(id)` / `reject_ontology_proposal(id)` | Review extracted-object proposals |
+| `query_ontology(query=..., schema_id=...)` | Typed retrieval with the cognitive overlay fused in |
+| `list_ontology_tools()` | The generated read-tool manifest (`search_/get_/summarize_<obj>`) the MCP server renders |
+
+```python
+res = graph.propose_ontology_schema(description="Clients, orders, contracts.")
+graph.activate_ontology_schema(res["schema_id"])
+tools = graph.list_ontology_tools()
+ctx = graph.query_ontology(query="Which customers are a churn risk?", schema_id=res["schema_id"])
+```
+
+See the [Operational Ontology](https://mindgraph.cloud/docs/ontology) and [Connect a database](https://mindgraph.cloud/docs/connect) docs.
+
 ### CRUD
 
 | Method | Description |

{mindgraph_sdk-0.7.0 → mindgraph_sdk-0.9.0}/mindgraph/client.py

@@ -908,6 +908,10 @@ class MindGraph:
         citation_count: int | None = None,
         arxiv_id: str | None = None,
         language: str | None = None,
+        page_offsets: list[dict[str, Any]] | None = None,
+        page_count: int | None = None,
+        mime_type: str | None = None,
+        force_reingest: bool | None = None,
     ) -> dict[str, Any]:
         body: dict[str, Any] = {"content": content}
         if title:
@@ -944,6 +948,17 @@ class MindGraph:
             body["arxiv_id"] = arxiv_id
         if language:
             body["language"] = language
+        if page_offsets:
+            # Each entry is {"page": int (1-based), "char_start": int}, where
+            # char_start is a UTF-8 BYTE offset into `content` (not a codepoint
+            # count) — use len(s.encode("utf-8")), or pages drift on non-ASCII text.
+            body["page_offsets"] = page_offsets
+        if page_count is not None:
+            body["page_count"] = page_count
+        if mime_type:
+            body["mime_type"] = mime_type
+        if force_reingest is not None:
+            body["force_reingest"] = force_reingest
         return self._request("POST", "/ingest/document", body)
 
     def ingest_session(
@@ -989,6 +1004,19 @@ class MindGraph:
         Returns articles (synthesized wiki summaries), graph nodes with
         source_documents provenance, and optionally raw chunks.
 
+        Each graph node may also carry an optional ``source_chunks`` array of
+        citation-provenance spans. Each entry is a dict with keys:
+        ``chunk_uid`` (str), ``char_start``/``char_end`` (int|None, UTF-8 byte
+        offsets into the chunk), ``page_start``/``page_end`` (int|None, 1-based
+        page numbers, None if no page map), ``quote`` (str|None, the verbatim
+        source span when matched), and ``anchor`` (str|None, a JSON-encoded
+        Web-Annotation selector string).
+
+        Claim nodes may additionally carry an optional ``believed_by`` array of
+        per-agent stances. Each entry is a dict with keys: ``agent_uid`` (str),
+        ``agent_label`` (str), and ``confidence`` (float|None, the asserting
+        agent's certainty, None if unspecified).
+
         Args:
             query: Natural language search query.
             node_limit: Max graph nodes (default 10).
@@ -1020,6 +1048,13 @@ class MindGraph:
         """Backfill node_source provenance from existing ExtractedFrom edges."""
         return self._request("POST", "/backfill/node-sources", {})
 
+    def backfill_anchors(self) -> dict[str, Any]:
+        """Backfill citation anchors (source_chunks spans) for existing graphs.
+
+        Returns a background job descriptor (e.g. ``{"job_id": ...}``).
+        """
+        return self._request("POST", "/backfill/anchors", {})
+
     def list_jobs(self) -> list[dict[str, Any]]:
         return self._request("GET", "/jobs")
 
@@ -1231,7 +1266,23 @@ class MindGraph:
 
         Recognized kwargs: name (required), display_name, description, fields,
         required_fields, identity_fields, aliases, examples, extraction_hints,
-        default_confidence, review_policy.
+        default_confidence, review_policy, backing.
+
+        `backing` binds the type to an external source (the semantic-contract
+        mapping). Omit it for extracted/authored types. SQL example::
+
+            backing={
+                "kind": "sql",
+                "sources": [{
+                    "connection_ref": "conn_1",
+                    "table": "customers",
+                    "key": "id",
+                    "field_map": {"name": {"column": "full_name", "mode": "indexed"}},
+                }],
+                "primary_key": "id",
+                "title_field": "name",
+                "sync": {"mode": "incremental", "cursor_column": "updated_at"},
+            }
         """
         return self._request(
             "POST", f"/v1/ontology/schemas/{schema_id}/object-types", kwargs
@@ -1368,6 +1419,18 @@ class MindGraph:
             "POST", "/v1/ontology/proposals/batch-reject", body
         )
 
+    def list_ontology_tools(self) -> dict[str, Any]:
+        """Read-only agent tool manifest for the org's active ontology schema(s).
+
+        Returns ``{"tools": [...]}`` — per active object type, descriptors for
+        ``search_<objs>`` / ``get_<obj>`` / ``summarize_<obj>`` that an MCP
+        server (or your own agent loop) renders into tools and dispatches into
+        the ``/ontology`` read endpoints. ``summarize_<obj>`` returns the object
+        — whether mapped from a connected SQL database or extracted from
+        documents — plus its cognitive context (claims, risks, decisions).
+        """
+        return self._request("GET", "/v1/ontology/tools")
+
     # ---- Retrieval (graph server) ----
 
     def query_ontology(

{mindgraph_sdk-0.7.0 → mindgraph_sdk-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mindgraph-sdk"
-version = "0.7.0"
+version = "0.9.0"
 description = "Python client for the MindGraph Cloud API"
 readme = "README.md"
 license = "MIT"

mindgraph_sdk-0.9.0/tests/contract_fixture.py

@@ -0,0 +1,398 @@
+"""Canonical wire-contract fixture for the MindGraph Python SDK.
+
+This is the single source of truth that the offline parity test
+(``tests/test_offline.py``) checks the client against. It is derived from the
+authoritative contract in ``CLAUDE.md`` ("Cognitive Endpoint Actions" table +
+"SDK-Server Field Name Conventions"), which R6 verified matches the server.
+
+Each entry describes the *wire* request a client method must produce:
+
+    {
+        "method": "<MindGraph attribute name>",
+        "http_method": "GET" | "POST" | "PATCH" | "DELETE" | "PUT",
+        "path": "/exact/path",          # leading-slash path the client must hit
+        "path_contains": "/fragment",   # OR: a substring the path must contain
+                                        #     (for path-templated / query-string URLs)
+        "action": "<action>" | None,    # required value of JSON body["action"]
+        "required_fields": ["a", "b"],  # keys that must appear in the JSON body
+        "args": {...},                  # sample kwargs to call the method with
+        "positional": [...],            # sample positional args (optional)
+    }
+
+Action-dispatch endpoints must send their ``action`` in the JSON body and that
+action must be one of the endpoint's valid values per CLAUDE.md. Field-name
+conventions (``start_uid``/``end_uid`` for /traverse; structured monolithic
+/epistemic/argument) are asserted here too.
+"""
+
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# Valid action sets per CLAUDE.md "Cognitive Endpoint Actions (exhaustive)".
+# The offline test asserts every contract entry's action is in its endpoint set
+# and that the SDK never sends an action outside these sets.
+# ---------------------------------------------------------------------------
+
+VALID_ACTIONS: dict[str, set[str]] = {
+    "/reality/capture": {"source", "snippet", "observation"},
+    "/reality/entity": {
+        "create",
+        "alias",
+        "resolve",
+        "fuzzy_resolve",
+        "merge",
+        "relate",
+    },
+    # /epistemic/argument is MONOLITHIC — no action field.
+    "/epistemic/inquiry": {
+        "hypothesis",
+        "theory",
+        "paradigm",
+        "anomaly",
+        "assumption",
+        "question",
+        "open_question",
+    },
+    "/epistemic/structure": {
+        "concept",
+        "pattern",
+        "mechanism",
+        "model",
+        "model_evaluation",
+        "analogy",
+        "inference_chain",
+        "reasoning_strategy",
+        "sensitivity_analysis",
+        "theorem",
+        "equation",
+        "method",
+        "experiment",
+    },
+    "/intent/commitment": {"goal", "project", "milestone"},
+    "/intent/deliberation": {
+        "open_decision",
+        "add_option",
+        "add_constraint",
+        "resolve",
+        "get_open",
+    },
+    "/action/procedure": {
+        "create_flow",
+        "add_step",
+        "add_affordance",
+        "add_control",
+    },
+    "/action/risk": {"assess", "get_assessments"},
+    "/memory/session": {"open", "trace", "close", "journal"},
+    # /memory/distill is MONOLITHIC — no action field.
+    "/memory/config": {
+        "set_preference",
+        "get_preferences",
+        "set_policy",
+        "get_policies",
+    },
+    "/agent/plan": {
+        "create_task",
+        "create_plan",
+        "add_step",
+        "update_status",
+        "get_plan",
+    },
+    "/agent/governance": {
+        "create_policy",
+        "set_budget",
+        "request_approval",
+        "resolve_approval",
+        "get_pending",
+    },
+    "/agent/execution": {
+        "start",
+        "complete",
+        "fail",
+        "register_agent",
+        "get_executions",
+    },
+    # The full /retrieve action set — the drift-prone invariant from the task.
+    "/retrieve": {
+        "text",
+        "semantic",
+        "hybrid",
+        "active_goals",
+        "open_questions",
+        "weak_claims",
+        "pending_approvals",
+        "unresolved_contradictions",
+        "merge_candidates",
+        "curation_counts",
+        "preferences",
+        "layer",
+        "recent",
+    },
+    "/traverse": {"chain", "neighborhood", "path", "subgraph"},
+    "/evolve": {
+        "update",
+        "tombstone",
+        "restore",
+        "decay",
+        "history",
+        "snapshot",
+        "tombstone_edge",
+        "restore_edge",
+        "tombstone_cascade",
+    },
+}
+
+# Endpoints that are monolithic (must NOT carry an ``action`` field).
+MONOLITHIC_ENDPOINTS: set[str] = {"/epistemic/argument", "/memory/distill"}
+
+# Field-name conventions enforced by the server (SDK-Server Field Name
+# Conventions in CLAUDE.md). The offline test asserts these positively.
+FIELD_CONVENTIONS = {
+    "traverse_start_uid": "start_uid",  # NOT uid / from_uid
+    "traverse_path_end_uid": "end_uid",  # NOT to_uid
+}
+
+
+# ---------------------------------------------------------------------------
+# Per-method contract entries.
+# These cover the action-dispatch convenience/raw methods plus the field-name
+# conventions. Pure CRUD / passthrough (**kwargs) methods that don't bake in an
+# action are exercised separately or recorded in coverage_gaps.
+# ---------------------------------------------------------------------------
+
+CONTRACT: list[dict] = [
+    # ---- Reality ----
+    {
+        "method": "find_or_create_entity",
+        "http_method": "POST",
+        "path": "/reality/entity",
+        "action": "create",
+        "required_fields": ["action", "label", "props"],
+        "positional": ["Acme Corp"],
+        "args": {},
+    },
+    {
+        "method": "find_or_create_person",
+        "http_method": "POST",
+        "path": "/reality/entity",
+        "action": "create",
+        "required_fields": ["action", "label", "props"],
+        "positional": ["Ada Lovelace"],
+        "args": {},
+    },
+    {
+        "method": "find_or_create_organization",
+        "http_method": "POST",
+        "path": "/reality/entity",
+        "action": "create",
+        "required_fields": ["action", "label", "props"],
+        "positional": ["OpenAI"],
+        "args": {},
+    },
+    {
+        "method": "find_or_create_nation",
+        "http_method": "POST",
+        "path": "/reality/entity",
+        "action": "create",
+        "required_fields": ["action", "label", "props"],
+        "positional": ["France"],
+        "args": {},
+    },
+    {
+        "method": "find_or_create_event",
+        "http_method": "POST",
+        "path": "/reality/entity",
+        "action": "create",
+        "required_fields": ["action", "label", "props"],
+        "positional": ["WWDC 2026"],
+        "args": {},
+    },
+    {
+        "method": "find_or_create_place",
+        "http_method": "POST",
+        "path": "/reality/entity",
+        "action": "create",
+        "required_fields": ["action", "label", "props"],
+        "positional": ["Paris"],
+        "args": {},
+    },
+    {
+        "method": "find_or_create_concept",
+        "http_method": "POST",
+        "path": "/reality/entity",
+        "action": "create",
+        "required_fields": ["action", "label", "props"],
+        "positional": ["Entropy"],
+        "args": {},
+    },
+    {
+        "method": "add_observation",
+        "http_method": "POST",
+        "path": "/reality/capture",
+        "action": "observation",
+        "required_fields": ["action", "label", "summary"],
+        "positional": ["Obs", "the sky is blue"],
+        "args": {},
+    },
+    {
+        "method": "resolve_entity",
+        "http_method": "POST",
+        "path": "/reality/entity",
+        "action": "resolve",
+        "required_fields": ["action", "text"],
+        "positional": ["Acme"],
+        "args": {},
+    },
+    {
+        "method": "fuzzy_resolve_entity",
+        "http_method": "POST",
+        "path": "/reality/entity",
+        "action": "fuzzy_resolve",
+        "required_fields": ["action", "text", "limit"],
+        "positional": ["Acme"],
+        "args": {},
+    },
+    # ---- Epistemic ----
+    {
+        "method": "add_claim",
+        "http_method": "POST",
+        # NOTE: KNOWN R4 DIVERGENCE — Py routes add_claim to /epistemic/inquiry
+        # (hypothesis), TS routes addClaim to /epistemic/argument (Claim). The
+        # offline test records this via KNOWN_DIVERGENCES, not the action check.
+        "path": "/epistemic/inquiry",
+        "action": "hypothesis",
+        "required_fields": ["action", "label", "summary"],
+        "positional": ["Claim label", "claim content"],
+        "args": {},
+    },
+    # ---- Intent ----
+    {
+        "method": "open_decision",
+        "http_method": "POST",
+        "path": "/intent/deliberation",
+        "action": "open_decision",
+        "required_fields": ["action", "label"],
+        "positional": ["Pick a DB"],
+        "args": {},
+    },
+    {
+        "method": "add_option",
+        "http_method": "POST",
+        "path": "/intent/deliberation",
+        "action": "add_option",
+        "required_fields": ["action", "decision_uid", "label"],
+        "positional": ["dec_1", "Postgres"],
+        "args": {},
+    },
+    {
+        "method": "resolve_decision",
+        "http_method": "POST",
+        "path": "/intent/deliberation",
+        "action": "resolve",
+        "required_fields": ["action", "decision_uid", "chosen_option_uid"],
+        "positional": ["dec_1", "opt_1"],
+        "args": {},
+    },
+    # ---- Memory ----
+    {
+        "method": "journal",
+        "http_method": "POST",
+        "path": "/memory/session",
+        "action": "journal",
+        "required_fields": ["action", "label"],
+        "positional": ["A journal entry"],
+        "args": {},
+    },
+    # ---- Cross-cutting / retrieve ----
+    {
+        "method": "merge_candidates",
+        "http_method": "POST",
+        "path": "/retrieve",
+        "action": "merge_candidates",
+        "required_fields": ["action"],
+        "positional": [],
+        "args": {},
+    },
+    {
+        "method": "preferences",
+        "http_method": "POST",
+        "path": "/retrieve",
+        "action": "preferences",
+        "required_fields": ["action"],
+        "positional": [],
+        "args": {},
+    },
+    {
+        "method": "hybrid_search",
+        "http_method": "POST",
+        "path": "/retrieve",
+        "action": "hybrid",
+        "required_fields": ["action", "query"],
+        "positional": ["graph databases"],
+        "args": {},
+    },
+    # ---- Traverse (field-name conventions) ----
+    {
+        "method": "reasoning_chain",
+        "http_method": "POST",
+        "path": "/traverse",
+        "action": "chain",
+        "required_fields": ["action", "start_uid", "max_depth"],
+        "positional": ["n_1"],
+        "args": {},
+        "forbidden_fields": ["uid", "from_uid"],
+    },
+    {
+        "method": "neighborhood",
+        "http_method": "POST",
+        "path": "/traverse",
+        "action": "neighborhood",
+        "required_fields": ["action", "start_uid", "max_depth"],
+        "positional": ["n_1"],
+        "args": {},
+        "forbidden_fields": ["uid", "from_uid"],
+    },
+    # ---- Evolve shortcuts ----
+    {
+        "method": "tombstone",
+        "http_method": "POST",
+        "path": "/evolve",
+        "action": "tombstone",
+        "required_fields": ["action", "uid"],
+        "positional": ["n_1"],
+        "args": {},
+    },
+    {
+        "method": "restore",
+        "http_method": "POST",
+        "path": "/evolve",
+        "action": "restore",
+        "required_fields": ["action", "uid"],
+        "positional": ["n_1"],
+        "args": {},
+    },
+]
+
+
+# Raw passthrough (**kwargs) methods: the client forwards the body verbatim,
+# so the action is supplied by the caller. The offline test drives each with a
+# valid action and asserts the path + that the action lands in the body and is a
+# member of the endpoint's valid set.
+PASSTHROUGH: list[dict] = [
+    {"method": "capture", "path": "/reality/capture", "action": "observation"},
+    {"method": "entity", "path": "/reality/entity", "action": "create"},
+    {"method": "inquire", "path": "/epistemic/inquiry", "action": "hypothesis"},
+    {"method": "structure", "path": "/epistemic/structure", "action": "concept"},
+    {"method": "commit", "path": "/intent/commitment", "action": "goal"},
+    {"method": "deliberate", "path": "/intent/deliberation", "action": "open_decision"},
+    {"method": "procedure", "path": "/action/procedure", "action": "create_flow"},
+    {"method": "risk", "path": "/action/risk", "action": "assess"},
+    {"method": "session", "path": "/memory/session", "action": "open"},
+    {"method": "memory_config", "path": "/memory/config", "action": "set_preference"},
+    {"method": "plan", "path": "/agent/plan", "action": "create_plan"},
+    {"method": "governance", "path": "/agent/governance", "action": "create_policy"},
+    {"method": "execution", "path": "/agent/execution", "action": "start"},
+    {"method": "retrieve", "path": "/retrieve", "action": "text"},
+    {"method": "traverse", "path": "/traverse", "action": "chain"},
+    {"method": "evolve", "path": "/evolve", "action": "update"},
+]

{mindgraph_sdk-0.7.0 → mindgraph_sdk-0.9.0}/tests/test_integration.py

@@ -2,7 +2,16 @@
 Comprehensive integration tests for the MindGraph Python SDK.
 Tests every public method against the live Cloud API.
 
-Run: API_KEY=mg_live_... pytest tests/test_integration.py -v
+WARNING: this suite is a LIVE, PROD-MUTATING E2E. It creates/updates/tombstones
+real nodes in whatever org the supplied key belongs to. It is OPT-IN ONLY and
+SKIPS by default so a plain `pytest` run (CI, publish) executes only the offline
+contract tests in tests/test_offline.py.
+
+To run it you must BOTH:
+  1. set MINDGRAPH_E2E=1 (explicit opt-in acknowledging it mutates a test org), and
+  2. provide an API_KEY (or MINDGRAPH_API_KEY) for a DEDICATED TEST org.
+
+Run: MINDGRAPH_E2E=1 API_KEY=mg_live_... pytest tests/test_integration.py -v
 """
 import os
 import pytest
@@ -11,8 +20,12 @@ from mindgraph import MindGraph
 
 API_KEY = os.environ.get("API_KEY") or os.environ.get("MINDGRAPH_API_KEY", "")
 BASE_URL = os.environ.get("BASE_URL", "https://api.mindgraph.cloud")
+E2E_OPT_IN = os.environ.get("MINDGRAPH_E2E", "").lower() in ("1", "true", "yes", "on")
 
-pytestmark = pytest.mark.skipif(not API_KEY, reason="API_KEY not set")
+pytestmark = pytest.mark.skipif(
+    not (E2E_OPT_IN and API_KEY),
+    reason="live prod-mutating E2E: set MINDGRAPH_E2E=1 AND API_KEY to opt in",
+)
 
 
 @pytest.fixture(scope="module")

mindgraph_sdk-0.9.0/tests/test_offline.py

@@ -0,0 +1,416 @@
+"""Offline wire-contract parity tests for the MindGraph Python SDK.
+
+These tests hit NO network. They install an ``httpx.MockTransport`` into the
+client's underlying ``httpx.Client`` to capture the outgoing request, then
+assert the request path / HTTP method / JSON body ``action`` + required fields
+match the canonical contract in ``tests/contract_fixture.py`` (derived from
+CLAUDE.md, verified against the server by R6).
+
+Run: ``pytest tests/test_offline.py`` — no API key, no secrets, no network.
+
+KNOWN R4 DIVERGENCES (a pending owner/product decision, NOT bugs to fix here)
+are pinned in ``test_known_r4_divergences`` so they are documented and do not
+fail CI; any NEW/undocumented drift from the contract DOES fail.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+import pytest
+
+from mindgraph import MindGraph
+
+from .contract_fixture import (
+    CONTRACT,
+    FIELD_CONVENTIONS,
+    MONOLITHIC_ENDPOINTS,
+    PASSTHROUGH,
+    VALID_ACTIONS,
+)
+
+BASE_URL = "https://api.mindgraph.test"
+
+
+class Capture:
+    """Records the single request a method makes through MockTransport."""
+
+    def __init__(self) -> None:
+        self.request: httpx.Request | None = None
+
+    @property
+    def path(self) -> str:
+        assert self.request is not None, "no request was captured"
+        return self.request.url.path
+
+    @property
+    def full_path(self) -> str:
+        assert self.request is not None, "no request was captured"
+        url = self.request.url
+        return url.path + (("?" + url.query.decode()) if url.query else "")
+
+    @property
+    def method(self) -> str:
+        assert self.request is not None
+        return self.request.method
+
+    @property
+    def body(self) -> dict[str, Any]:
+        assert self.request is not None
+        content = self.request.content
+        if not content:
+            return {}
+        return json.loads(content)
+
+
+def make_client(capture: Capture, response_json: Any = None) -> MindGraph:
+    """Build a MindGraph client whose transport records and replies offline."""
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        capture.request = request
+        payload = {"uid": "n_test"} if response_json is None else response_json
+        return httpx.Response(200, json=payload)
+
+    client = MindGraph(BASE_URL, api_key="mg_test_key")
+    # Swap the real transport for an offline mock; never touches the network.
+    client._client = httpx.Client(
+        base_url=client.base_url,
+        headers={"Content-Type": "application/json"},
+        transport=httpx.MockTransport(handler),
+    )
+    return client
+
+
+# ---------------------------------------------------------------------------
+# Sanity: the fixture itself is internally consistent.
+# ---------------------------------------------------------------------------
+
+
+def test_retrieve_action_set_is_exact():
+    """The /retrieve action enum is the most drift-prone invariant."""
+    assert VALID_ACTIONS["/retrieve"] == {
+        "text",
+        "semantic",
+        "hybrid",
+        "active_goals",
+        "open_questions",
+        "weak_claims",
+        "pending_approvals",
+        "unresolved_contradictions",
+        "merge_candidates",
+        "curation_counts",
+        "preferences",
+        "layer",
+        "recent",
+    }
+
+
+def test_fixture_actions_are_valid_for_their_endpoint():
+    """Every contract entry's declared action belongs to its endpoint's set."""
+    for entry in CONTRACT:
+        action = entry["action"]
+        path = entry["path"]
+        if action is None:
+            assert path in MONOLITHIC_ENDPOINTS
+            continue
+        if path in VALID_ACTIONS:
+            assert action in VALID_ACTIONS[path], (
+                f"{entry['method']} declares action={action!r} "
+                f"not in valid set for {path}"
+            )
+
+
+# ---------------------------------------------------------------------------
+# Per-method wire parity: every CONTRACT entry.
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("entry", CONTRACT, ids=[e["method"] for e in CONTRACT])
+def test_contract_method_wire_shape(entry: dict):
+    cap = Capture()
+    client = make_client(cap)
+    method = getattr(client, entry["method"])
+
+    positional = entry.get("positional", [])
+    kwargs = entry.get("args", {})
+    method(*positional, **kwargs)
+
+    # HTTP method.
+    assert cap.method == entry["http_method"], (
+        f"{entry['method']}: expected {entry['http_method']}, got {cap.method}"
+    )
+
+    # Path (exact or substring).
+    if "path" in entry:
+        assert cap.path == entry["path"], (
+            f"{entry['method']}: expected path {entry['path']}, got {cap.path}"
+        )
+    elif "path_contains" in entry:
+        assert entry["path_contains"] in cap.full_path
+
+    body = cap.body
+
+    # Action: present, correct, and a valid member of the endpoint set.
+    if entry["action"] is not None:
+        assert body.get("action") == entry["action"], (
+            f"{entry['method']}: expected action {entry['action']}, "
+            f"got {body.get('action')}"
+        )
+        path = entry.get("path")
+        if path in VALID_ACTIONS:
+            assert body["action"] in VALID_ACTIONS[path]
+    else:
+        # Monolithic endpoints must not carry an action field.
+        assert "action" not in body, (
+            f"{entry['method']}: monolithic endpoint must not send action"
+        )
+
+    # Required fields present.
+    for field in entry["required_fields"]:
+        assert field in body, (
+            f"{entry['method']}: missing required field {field!r} in body {body}"
+        )
+
+    # Forbidden (anti-convention) fields absent.
+    for field in entry.get("forbidden_fields", []):
+        assert field not in body, (
+            f"{entry['method']}: forbidden field {field!r} present in body {body}"
+        )
+
+    client.close()
+
+
+# ---------------------------------------------------------------------------
+# Passthrough (**kwargs) methods: action is supplied by the caller and must
+# land in the body unchanged, on the right path, within the valid set.
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "entry", PASSTHROUGH, ids=[e["method"] for e in PASSTHROUGH]
+)
+def test_passthrough_method_forwards_action(entry: dict):
+    cap = Capture()
+    client = make_client(cap)
+    method = getattr(client, entry["method"])
+
+    method(action=entry["action"], label="x", summary="y")
+
+    assert cap.method == "POST"
+    assert cap.path == entry["path"]
+    body = cap.body
+    assert body.get("action") == entry["action"]
+    assert body["action"] in VALID_ACTIONS[entry["path"]]
+    client.close()
+
+
+# ---------------------------------------------------------------------------
+# Field-name conventions (SDK-Server Field Name Conventions in CLAUDE.md).
+# ---------------------------------------------------------------------------
+
+
+def test_traverse_uses_start_uid_not_uid_or_from_uid():
+    cap = Capture()
+    client = make_client(cap)
+    client.traverse(action="chain", start_uid="n_1", max_depth=2)
+    body = cap.body
+    assert body.get(FIELD_CONVENTIONS["traverse_start_uid"]) == "n_1"
+    assert "uid" not in body
+    assert "from_uid" not in body
+    client.close()
+
+
+def test_traverse_path_uses_end_uid_not_to_uid():
+    cap = Capture()
+    client = make_client(cap)
+    client.traverse(action="path", start_uid="n_1", end_uid="n_2")
+    body = cap.body
+    assert body.get("action") == "path"
+    assert body.get(FIELD_CONVENTIONS["traverse_start_uid"]) == "n_1"
+    assert body.get(FIELD_CONVENTIONS["traverse_path_end_uid"]) == "n_2"
+    assert "to_uid" not in body
+    client.close()
+
+
+def test_reasoning_chain_shortcut_uses_start_uid():
+    cap = Capture()
+    client = make_client(cap, response_json={"steps": []})
+    client.reasoning_chain("n_1", max_depth=3)
+    body = cap.body
+    assert cap.path == "/traverse"
+    assert body == {"action": "chain", "start_uid": "n_1", "max_depth": 3}
+    client.close()
+
+
+# ---------------------------------------------------------------------------
+# /epistemic/argument is MONOLITHIC: no action; structured claim + evidence
+# (evidence is an ARRAY per the server's ArgumentRequest contract).
+# ---------------------------------------------------------------------------
+
+
+def test_argue_is_monolithic_no_action_evidence_array():
+    cap = Capture()
+    client = make_client(cap, response_json={"claim_uid": "c_1"})
+    client.argue(
+        claim={"label": "C", "statement": "s"},
+        evidence=[{"label": "E", "statement": "e"}],
+    )
+    body = cap.body
+    assert cap.path == "/epistemic/argument"
+    assert "action" not in body  # monolithic
+    assert "claim" in body
+    assert isinstance(body["evidence"], list)  # server contract: evidence is array
+    client.close()
+
+
+# ---------------------------------------------------------------------------
+# The full /retrieve action set is reachable through the raw retrieve() method
+# (the Python RetrieveRequest is untyped **kwargs, so all 13 are accepted).
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("action", sorted(VALID_ACTIONS["/retrieve"]))
+def test_retrieve_accepts_every_valid_action(action: str):
+    cap = Capture()
+    client = make_client(cap, response_json=[])
+    client.retrieve(action=action)
+    body = cap.body
+    assert cap.path == "/retrieve"
+    assert body.get("action") == action
+    client.close()
+
+
+def test_retrieve_includes_merge_candidates_and_curation_counts():
+    """These two are valid server-side but omitted from the TS enum (R4 #3).
+    Python's untyped kwargs accept both — assert they reach the wire."""
+    for action in ("merge_candidates", "curation_counts"):
+        cap = Capture()
+        client = make_client(cap, response_json=[])
+        client.retrieve(action=action)
+        assert cap.body.get("action") == action
+        client.close()
+
+
+# ---------------------------------------------------------------------------
+# Auth header wiring (verifies the client still sets Bearer auth offline).
+# ---------------------------------------------------------------------------
+
+
+def test_api_key_sets_bearer_auth_header():
+    captured: dict[str, Any] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["auth"] = request.headers.get("Authorization")
+        return httpx.Response(200, json={"status": "ok"})
+
+    client = MindGraph(BASE_URL, api_key="mg_secret")
+    client._client = httpx.Client(
+        base_url=client.base_url,
+        headers={"Authorization": "Bearer mg_secret"},
+        transport=httpx.MockTransport(handler),
+    )
+    client.health()
+    assert captured["auth"] == "Bearer mg_secret"
+    client.close()
+
+
+# ===========================================================================
+# KNOWN R4 DIVERGENCES — pinned, documented, NON-failing.
+#
+# These restate the *current* Python behavior that diverges from the TS SDK
+# and/or the canonical reconciliation R4 will eventually land. R4 is a pending
+# owner/product decision (a confirmed breaking change), so these tests assert
+# present behavior so the divergence is visible and intentional in CI, while
+# any UNDOCUMENTED drift still fails the contract tests above.
+# ===========================================================================
+
+# Allowlist: human-readable record of each pinned divergence.
+KNOWN_DIVERGENCES = [
+    "R4#1 add_claim -> POST /epistemic/inquiry action=hypothesis -> Hypothesis "
+    "(TS addClaim -> POST /epistemic/argument -> Claim). Different endpoint AND node type.",
+    "R4#2 add_evidence sends a single OBJECT under 'evidence' with 'summary' "
+    "(TS addEvidence sends an ARRAY + props).",
+    "R4#3 Python retrieve() accepts merge_candidates and curation_counts "
+    "(TS RetrieveRequest.action omits both, though both are valid server-side).",
+    "R4#4 get_article_by_subject maps ONLY 404 -> None and re-raises other errors "
+    "(TS getArticleBySubject swallows ALL errors as not-found).",
+    "R4#5 Python client has a 30s default timeout (TS request() has no timeout).",
+]
+
+
+def test_known_divergence_1_add_claim_routes_to_inquiry_hypothesis():
+    cap = Capture()
+    client = make_client(cap)
+    client.add_claim("Label", "content", confidence=0.8)
+    body = cap.body
+    # Diverges from TS: Py uses /epistemic/inquiry + hypothesis, NOT /epistemic/argument.
+    assert cap.path == "/epistemic/inquiry"
+    assert body.get("action") == "hypothesis"
+    assert body.get("label") == "Label"
+    assert body.get("summary") == "content"
+    client.close()
+
+
+def test_known_divergence_2_add_evidence_sends_single_object():
+    cap = Capture()
+    client = make_client(cap, response_json={"uid": "e_1"})
+    client.add_evidence("Evidence label", "the description")
+    body = cap.body
+    assert cap.path == "/epistemic/argument"
+    # Diverges from TS array form: Py sends a single dict object + summary.
+    assert isinstance(body.get("evidence"), dict)
+    assert body["evidence"]["label"] == "Evidence label"
+    assert body["evidence"]["summary"] == "the description"
+    client.close()
+
+
+def test_known_divergence_3_retrieve_accepts_ts_omitted_actions():
+    for action in ("merge_candidates", "curation_counts"):
+        cap = Capture()
+        client = make_client(cap, response_json=[])
+        client.retrieve(action=action)
+        assert cap.body.get("action") == action
+        client.close()
+
+
+def test_known_divergence_4_get_article_by_subject_404_only():
+    # 404 -> None
+    def handler_404(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(404, json={"error": "not found"})
+
+    client = MindGraph(BASE_URL, api_key="mg_test")
+    client._client = httpx.Client(
+        base_url=client.base_url, transport=httpx.MockTransport(handler_404)
+    )
+    assert client.get_article_by_subject("subj_1") is None
+    client.close()
+
+    # 500 -> re-raised (NOT swallowed, unlike TS).
+    def handler_500(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(500, json={"error": "boom"})
+
+    from mindgraph import MindGraphError
+
+    client2 = MindGraph(BASE_URL, api_key="mg_test")
+    client2._client = httpx.Client(
+        base_url=client2.base_url, transport=httpx.MockTransport(handler_500)
+    )
+    with pytest.raises(MindGraphError):
+        client2.get_article_by_subject("subj_1")
+    client2.close()
+
+
+def test_known_divergence_5_default_timeout_is_30s():
+    # Build a normal client (real transport, but we never send a request) and
+    # inspect its configured timeout — Python default is 30s; TS has none.
+    client = MindGraph(BASE_URL, api_key="mg_test")
+    assert client._client.timeout.read == 30.0
+    client.close()
+
+
+def test_known_divergences_documented():
+    """Guard: the allowlist stays populated so divergences remain visible."""
+    assert len(KNOWN_DIVERGENCES) == 5
+    assert all(d.startswith("R4#") for d in KNOWN_DIVERGENCES)

mindgraph_sdk-0.7.0/.github/workflows/publish.yml

@@ -1,25 +0,0 @@
-name: Publish to PyPI
-
-on:
-  push:
-    tags:
-      - 'v*'
-  workflow_dispatch:
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    environment: pypi
-    permissions:
-      id-token: write
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.12'
-
-      - run: pip install build
-      - run: python -m build
-
-      - uses: pypa/gh-action-pypi-publish@release/v1