xyfra-sdk 1.0.0__tar.gz

xyfra_sdk-1.0.0/.gitignore

@@ -0,0 +1,137 @@
+# =========================
+# .NET / C# Build Artifacts
+# =========================
+bin/
+obj/
+[Dd]ebug/
+[Rr]elease/
+x64/
+x86/
+*.dll
+*.exe
+*.pdb
+*.user
+*.userosscache
+*.sln.docstates
+
+# FEAT-EXPR-ACCEL v1 Bundle C — BenchmarkDotNet output (generated
+# locally by `dotnet run -c Release --project ...Tests.Bench`).
+# Not source-controlled; engineers regenerate per local hardware.
+BenchmarkDotNet.Artifacts/
+
+# NuGet Packages
+*.nupkg
+**/packages/*
+!**/packages/build/
+
+# =========================
+# Node.js / Next.js
+# =========================
+node_modules/
+.next/
+out/
+.pnpm-debug.log*
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# =========================
+# IDE / Editor Files
+# =========================
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.vs/
+
+# =========================
+# Environment & Secrets
+# =========================
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+*.env
+!.env.example
+appsettings.*.local.json
+
+# Secrets baseline (for detect-secrets pre-commit hook)
+.secrets.baseline
+
+# =========================
+# Logs
+# =========================
+logs/
+*.log
+
+# =========================
+# Test Results & Coverage
+# =========================
+TestResults/
+test-results/
+coverage/
+*.trx
+*.coverage
+*.coveragexml
+
+# =========================
+# OS Generated Files
+# =========================
+.DS_Store
+.DS_Store?
+._*
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# =========================
+# Backup Files
+# =========================
+docs_backup_*/
+*.bak
+*.backup
+
+# =========================
+# Process ID Files
+# =========================
+.pids/
+
+# =========================
+# Misc
+# =========================
+*.tmp
+*.temp
+*.cache
+
+
+# IDE / agent working directories
+.claude/
+# .cursor/* ignores immediate children (mcp.json, etc.) without blocking git
+# from descending into subdirectories. The negation rules below then
+# selectively re-include team-facing config (skills + rules).
+.cursor/*
+!.cursor/skills/
+!.cursor/skills/**
+!.cursor/rules/
+!.cursor/rules/**
+
+# Python bytecode (added 2026-05-09 — was missing; tests/aichat-schema-recovery/__pycache__/ had been silently tracked)
+__pycache__/
+*.pyc
+*.pyo
+
+# Build/export artifacts (added 2026-05-17)
+ai-sdlc-bundle.zip
+
+# FEAT-PARTNER-SURFACE Phase P4b SDK artefacts
+src/sdk/typescript/node_modules/
+src/sdk/typescript/dist/
+src/sdk/typescript/*.tgz
+src/sdk/python/.venv/
+src/sdk/python/venv/
+src/sdk/python/dist/
+src/sdk/python/build/
+src/sdk/python/*.egg-info/
+src/sdk/python/__pycache__/

xyfra_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: xyfra-sdk
+Version: 1.0.0
+Summary: Xyfra Data Platform partner SDK (Python)
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: ariadne-codegen>=0.13.0; extra == 'dev'
+Requires-Dist: datamodel-code-generator>=0.25.0; extra == 'dev'
+Requires-Dist: openapi-python-client>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# xyfra-sdk
+
+Python SDK for the Xyfra Data Platform partner surface.
+
+## Installation
+
+```bash
+pip install xyfra-sdk
+```
+
+## Usage
+
+```python
+import asyncio
+from xyfra_sdk import XyfraClient, XyfraClientOptions
+
+async def main():
+    client = XyfraClient(XyfraClientOptions(
+        base_url="https://api.xyfra.ai",
+        refresh_token="xyfra-rt-...",
+        tenant_id="tenant-123",
+    ))
+    await client.refresh()
+    result = await client.call_tool("semantic.query", {"query": "..."})
+    print(result)
+
+asyncio.run(main())
+```
+
+## Codegen
+
+The `scripts/` directory contains generators that consume the partner OpenAPI,
+GraphQL SDL, and MCP schema artefacts and emit typed clients under
+`xyfra_sdk/client/`.

xyfra_sdk-1.0.0/README.md

@@ -0,0 +1,34 @@
+# xyfra-sdk
+
+Python SDK for the Xyfra Data Platform partner surface.
+
+## Installation
+
+```bash
+pip install xyfra-sdk
+```
+
+## Usage
+
+```python
+import asyncio
+from xyfra_sdk import XyfraClient, XyfraClientOptions
+
+async def main():
+    client = XyfraClient(XyfraClientOptions(
+        base_url="https://api.xyfra.ai",
+        refresh_token="xyfra-rt-...",
+        tenant_id="tenant-123",
+    ))
+    await client.refresh()
+    result = await client.call_tool("semantic.query", {"query": "..."})
+    print(result)
+
+asyncio.run(main())
+```
+
+## Codegen
+
+The `scripts/` directory contains generators that consume the partner OpenAPI,
+GraphQL SDL, and MCP schema artefacts and emit typed clients under
+`xyfra_sdk/client/`.

xyfra_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "xyfra-sdk"
+version = "1.0.0"
+description = "Xyfra Data Platform partner SDK (Python)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "openapi-python-client>=0.21.0",
+    "ariadne-codegen>=0.13.0",
+    "datamodel-code-generator>=0.25.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["xyfra_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

xyfra_sdk-1.0.0/scripts/gen_graphql_client.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Generate the GraphQL typed operations client from the partner SDL artefact."""
+import asyncio
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import httpx
+
+
+def main() -> None:
+    base_url = os.environ.get("XYFRA_SDK_BASE_URL", "http://localhost:5000")
+    tenant_id = os.environ.get("XYFRA_SDK_TENANT_ID", "test-tenant")
+    version = os.environ.get("XYFRA_SDK_API_VERSION", "v1")
+    refresh_token = os.environ.get("XYFRA_CI_SANDBOX_REFRESH_TOKEN", "")
+
+    out_dir = Path(__file__).parent.parent / "xyfra_sdk" / "client" / "graphql"
+
+    if not refresh_token:
+        raise RuntimeError("XYFRA_CI_SANDBOX_REFRESH_TOKEN is required to fetch the partner GraphQL SDL artefact")
+
+    # Refresh to an access JWT before fetching the partner-gated endpoint.
+    from xyfra_sdk.auth import refresh_access_token
+
+    tokens = asyncio.run(refresh_access_token(base_url, refresh_token))
+    sdl_url = f"{base_url}/api/_meta/graphql/schema.graphql?tenant_id={tenant_id}&version={version}"
+
+    response = httpx.get(
+        sdl_url,
+        headers={"Authorization": f"Bearer {tokens['accessToken']}", "Accept": "text/plain"},
+    )
+    response.raise_for_status()
+
+    # ariadne-codegen emits a Python package from the SDL into the target path.
+    if out_dir.exists():
+        shutil.rmtree(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    schema_path = out_dir / "schema.graphql"
+    schema_path.write_text(response.text)
+
+    subprocess.run(
+        [
+            "ariadne-codegen",
+            "--schema",
+            str(schema_path),
+            "--target-package-path",
+            str(out_dir),
+        ],
+        check=True,
+    )
+
+    print(f"Generated GraphQL client from {sdl_url} -> {out_dir}")
+
+
+if __name__ == "__main__":
+    main()

xyfra_sdk-1.0.0/scripts/gen_mcp_client.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""Generate typed MCP tool-input Pydantic models from the partner-projected schema dump."""
+import asyncio
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+import httpx
+
+
+def main() -> None:
+    base_url = os.environ.get("XYFRA_SDK_BASE_URL", "http://localhost:5000")
+    refresh_token = os.environ.get("XYFRA_CI_SANDBOX_REFRESH_TOKEN", "")
+
+    list_url = f"{base_url}/mcp/list_tools_with_schemas"
+    out_dir = Path(__file__).parent.parent / "xyfra_sdk" / "client" / "mcp"
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    if not refresh_token:
+        raise RuntimeError("XYFRA_CI_SANDBOX_REFRESH_TOKEN is required to fetch the partner MCP schema artefact")
+
+    # Refresh to an access JWT before fetching the partner-gated endpoint.
+    from xyfra_sdk.auth import refresh_access_token
+
+    tokens = asyncio.run(refresh_access_token(base_url, refresh_token))
+
+    response = httpx.get(list_url, headers={"Authorization": f"Bearer {tokens['accessToken']}"})
+    response.raise_for_status()
+    envelope = response.json()
+    if not envelope.get("ok") or "data" not in envelope:
+        raise RuntimeError(envelope.get("error", {}).get("code", "mcp_schema_fetch_failed"))
+
+    init_lines = []
+    for tool in envelope["data"]["tools"]:
+        safe_name = re.sub(r"[^a-zA-Z0-9_]", "_", tool["name"])
+        schema = {
+            "$schema": "http://json-schema.org/draft-07/schema#",
+            "title": f"{safe_name}_input",
+            **tool["inputSchema"],
+        }
+        schema_file = out_dir / f"{safe_name}.schema.json"
+        schema_file.write_text(json.dumps(schema, indent=2))
+
+        model_file = out_dir / f"{safe_name}.py"
+        subprocess.run(
+            [
+                "datamodel-codegen",
+                "--input",
+                str(schema_file),
+                "--input-file-type",
+                "jsonschema",
+                "--output",
+                str(model_file),
+                "--class-name",
+                f"{safe_name}_input",
+            ],
+            check=True,
+        )
+        init_lines.append(f"from .{safe_name} import {safe_name}_input")
+
+    (out_dir / "__init__.py").write_text("\n".join(init_lines) + "\n")
+    print(f"Generated MCP client from {list_url} -> {out_dir}")
+
+
+if __name__ == "__main__":
+    main()

xyfra_sdk-1.0.0/scripts/gen_rest_client.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Generate the REST client module from the partner OpenAPI artefact."""
+import asyncio
+import os
+import subprocess
+from pathlib import Path
+
+import httpx
+
+
+def main() -> None:
+    base_url = os.environ.get("XYFRA_SDK_BASE_URL", "http://localhost:5000")
+    version = os.environ.get("XYFRA_SDK_API_VERSION", "v1")
+    refresh_token = os.environ.get("XYFRA_CI_SANDBOX_REFRESH_TOKEN", "")
+
+    out_dir = Path(__file__).parent.parent / "xyfra_sdk" / "client" / "rest"
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    if not refresh_token:
+        raise RuntimeError("XYFRA_CI_SANDBOX_REFRESH_TOKEN is required to fetch the partner OpenAPI artefact")
+
+    # Refresh to an access JWT before fetching the partner-gated endpoint.
+    from xyfra_sdk.auth import refresh_access_token
+
+    tokens = asyncio.run(refresh_access_token(base_url, refresh_token))
+    spec_url = f"{base_url}/api/_meta/openapi.json?version={version}"
+
+    response = httpx.get(spec_url, headers={"Authorization": f"Bearer {tokens['accessToken']}"})
+    response.raise_for_status()
+
+    spec_path = out_dir / "openapi.json"
+    spec_path.write_text(response.text)
+
+    subprocess.run(
+        [
+            "openapi-python-client",
+            "generate",
+            "--path",
+            str(spec_path),
+            "--meta",
+            "none",
+            "--output-path",
+            str(out_dir),
+        ],
+        check=True,
+    )
+    print(f"Generated REST client from {spec_url} -> {out_dir}")
+
+
+if __name__ == "__main__":
+    main()

xyfra_sdk-1.0.0/tests/test_roundtrip.py

@@ -0,0 +1,14 @@
+import pytest
+
+from xyfra_sdk import XyfraClient, XyfraClientOptions
+
+
+def test_client_init() -> None:
+    client = XyfraClient(
+        XyfraClientOptions(
+            base_url="https://api.xyfra.ai/",
+            refresh_token="rt-test",
+            tenant_id="t-test",
+        )
+    )
+    assert client is not None

xyfra_sdk-1.0.0/xyfra_sdk/__init__.py

@@ -0,0 +1,4 @@
+from .client import XyfraClient, XyfraClientOptions
+from .auth import refresh_access_token
+
+__all__ = ["XyfraClient", "XyfraClientOptions", "refresh_access_token"]

xyfra_sdk-1.0.0/xyfra_sdk/auth.py

@@ -0,0 +1,20 @@
+import os
+from typing import Any
+
+import httpx
+
+
+async def refresh_access_token(
+    base_url: str,
+    refresh_token: str,
+) -> dict[str, Any]:
+    """Refresh an access JWT from a partner refresh token."""
+    response = await httpx.AsyncClient().post(
+        f"{base_url}/api/partners/me/credentials/refresh",
+        headers={"Authorization": f"Bearer {refresh_token}"},
+    )
+    response.raise_for_status()
+    envelope = response.json()
+    if not envelope.get("ok") or "data" not in envelope:
+        raise RuntimeError(envelope.get("error", {}).get("code", "refresh_failed"))
+    return envelope["data"]

xyfra_sdk-1.0.0/xyfra_sdk/client.py

@@ -0,0 +1,273 @@
+from dataclasses import dataclass, field
+import hashlib
+import hmac
+import uuid
+from typing import Any, Callable, Optional
+
+import httpx
+
+from .auth import refresh_access_token
+
+
+@dataclass
+class XyfraClientOptions:
+    base_url: str
+    refresh_token: str
+    tenant_id: str
+    sandbox_deterministic: bool = False
+    traceparent: Optional[str] = None
+
+
+class _ToolsNamespace:
+    def __init__(self, client: "XyfraClient") -> None:
+        self._client = client
+
+    async def call(self, tool_name: str, arguments: dict[str, Any]) -> Any:
+        return await self._client._post("/mcp/call_tool", {"tool_name": tool_name, "arguments": arguments})
+
+
+class _EventsNamespace:
+    def __init__(self, client: "XyfraClient") -> None:
+        self._client = client
+
+    async def subscribe(
+        self,
+        surface: str,
+        on_event: Callable[[dict[str, Any]], None],
+        *,
+        since: Optional[str] = None,
+        signal: Any = None,
+    ) -> None:
+        params: dict[str, Any] = {"surface": surface}
+        if since:
+            params["since"] = since
+        headers = await self._client.headers()
+        headers["Accept"] = "text/event-stream"
+        async with self._client._http.stream(
+            "GET",
+            f"{self._client._base_url}/api/events",
+            headers=headers,
+            params=params,
+        ) as response:
+            response.raise_for_status()
+            buffer = ""
+            last_event_id: Optional[str] = None
+            event_name: Optional[str] = None
+            async for chunk in response.aiter_text():
+                buffer += chunk
+                lines = buffer.split("\n")
+                buffer = lines.pop()
+                for line in lines:
+                    if line.startswith("id:"):
+                        last_event_id = line[3:].strip()
+                    elif line.startswith("event:"):
+                        event_name = line[6:].strip()
+                    elif line.startswith("data:"):
+                        raw = line[5:].strip()
+                        try:
+                            import json
+
+                            data = json.loads(raw)
+                        except Exception:
+                            data = raw
+                        on_event({"id": last_event_id, "event": event_name, "data": data})
+                    elif line.strip() == "":
+                        event_name = None
+
+
+class _WebhooksNamespace:
+    def __init__(self, client: "XyfraClient") -> None:
+        self._client = client
+
+    def verify_signature(self, payload: str, signature: str, secret: str) -> bool:
+        expected = hmac.new(secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).hexdigest()
+        return hmac.compare_digest(signature, expected)
+
+
+class _AuditNamespace:
+    def __init__(self, client: "XyfraClient") -> None:
+        self._client = client
+
+    async def list(
+        self,
+        *,
+        tenant_id: Optional[str] = None,
+        since: Optional[str] = None,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Any:
+        params: dict[str, Any] = {}
+        if tenant_id:
+            params["tenant_id"] = tenant_id
+        if since:
+            params["since"] = since
+        if cursor:
+            params["cursor"] = cursor
+        if limit:
+            params["limit"] = limit
+        return await self._client._get("/api/audit", params)
+
+
+class _BillingNamespace:
+    def __init__(self, client: "XyfraClient") -> None:
+        self._client = client
+
+    async def get_period(self, period: Optional[str] = None, tenant_id: Optional[str] = None) -> Any:
+        params: dict[str, Any] = {}
+        if period:
+            params["period"] = period
+        if tenant_id:
+            params["tenantId"] = tenant_id
+        return await self._client._get("/api/partner-usage", params)
+
+    async def list_periods(self, cursor: Optional[str] = None, limit: Optional[int] = None) -> Any:
+        params: dict[str, Any] = {}
+        if cursor:
+            params["cursor"] = cursor
+        if limit:
+            params["limit"] = limit
+        return await self._client._get("/api/partner-usage/periods", params)
+
+
+class _MetricsNamespace:
+    def __init__(self, client: "XyfraClient") -> None:
+        self._client = client
+
+    async def subscribe(
+        self, tenant_id: str, prometheus_remote_write_url: str, auth_header: str
+    ) -> Any:
+        return await self._client._post(
+            "/api/partners/me/metrics-subscriptions",
+            {
+                "tenantId": tenant_id,
+                "prometheusRemoteWriteUrl": prometheus_remote_write_url,
+                "authHeader": auth_header,
+            },
+        )
+
+    async def reactivate(self, subscription_id: str) -> Any:
+        return await self._client._post(
+            f"/api/partners/me/metrics-subscriptions/{subscription_id}/reactivate",
+            {},
+        )
+
+    async def delete(self, subscription_id: str) -> None:
+        response = await self._client._http.delete(
+            f"{self._client._base_url}/api/partners/me/metrics-subscriptions/{subscription_id}",
+            headers=await self._client.headers(),
+        )
+        response.raise_for_status()
+
+
+class _QueryNamespace:
+    def __init__(self, client: "XyfraClient") -> None:
+        self._client = client
+
+    async def execute(self, query: str, variables: Optional[dict[str, Any]] = None) -> Any:
+        return await self._client._post("/graphql", {"query": query, "variables": variables or {}})
+
+
+class XyfraClient:
+    """Hand-written thin wrapper over generated REST/GraphQL/MCP client modules."""
+
+    def __init__(self, options: XyfraClientOptions) -> None:
+        base_url = options.base_url.strip() if options.base_url else ""
+        refresh_token = options.refresh_token.strip() if options.refresh_token else ""
+        tenant_id = options.tenant_id.strip() if options.tenant_id else ""
+
+        if not base_url:
+            raise ValueError("XyfraClient: base_url is required")
+        if not refresh_token:
+            raise ValueError("XyfraClient: refresh_token is required")
+        if not tenant_id:
+            raise ValueError("XyfraClient: tenant_id is required")
+
+        self._base_url = base_url.rstrip("/")
+        self._tenant_id = tenant_id
+        self._refresh_token = refresh_token
+        self._sandbox_deterministic = options.sandbox_deterministic
+        self._traceparent = options.traceparent or str(uuid.uuid4())
+        self._access_token: Optional[str] = None
+        self._http = httpx.AsyncClient()
+        self._closed = False
+
+        self.query = _QueryNamespace(self)
+        self.tools = _ToolsNamespace(self)
+        self.events = _EventsNamespace(self)
+        self.webhooks = _WebhooksNamespace(self)
+        self.audit = _AuditNamespace(self)
+        self.billing = _BillingNamespace(self)
+        self.metrics = _MetricsNamespace(self)
+
+    async def refresh(self) -> None:
+        self._assert_open()
+        result = await refresh_access_token(self._base_url, self._refresh_token)
+        self._access_token = result["accessToken"]
+        self._refresh_token = result["refreshToken"]
+
+    async def access_token(self) -> str:
+        self._assert_open()
+        if self._access_token is None:
+            await self.refresh()
+        if self._access_token is None:
+            raise RuntimeError("refresh_failed")
+        return self._access_token
+
+    async def headers(self) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {await self.access_token()}",
+            "X-Tenant-Id": self._tenant_id,
+            "X-Request-ID": self._traceparent,
+            "Content-Type": "application/json",
+        }
+        if self._sandbox_deterministic:
+            headers["X-Sandbox-Deterministic"] = "true"
+        return headers
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._access_token = None
+        await self._http.aclose()
+
+    async def aclose(self) -> None:
+        await self.close()
+
+    async def __aenter__(self) -> "XyfraClient":
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        await self.close()
+
+    @property
+    def is_closed(self) -> bool:
+        return self._closed
+
+    def _assert_open(self) -> None:
+        if self._closed:
+            raise RuntimeError("XyfraClient has been closed")
+
+    async def _get(self, path: str, params: Optional[dict[str, Any]] = None) -> Any:
+        response = await self._http.get(
+            f"{self._base_url}{path}",
+            headers=await self.headers(),
+            params=params,
+        )
+        response.raise_for_status()
+        content_type = response.headers.get("content-type", "")
+        if "application/json" in content_type:
+            return response.json()
+        return response.text
+
+    async def _post(self, path: str, body: Any) -> Any:
+        response = await self._http.post(
+            f"{self._base_url}{path}",
+            headers=await self.headers(),
+            json=body,
+        )
+        response.raise_for_status()
+        content_type = response.headers.get("content-type", "")
+        if "application/json" in content_type:
+            return response.json()
+        return response.text