stacklink-sdk 0.2.0__py3-none-any.whl

stacklink/mcp.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .errors import StacklinkError
+
+
+class McpResource:
+    def __init__(self, client):
+        self.client = client
+
+    def request(self, body: dict[str, Any] | list[dict[str, Any]]):
+        return self.client.request("POST", "/v1/mcp", json_body=body)
+
+    def session_request(self, session_id: str, body: dict[str, Any] | list[dict[str, Any]]):
+        return self.client.request("POST", f"/v1/sessions/{session_id}/mcp", json_body=body)
+
+    def list_tools(self):
+        return self.request({"jsonrpc": "2.0", "id": "tools-list", "method": "tools/list"})
+
+    def call_tool(self, name: str, arguments: dict[str, Any]):
+        return self.request({
+            "jsonrpc": "2.0",
+            "id": f"{name}-call",
+            "method": "tools/call",
+            "params": {"name": name, "arguments": arguments},
+        })
+
+    def call_session_tool(self, session_id: str, name: str, arguments: dict[str, Any]):
+        return self.session_request(session_id, {
+            "jsonrpc": "2.0",
+            "id": f"{name}-call",
+            "method": "tools/call",
+            "params": {"name": name, "arguments": arguments},
+        })
+
+    def call_session_tool_result(self, session_id: str, name: str, arguments: dict[str, Any]):
+        return unwrap_tool_result(self.call_session_tool(session_id, name, arguments))
+
+
+def unwrap_tool_result(response: Any):
+    if not isinstance(response, dict):
+        return response
+    error = response.get("error")
+    if isinstance(error, dict):
+        raise StacklinkError(
+            str(error.get("message") or "Stacklink MCP tool call failed."),
+            status_code=400,
+            code=str(error.get("code")) if error.get("code") is not None else None,
+            details=error.get("data"),
+        )
+    result = response.get("result")
+    if not isinstance(result, dict):
+        return result
+    if result.get("isError") is True:
+        text = "\n".join(
+            str(item.get("text"))
+            for item in result.get("content", [])
+            if isinstance(item, dict) and item.get("type") == "text" and isinstance(item.get("text"), str)
+        )
+        raise StacklinkError(text or "Stacklink MCP tool call failed.", status_code=400, code="mcp_tool_error", details=result)
+    if "structuredContent" in result:
+        return result["structuredContent"]
+    content = result.get("content")
+    text_items = [
+        item["text"]
+        for item in content or []
+        if isinstance(item, dict) and item.get("type") == "text" and isinstance(item.get("text"), str)
+    ]
+    if len(text_items) != 1:
+        return result
+    try:
+        return json.loads(text_items[0])
+    except json.JSONDecodeError:
+        return text_items[0]

