mindgraph-sdk 0.1.0__tar.gz

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

@@ -0,0 +1,25 @@
+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

mindgraph_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: mindgraph-sdk
+Version: 0.1.0
+Summary: Python client for the MindGraph Cloud API
+License-Expression: MIT
+Keywords: agent,ai,cognitive,knowledge-graph,mindgraph
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mindgraph
+
+[![PyPI](https://img.shields.io/pypi/v/mindgraph)](https://pypi.org/project/mindgraph/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Python client for the [MindGraph Cloud](https://mindgraph.cloud) API — a structured semantic memory graph for AI agents.
+
+## Install
+
+```bash
+pip install mindgraph
+```
+
+## Quick Start
+
+```python
+from mindgraph import MindGraph
+
+with MindGraph("https://api.mindgraph.cloud", api_key="mg_...") as graph:
+    # Add a node
+    node = graph.add_node(
+        label="User prefers dark mode",
+        node_type="Preference",
+    )
+
+    # Search
+    results = graph.search("what does the user prefer?")
+
+    # Connect knowledge
+    graph.add_link(
+        from_uid=node["uid"],
+        to_uid="user_abc",
+        edge_type="BelongsTo",
+    )
+```
+
+## API Reference
+
+### Constructor
+
+```python
+MindGraph(base_url, *, api_key=None, jwt=None, timeout=30.0)
+```
+
+Supports context manager protocol (`with` statement) for automatic cleanup.
+
+### Reality Layer
+
+| Method | Description |
+|--------|-------------|
+| `ingest(**kwargs)` | Ingest a source, snippet, or observation |
+| `entity(**kwargs)` | Create, alias, resolve, or merge entities |
+| `find_or_create_entity(label, entity_type?, agent_id?)` | Convenience: create or find an entity by label |
+
+### Epistemic Layer
+
+| Method | Description |
+|--------|-------------|
+| `argue(**kwargs)` | Construct a full argument: claim + evidence + warrant + edges |
+| `inquire(**kwargs)` | Add hypothesis, theory, paradigm, anomaly, assumption, or question |
+| `structure(**kwargs)` | Add concept, pattern, mechanism, model, analogy, theorem, etc. |
+
+### Intent Layer
+
+| Method | Description |
+|--------|-------------|
+| `commit(**kwargs)` | Create a goal, project, or milestone |
+| `deliberate(**kwargs)` | Open decisions, add options/constraints, resolve decisions |
+
+### Action Layer
+
+| Method | Description |
+|--------|-------------|
+| `procedure(**kwargs)` | Build flows, add steps, affordances, and controls |
+| `risk(**kwargs)` | Assess risk or retrieve existing assessments |
+
+### Memory Layer
+
+| Method | Description |
+|--------|-------------|
+| `session(**kwargs)` | Open a session, record traces, or close a session |
+| `distill(**kwargs)` | Create a summary that distills multiple source nodes |
+| `memory_config(**kwargs)` | Set/get preferences and memory policies |
+
+### Agent Layer
+
+| Method | Description |
+|--------|-------------|
+| `plan(**kwargs)` | Create tasks, plans, plan steps, update status |
+| `governance(**kwargs)` | Create policies, set safety budgets, request/resolve approvals |
+| `execution(**kwargs)` | Track execution lifecycle and register agents |
+
+### CRUD
+
+| Method | Description |
+|--------|-------------|
+| `get_node(uid)` | Get a node by UID |
+| `add_node(label, node_type?, props?, agent_id?)` | Add a generic node |
+| `update_node(uid, **kwargs)` | Update node fields |
+| `delete_node(uid)` | Tombstone a node and all connected edges |
+| `add_link(from_uid, to_uid, edge_type, agent_id?)` | Add a typed edge |
+| `get_edges(from_uid?, to_uid?)` | Get edges by source or target |
+
+### Search
+
+| Method | Description |
+|--------|-------------|
+| `search(query, node_type?, layer?, limit?)` | Full-text search |
+| `hybrid_search(query, k?, node_types?, layer?)` | BM25 + vector search with rank fusion |
+
+### Traversal
+
+| Method | Description |
+|--------|-------------|
+| `reasoning_chain(uid, max_depth=5)` | Follow epistemic edges from a node |
+| `neighborhood(uid, max_depth=1)` | Get all nodes within N hops |
+
+### Cross-cutting
+
+| Method | Description |
+|--------|-------------|
+| `retrieve(**kwargs)` | Unified retrieval: text search, active goals, open questions, weak claims |
+| `traverse(**kwargs)` | Graph traversal: chain, neighborhood, path, or subgraph |
+| `evolve(**kwargs)` | Lifecycle mutations: update, tombstone, restore, decay, history |
+
+### Health & Stats
+
+| Method | Description |
+|--------|-------------|
+| `health()` | Health check |
+| `stats()` | Graph-wide statistics |
+
+## Error Handling
+
+All methods raise `MindGraphError` on HTTP errors:
+
+```python
+from mindgraph import MindGraphError
+
+try:
+    graph.get_node("nonexistent")
+except MindGraphError as e:
+    print(e.status, e.body)
+```
+
+## License
+
+MIT

mindgraph_sdk-0.1.0/README.md

@@ -0,0 +1,148 @@
+# mindgraph
+
+[![PyPI](https://img.shields.io/pypi/v/mindgraph)](https://pypi.org/project/mindgraph/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Python client for the [MindGraph Cloud](https://mindgraph.cloud) API — a structured semantic memory graph for AI agents.
+
+## Install
+
+```bash
+pip install mindgraph
+```
+
+## Quick Start
+
+```python
+from mindgraph import MindGraph
+
+with MindGraph("https://api.mindgraph.cloud", api_key="mg_...") as graph:
+    # Add a node
+    node = graph.add_node(
+        label="User prefers dark mode",
+        node_type="Preference",
+    )
+
+    # Search
+    results = graph.search("what does the user prefer?")
+
+    # Connect knowledge
+    graph.add_link(
+        from_uid=node["uid"],
+        to_uid="user_abc",
+        edge_type="BelongsTo",
+    )
+```
+
+## API Reference
+
+### Constructor
+
+```python
+MindGraph(base_url, *, api_key=None, jwt=None, timeout=30.0)
+```
+
+Supports context manager protocol (`with` statement) for automatic cleanup.
+
+### Reality Layer
+
+| Method | Description |
+|--------|-------------|
+| `ingest(**kwargs)` | Ingest a source, snippet, or observation |
+| `entity(**kwargs)` | Create, alias, resolve, or merge entities |
+| `find_or_create_entity(label, entity_type?, agent_id?)` | Convenience: create or find an entity by label |
+
+### Epistemic Layer
+
+| Method | Description |
+|--------|-------------|
+| `argue(**kwargs)` | Construct a full argument: claim + evidence + warrant + edges |
+| `inquire(**kwargs)` | Add hypothesis, theory, paradigm, anomaly, assumption, or question |
+| `structure(**kwargs)` | Add concept, pattern, mechanism, model, analogy, theorem, etc. |
+
+### Intent Layer
+
+| Method | Description |
+|--------|-------------|
+| `commit(**kwargs)` | Create a goal, project, or milestone |
+| `deliberate(**kwargs)` | Open decisions, add options/constraints, resolve decisions |
+
+### Action Layer
+
+| Method | Description |
+|--------|-------------|
+| `procedure(**kwargs)` | Build flows, add steps, affordances, and controls |
+| `risk(**kwargs)` | Assess risk or retrieve existing assessments |
+
+### Memory Layer
+
+| Method | Description |
+|--------|-------------|
+| `session(**kwargs)` | Open a session, record traces, or close a session |
+| `distill(**kwargs)` | Create a summary that distills multiple source nodes |
+| `memory_config(**kwargs)` | Set/get preferences and memory policies |
+
+### Agent Layer
+
+| Method | Description |
+|--------|-------------|
+| `plan(**kwargs)` | Create tasks, plans, plan steps, update status |
+| `governance(**kwargs)` | Create policies, set safety budgets, request/resolve approvals |
+| `execution(**kwargs)` | Track execution lifecycle and register agents |
+
+### CRUD
+
+| Method | Description |
+|--------|-------------|
+| `get_node(uid)` | Get a node by UID |
+| `add_node(label, node_type?, props?, agent_id?)` | Add a generic node |
+| `update_node(uid, **kwargs)` | Update node fields |
+| `delete_node(uid)` | Tombstone a node and all connected edges |
+| `add_link(from_uid, to_uid, edge_type, agent_id?)` | Add a typed edge |
+| `get_edges(from_uid?, to_uid?)` | Get edges by source or target |
+
+### Search
+
+| Method | Description |
+|--------|-------------|
+| `search(query, node_type?, layer?, limit?)` | Full-text search |
+| `hybrid_search(query, k?, node_types?, layer?)` | BM25 + vector search with rank fusion |
+
+### Traversal
+
+| Method | Description |
+|--------|-------------|
+| `reasoning_chain(uid, max_depth=5)` | Follow epistemic edges from a node |
+| `neighborhood(uid, max_depth=1)` | Get all nodes within N hops |
+
+### Cross-cutting
+
+| Method | Description |
+|--------|-------------|
+| `retrieve(**kwargs)` | Unified retrieval: text search, active goals, open questions, weak claims |
+| `traverse(**kwargs)` | Graph traversal: chain, neighborhood, path, or subgraph |
+| `evolve(**kwargs)` | Lifecycle mutations: update, tombstone, restore, decay, history |
+
+### Health & Stats
+
+| Method | Description |
+|--------|-------------|
+| `health()` | Health check |
+| `stats()` | Graph-wide statistics |
+
+## Error Handling
+
+All methods raise `MindGraphError` on HTTP errors:
+
+```python
+from mindgraph import MindGraphError
+
+try:
+    graph.get_node("nonexistent")
+except MindGraphError as e:
+    print(e.status, e.body)
+```
+
+## License
+
+MIT

mindgraph_sdk-0.1.0/mindgraph/__init__.py

@@ -0,0 +1,3 @@
+from .client import MindGraph, MindGraphError
+
+__all__ = ["MindGraph", "MindGraphError"]

mindgraph_sdk-0.1.0/mindgraph/client.py

@@ -0,0 +1,300 @@
+"""MindGraph Python client for the MindGraph Cloud API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class MindGraphError(Exception):
+    def __init__(self, message: str, status: int, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class MindGraph:
+    """Client for the MindGraph REST API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: str | None = None,
+        jwt: str | None = None,
+        timeout: float = 30.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        elif jwt:
+            headers["Authorization"] = f"Bearer {jwt}"
+        self._client = httpx.Client(
+            base_url=self.base_url, headers=headers, timeout=timeout
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> MindGraph:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # ---- HTTP helpers ----
+
+    def _request(self, method: str, path: str, json: Any = None) -> Any:
+        resp = self._client.request(method, path, json=json)
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+            except Exception:
+                body = resp.text
+            raise MindGraphError(
+                f"{method} {path} failed: {resp.status_code}",
+                resp.status_code,
+                body,
+            )
+        if not resp.content:
+            return None
+        return resp.json()
+
+    # ---- Health ----
+
+    def health(self) -> dict[str, str]:
+        return self._request("GET", "/health")
+
+    def stats(self) -> dict[str, Any]:
+        return self._request("GET", "/stats")
+
+    # ---- Reality Layer ----
+
+    def ingest(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/reality/ingest", kwargs)
+
+    def entity(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/reality/entity", kwargs)
+
+    def find_or_create_entity(
+        self,
+        label: str,
+        entity_type: str = "other",
+        agent_id: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "action": "create",
+            "label": label,
+            "entity_type": entity_type,
+        }
+        if agent_id:
+            body["agent_id"] = agent_id
+        return self._request("POST", "/reality/entity", body)
+
+    # ---- Epistemic Layer ----
+
+    def argue(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/epistemic/argument", kwargs)
+
+    def inquire(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/epistemic/inquiry", kwargs)
+
+    def structure(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/epistemic/structure", kwargs)
+
+    # ---- Intent Layer ----
+
+    def commit(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/intent/commitment", kwargs)
+
+    def deliberate(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/intent/deliberation", kwargs)
+
+    # ---- Action Layer ----
+
+    def procedure(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/action/procedure", kwargs)
+
+    def risk(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/action/risk", kwargs)
+
+    # ---- Memory Layer ----
+
+    def session(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/memory/session", kwargs)
+
+    def distill(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/memory/distill", kwargs)
+
+    def memory_config(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/memory/config", kwargs)
+
+    # ---- Agent Layer ----
+
+    def plan(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/agent/plan", kwargs)
+
+    def governance(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/agent/governance", kwargs)
+
+    def execution(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/agent/execution", kwargs)
+
+    # ---- Cross-cutting ----
+
+    def retrieve(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/retrieve", kwargs)
+
+    def traverse(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/traverse", kwargs)
+
+    def evolve(self, **kwargs: Any) -> Any:
+        return self._request("POST", "/evolve", kwargs)
+
+    # ---- Node CRUD ----
+
+    def get_node(self, uid: str) -> dict[str, Any]:
+        return self._request("GET", f"/node/{uid}")
+
+    def add_node(
+        self,
+        label: str,
+        node_type: str | None = None,
+        props: dict[str, Any] | None = None,
+        agent_id: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"label": label}
+        if node_type:
+            body["node_type"] = node_type
+        if props:
+            body["props"] = props
+        if agent_id:
+            body["agent_id"] = agent_id
+        return self._request("POST", "/node", body)
+
+    def update_node(
+        self, uid: str, **kwargs: Any
+    ) -> dict[str, Any]:
+        return self._request("PATCH", f"/node/{uid}", kwargs)
+
+    def delete_node(self, uid: str) -> None:
+        self._request("DELETE", f"/node/{uid}")
+
+    # ---- Edge CRUD ----
+
+    def add_link(
+        self,
+        from_uid: str,
+        to_uid: str,
+        edge_type: str,
+        agent_id: str | None = None,
+    ) -> Any:
+        body: dict[str, Any] = {
+            "from_uid": from_uid,
+            "to_uid": to_uid,
+            "edge_type": edge_type,
+        }
+        if agent_id:
+            body["agent_id"] = agent_id
+        return self._request("POST", "/link", body)
+
+    def get_edges(
+        self,
+        from_uid: str | None = None,
+        to_uid: str | None = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, str] = {}
+        if from_uid:
+            params["from_uid"] = from_uid
+        if to_uid:
+            params["to_uid"] = to_uid
+        qs = "&".join(f"{k}={v}" for k, v in params.items())
+        return self._request("GET", f"/edges?{qs}")
+
+    # ---- Search ----
+
+    def search(
+        self,
+        query: str,
+        node_type: str | None = None,
+        layer: str | None = None,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        body: dict[str, Any] = {"query": query}
+        if node_type:
+            body["node_type"] = node_type
+        if layer:
+            body["layer"] = layer
+        if limit:
+            body["limit"] = limit
+        return self._request("POST", "/search", body)
+
+    def hybrid_search(
+        self,
+        query: str,
+        k: int | None = None,
+        node_types: list[str] | None = None,
+        layer: str | None = None,
+    ) -> list[dict[str, Any]]:
+        body: dict[str, Any] = {"action": "hybrid", "query": query}
+        if k:
+            body["k"] = k
+        if node_types:
+            body["node_types"] = node_types
+        if layer:
+            body["layer"] = layer
+        return self._request("POST", "/retrieve", body)
+
+    # ---- Traversal shortcuts ----
+
+    def reasoning_chain(self, uid: str, max_depth: int = 5) -> list[dict[str, Any]]:
+        return self._request(
+            "POST", "/traverse", {"action": "chain", "start_uid": uid, "max_depth": max_depth}
+        )
+
+    def neighborhood(self, uid: str, max_depth: int = 1) -> list[dict[str, Any]]:
+        return self._request(
+            "POST",
+            "/traverse",
+            {"action": "neighborhood", "start_uid": uid, "max_depth": max_depth},
+        )
+
+    # ---- Lifecycle shortcuts ----
+
+    def tombstone(
+        self, uid: str, reason: str | None = None, agent_id: str | None = None
+    ) -> Any:
+        body: dict[str, Any] = {"action": "tombstone", "uid": uid}
+        if reason:
+            body["reason"] = reason
+        if agent_id:
+            body["agent_id"] = agent_id
+        return self._request("POST", "/evolve", body)
+
+    def restore(self, uid: str, agent_id: str | None = None) -> Any:
+        body: dict[str, Any] = {"action": "restore", "uid": uid}
+        if agent_id:
+            body["agent_id"] = agent_id
+        return self._request("POST", "/evolve", body)
+
+    # ---- Management (Cloud only) ----
+
+    def signup(self, email: str, password: str) -> Any:
+        return self._request("POST", "/v1/auth/signup", {"email": email, "password": password})
+
+    def login(self, email: str, password: str) -> Any:
+        return self._request("POST", "/v1/auth/login", {"email": email, "password": password})
+
+    def create_api_key(self, name: str = "default") -> dict[str, Any]:
+        return self._request("POST", "/v1/api-keys", {"name": name})
+
+    def list_api_keys(self) -> dict[str, Any]:
+        return self._request("GET", "/v1/api-keys")
+
+    def revoke_api_key(self, key_id: str) -> None:
+        self._request("DELETE", f"/v1/api-keys/{key_id}")
+
+    def get_usage(self) -> Any:
+        return self._request("GET", "/v1/usage")

mindgraph_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mindgraph-sdk"
+version = "0.1.0"
+description = "Python client for the MindGraph Cloud API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+keywords = ["mindgraph", "knowledge-graph", "cognitive", "ai", "agent"]
+dependencies = ["httpx>=0.25"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["mindgraph"]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio", "ruff"]