stacklink/memory.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+
+class MemoryResource:
+    def __init__(self, client):
+        self.client = client
+
+    def list_policies(self):
+        return self.client.request("GET", "/v1/memory/policies")
+
+    def create_policy(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/memory/policies", json_body=body)
+
+    def get_policy(self, policy_key: str = "default"):
+        return self.client.request("GET", f"/v1/memory/policies/{quote(policy_key, safe='')}")
+
+    def policy_history(self, policy_key: str = "default"):
+        return self.client.request("GET", f"/v1/memory/policies/{quote(policy_key, safe='')}/history")
+
+    def preview_policy(self, body: dict[str, Any], policy_key: str = "default"):
+        return self.client.request(
+            "POST",
+            f"/v1/memory/policies/{quote(policy_key, safe='')}/preview",
+            json_body=body,
+        )
+
+    def update_policy(self, policy_key: str, body: dict[str, Any]):
+        return self.client.request(
+            "PATCH",
+            f"/v1/memory/policies/{quote(policy_key, safe='')}",
+            json_body=body,
+        )
+
+    def delete_policy(self, policy_key: str):
+        return self.client.request("DELETE", f"/v1/memory/policies/{quote(policy_key, safe='')}")
+
+    def ingest(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/memory/ingest", json_body=body)
+
+    def ingest_rich(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/memory/ingest-rich", json_body=body)
+
+    def get_rich_ingest(self, job_id: str):
+        return self.client.request("GET", f"/v1/memory/ingest-rich/{job_id}")
+
+    def record_conversation_turn(self, body: dict[str, Any]):
+        return self.client.request(
+            "POST",
+            "/v1/memory/events/conversation-turn-completed",
+            json_body=body,
+        )
+
+    def add(self, body: dict[str, Any]):
+        return self.ingest({**body, "mode": "exact"})
+
+    def search(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/memory/search", json_body=body)
+
+    def context(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/memory/context", json_body=body)
+
+    def list_records(self, **query):
+        return self.client.request("GET", "/v1/memory/records", query=query)
+
+    def list_forgotten_records(self, **query):
+        return self.client.request("GET", "/v1/memory/admin/forgotten-records", query=query)
+
+    def get(self, memory_id: str, **query):
+        return self.client.request("GET", f"/v1/memory/records/{memory_id}", query=query)
+
+    def history(self, memory_id: str, **query):
+        return self.client.request("GET", f"/v1/memory/records/{memory_id}/history", query=query)
+
+    def update(self, memory_id: str, body: dict[str, Any]):
+        return self.client.request("PATCH", f"/v1/memory/records/{memory_id}", json_body=body)
+
+    def forget(self, memory_id: str, body: dict[str, Any]):
+        return self.client.request("POST", f"/v1/memory/records/{memory_id}/forget", json_body=body)
+
+    def restore(self, memory_id: str, body: dict[str, Any]):
+        return self.client.request("POST", f"/v1/memory/records/{memory_id}/restore", json_body=body)
+
+    def erase(self, memory_id: str, body: dict[str, Any]):
+        return self.client.request("DELETE", f"/v1/memory/records/{memory_id}", json_body=body)
+
+    def preview_erasure(self, memory_id: str, body: dict[str, Any]):
+        return self.client.request(
+            "POST",
+            f"/v1/memory/records/{memory_id}/erasure-preview",
+            json_body=body,
+        )
+
+    def get_erasure(self, erasure_job_id: str):
+        return self.client.request("GET", f"/v1/memory/erasures/{erasure_job_id}")
+
+    def profile(self, **query):
+        return self.client.request("GET", "/v1/memory/profile", query=query)
+
+    def subject_profile(self, subject_id: str, **query):
+        return self.client.request("GET", f"/v1/memory/subjects/{subject_id}/profile", query=query)
+
+    def list_subjects(self, **query):
+        return self.client.request("GET", "/v1/memory/subjects", query=query)
+
+    def erase_subject(self, subject_id: str, body: dict[str, Any]):
+        return self.client.request("POST", f"/v1/memory/subjects/{subject_id}/erase", json_body=body)
+
+    def create_block(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/memory/blocks", json_body=body)
+
+    def list_blocks(self, **query):
+        return self.client.request("GET", "/v1/memory/blocks", query=query)
+
+    def update_block(self, block_id: str, body: dict[str, Any]):
+        return self.client.request("PATCH", f"/v1/memory/blocks/{block_id}", json_body=body)
+
+    def revoke_block(self, block_id: str, body: dict[str, Any]):
+        return self.client.request("DELETE", f"/v1/memory/blocks/{block_id}", json_body=body)
+
+    def query_graph(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/memory/graph/query", json_body=body)
+
+    def create_source(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/memory/sources", json_body=body)
+
+    def preview_connected_source(self, body: dict[str, Any]):
+        return self.client.request(
+            "POST",
+            "/v1/memory/sources/connected/preview",
+            json_body=body,
+        )
+
+    def create_connected_source(self, body: dict[str, Any]):
+        return self.client.request(
+            "POST",
+            "/v1/memory/sources/connected",
+            json_body=body,
+        )
+
+    def list_sources(self, **query):
+        return self.client.request("GET", "/v1/memory/sources", query=query)
+
+    def get_source(self, binding_id: str):
+        return self.client.request("GET", f"/v1/memory/sources/{binding_id}")
+
+    def set_source_status(self, binding_id: str, status: str):
+        return self.update_source(binding_id, {"status": status})
+
+    def update_source(self, binding_id: str, body: dict[str, Any]):
+        return self.client.request(
+            "PATCH",
+            f"/v1/memory/sources/{binding_id}",
+            json_body=body,
+        )
+
+    def delete_source(self, binding_id: str):
+        return self.client.request("DELETE", f"/v1/memory/sources/{binding_id}")
+
+    def replay_source_item(self, binding_id: str, item_id: str):
+        return self.client.request(
+            "POST",
+            f"/v1/memory/sources/{binding_id}/items/{item_id}/replay",
+        )
+
+    def list_source_deliveries(self, **query):
+        return self.client.request("GET", "/v1/memory/source-deliveries", query=query)
+
+    def replay_source_delivery(self, delivery_id: str):
+        return self.client.request("POST", f"/v1/memory/source-deliveries/{delivery_id}/replay")
+
+    def export_memory(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/memory/exports", json_body=body)
+
+    def get_export(self, export_id: str):
+        return self.client.request("GET", f"/v1/memory/exports/{export_id}")
+
+    def data_management(self, **query):
+        return self.client.request("GET", "/v1/memory/data-management", query=query)
+
+    def create_legal_hold(self, body: dict[str, Any]):
+        return self.client.request("POST", "/v1/memory/legal-holds", json_body=body)
+
+    def release_legal_hold(self, hold_id: str):
+        return self.client.request("POST", f"/v1/memory/legal-holds/{hold_id}/release")
+
+
+class SessionMemoryResource:
+    def __init__(self, memory: MemoryResource, session_id: str):
+        self.memory = memory
+        self.session_id = session_id
+
+    def add(self, body: dict[str, Any]):
+        return self.memory.add({**body, "sessionId": self.session_id})
+
+    def ingest(self, body: dict[str, Any]):
+        return self.memory.ingest({**body, "sessionId": self.session_id})
+
+    def ingest_rich(self, body: dict[str, Any]):
+        return self.memory.ingest_rich({**body, "sessionId": self.session_id})
+
+    def get_rich_ingest(self, job_id: str):
+        return self.memory.get_rich_ingest(job_id)
+
+    def record_conversation_turn(self, body: dict[str, Any]):
+        return self.memory.record_conversation_turn({**body, "sessionId": self.session_id})
+
+    def search(self, body: dict[str, Any]):
+        return self.memory.search({**body, "sessionId": self.session_id})
+
+    def context(self, body: dict[str, Any]):
+        return self.memory.context({**body, "sessionId": self.session_id})
+
+    def recall(self, body: dict[str, Any]):
+        return self.context(body)
+
+    def profile(self):
+        return self.memory.profile(sessionId=self.session_id)
+
+    def get(self, memory_id: str):
+        return self.memory.get(memory_id, sessionId=self.session_id)
+
+    def history(self, memory_id: str):
+        return self.memory.history(memory_id, sessionId=self.session_id)
+
+    def update(self, memory_id: str, patch: dict[str, Any]):
+        return self.memory.update(memory_id, {"sessionId": self.session_id, "patch": patch})
+
+    def forget(self, memory_id: str, reason: str | None = None):
+        body: dict[str, Any] = {"sessionId": self.session_id}
+        if reason is not None:
+            body["reason"] = reason
+        return self.memory.forget(memory_id, body)

stacklink/openai_agents.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from agents import FunctionTool
+
+    from .sessions import Session, SessionTool
+
+
+def create_stacklink_openai_agents_tools(session: "Session") -> list["FunctionTool"]:
+    try:
+        from agents import FunctionTool
+    except ImportError as error:
+        raise ImportError(
+            "OpenAI Agents SDK support requires the 'openai-agents' extra: "
+            "pip install 'stacklink-sdk[openai-agents]'"
+        ) from error
+
+    return [
+        FunctionTool(
+            name=tool.name,
+            description=tool.description,
+            params_json_schema=tool.parameters,
+            on_invoke_tool=_tool_invoker(tool),
+            strict_json_schema=False,
+        )
+        for tool in session.tools().values()
+    ]
+
+
+def _tool_invoker(tool: "SessionTool"):
+    async def invoke(_context: Any, arguments_json: str) -> Any:
+        arguments = json.loads(arguments_json) if arguments_json else {}
+        if not isinstance(arguments, dict):
+            raise ValueError("Stacklink tool input must be a JSON object.")
+        return tool.call(arguments)
+
+    return invoke