proxima-sdk 1.0.0__tar.gz

proxima_sdk-1.0.0/.gitignore

@@ -0,0 +1,35 @@
+# Synthetic data (generated, ~1.3GB)
+agents/supply-chain/demand-forecasting/data/synthetic/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+env/
+*.egg-info/
+
+# Environment
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Original reference docs (large PDFs, keep .md conversions only)
+docs/reference/daimler/*.pdf
+docs/reference/daimler/*.pptx
+docs/reference/daimler/*.docx
+docs/reference/daimler/*.msg
+docs/reference/daimler/*.xlsx
+docs/reference/daimler/*.zip
+docs/reference/daimler/SAP Proposal - Supply Chain RFP/*.pdf
+docs/reference/daimler/SAP Proposal - Supply Chain RFP/*.xlsx
+platform/data/secrets.json

proxima_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: proxima-sdk
+Version: 1.0.0
+Summary: Proxima AIP SDK — build AI agents on the Proxima Intelligence platform
+Project-URL: Homepage, https://proximaintel.com/aip
+Project-URL: Documentation, https://docs.proximaintel.com/sdk
+Project-URL: Repository, https://github.com/proximaintel/proxima-sdk
+Author-email: Proxima Intelligence <hello@proximaintel.com>
+License-Expression: MIT
+Keywords: agents,ai,enterprise,platform,proxima
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# Proxima SDK
+
+The official Python SDK for building AI agents on the **Proxima AIP** platform.
+
+## Install
+
+```bash
+pip install proxima-sdk
+```
+
+## Quick Start
+
+```python
+from proxima_sdk import PlatformContext
+
+def my_tool(params: dict, ctx: PlatformContext) -> dict:
+    # Access knowledge bases
+    data = ctx.knowledge.query("What invoices are overdue?")
+    
+    # Log actions for governance
+    ctx.governance.log_action("queried_invoices")
+    
+    return {"answer": data.answer, "citations": data.citations}
+```
+
+## Testing
+
+```python
+from proxima_sdk.testing import mock_context
+
+ctx = mock_context(sources={"invoices": [{"id": "INV-001", "amount": 5000}]})
+result = my_tool({"query": "overdue"}, ctx)
+```
+
+## Documentation
+
+Full docs at [docs.proximaintel.com/sdk](https://docs.proximaintel.com/sdk)

proxima_sdk-1.0.0/README.md

@@ -0,0 +1,37 @@
+# Proxima SDK
+
+The official Python SDK for building AI agents on the **Proxima AIP** platform.
+
+## Install
+
+```bash
+pip install proxima-sdk
+```
+
+## Quick Start
+
+```python
+from proxima_sdk import PlatformContext
+
+def my_tool(params: dict, ctx: PlatformContext) -> dict:
+    # Access knowledge bases
+    data = ctx.knowledge.query("What invoices are overdue?")
+    
+    # Log actions for governance
+    ctx.governance.log_action("queried_invoices")
+    
+    return {"answer": data.answer, "citations": data.citations}
+```
+
+## Testing
+
+```python
+from proxima_sdk.testing import mock_context
+
+ctx = mock_context(sources={"invoices": [{"id": "INV-001", "amount": 5000}]})
+result = my_tool({"query": "overdue"}, ctx)
+```
+
+## Documentation
+
+Full docs at [docs.proximaintel.com/sdk](https://docs.proximaintel.com/sdk)

proxima_sdk-1.0.0/__init__.py

@@ -0,0 +1,50 @@
+"""
+Proxima SDK
+
+The official SDK for building toolboxes on the Proxima Intelligence platform.
+Provides typed access to Knowledge, Governance, and Secrets services.
+
+Quick Start:
+    from proxima_sdk import PlatformContext
+
+    def my_tool(params: dict, ctx: PlatformContext) -> dict:
+        data = ctx.knowledge.read("invoices-gold")
+        ctx.governance.log_action("processed_invoice")
+        return {"count": len(data)}
+
+Testing:
+    from proxima_sdk.testing import mock_context
+    import pandas as pd
+
+    ctx = mock_context(sources={"invoices-gold": pd.DataFrame([...])})
+    result = my_tool({"id": "INV-001"}, ctx)
+"""
+
+from .context import PlatformContext
+from .knowledge import KnowledgeClient
+from .exceptions import (
+    ProximaError,
+    SourceNotFoundError,
+    ConnectionFailedError,
+    QueryFailedError,
+    SecretNotFoundError,
+    PermissionDeniedError,
+)
+from .types import SearchResult, SearchResults, Citation, QueryMetadata
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "PlatformContext",
+    "KnowledgeClient",
+    "ProximaError",
+    "SourceNotFoundError",
+    "ConnectionFailedError",
+    "QueryFailedError",
+    "SecretNotFoundError",
+    "PermissionDeniedError",
+    "SearchResult",
+    "SearchResults",
+    "Citation",
+    "QueryMetadata",
+]

proxima_sdk-1.0.0/context.py

@@ -0,0 +1,140 @@
+"""
+Proxima SDK — Platform Context
+
+The single entry point injected into every toolbox tool call.
+Contains everything the toolbox needs to interact with the platform.
+
+Usage:
+    from proxima_sdk import PlatformContext
+
+    def my_tool(params: dict, ctx: PlatformContext) -> dict:
+        data = ctx.knowledge.read("invoices-gold")
+        ctx.governance.log_action("validated_invoice", {"id": params["invoice_id"]})
+        return {"result": "pass"}
+"""
+
+from typing import Optional
+from .knowledge import KnowledgeClient
+
+
+class GovernanceClient:
+    """Log actions and events to the platform governance system."""
+
+    def __init__(self, gateway_url: str, agent_id: str):
+        self._gateway_url = gateway_url
+        self._agent_id = agent_id
+
+    def log_action(self, action: str, detail: dict | None = None):
+        """Log a toolbox action to governance (async fire-and-forget)."""
+        import httpx
+        try:
+            httpx.post(
+                f"{self._gateway_url}/governance/logs",
+                json={"agent_id": self._agent_id, "type": "action", "action": action, "detail": detail or {}},
+                timeout=5.0,
+            )
+        except Exception:
+            pass  # Non-blocking — governance logging should never break tool execution
+
+
+class SecretsClient:
+    """Resolve secrets from the platform secret store."""
+
+    def __init__(self, gateway_url: str):
+        self._gateway_url = gateway_url
+
+    def resolve(self, name: str) -> str:
+        """Resolve a secret value by name."""
+        import httpx
+        from .exceptions import SecretNotFoundError, ConnectionFailedError
+        try:
+            res = httpx.post(f"{self._gateway_url}/internal/secrets/resolve", json={"name": name}, timeout=5.0)
+            if res.status_code == 200:
+                return res.json().get("value", "")
+            elif res.status_code == 404:
+                raise SecretNotFoundError(name)
+            return ""
+        except httpx.ConnectError:
+            raise ConnectionFailedError("Gateway", self._gateway_url)
+
+
+class PlatformContext:
+    """
+    Injected into every tool call. Provides access to all platform services.
+
+    Constructed by the gateway from the agent's config and passed to the toolbox
+    in the request payload under the `_context` key.
+    """
+
+    def __init__(self, config: dict):
+        """
+        Args:
+            config: The _context dict injected by the gateway into tool call payloads.
+                {
+                    "gateway_url": "https://gateway.example.com",
+                    "agent_id": "invoice-intelligence",
+                    "knowledge_bases": ["finance-kb"],
+                    "sources": [...],
+                    "token": "<_context HMAC token for dev mode>",
+                    "identity": {
+                        "client_id": "<agent SP client_id>",
+                        "client_secret": "<agent SP secret>",
+                        "tenant_id": "<IdP tenant>",
+                        "audience": "api://<gateway app id>"
+                    }
+                }
+        """
+        self._config = config
+        self._knowledge: Optional[KnowledgeClient] = None
+        self._governance: Optional[GovernanceClient] = None
+        self._secrets: Optional[SecretsClient] = None
+
+    @property
+    def knowledge(self) -> KnowledgeClient:
+        """Access enterprise data through the gateway."""
+        if self._knowledge is None:
+            identity = self._config.get("identity", {})
+            self._knowledge = KnowledgeClient(
+                gateway_url=self._config.get("gateway_url", "http://localhost:9000"),
+                knowledge_bases=self._config.get("knowledge_bases", []),
+                sources=self._config.get("sources", []),
+                token=self._config.get("token", ""),
+                client_id=identity.get("client_id", ""),
+                client_secret=identity.get("client_secret", ""),
+                tenant_id=identity.get("tenant_id", ""),
+                audience=identity.get("audience", ""),
+            )
+        return self._knowledge
+
+    @property
+    def governance(self) -> GovernanceClient:
+        """Log actions to the platform governance system."""
+        if self._governance is None:
+            self._governance = GovernanceClient(
+                gateway_url=self._config.get("gateway_url", "http://localhost:9000"),
+                agent_id=self._config.get("agent_id", ""),
+            )
+        return self._governance
+
+    @property
+    def secrets(self) -> SecretsClient:
+        """Resolve secrets from the platform secret store."""
+        if self._secrets is None:
+            self._secrets = SecretsClient(
+                gateway_url=self._config.get("gateway_url", "http://localhost:9000"),
+            )
+        return self._secrets
+
+    @property
+    def agent_id(self) -> str:
+        return self._config.get("agent_id", "")
+
+    def close(self):
+        if self._knowledge:
+            self._knowledge.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

proxima_sdk-1.0.0/exceptions.py

@@ -0,0 +1,55 @@
+"""
+Proxima SDK — Exceptions
+
+Clear, typed exceptions for toolbox developers.
+Every error tells you what went wrong and how to fix it.
+"""
+
+
+class ProximaError(Exception):
+    """Base exception for all Proxima SDK errors."""
+    pass
+
+
+class SourceNotFoundError(ProximaError):
+    """Knowledge source not found in the connected knowledge base."""
+    def __init__(self, source_id: str):
+        super().__init__(f"Knowledge source '{source_id}' not found. Check that the source is registered and connected to the agent's knowledge base.")
+        self.source_id = source_id
+
+
+class ConnectionFailedError(ProximaError):
+    """Failed to connect to a platform service (Knowledge Service, Gateway)."""
+    def __init__(self, service: str, url: str, detail: str = ""):
+        super().__init__(f"Failed to connect to {service} at {url}. {detail}")
+        self.service = service
+        self.url = url
+
+
+class QueryFailedError(ProximaError):
+    """Knowledge query failed — source unreachable or credentials invalid."""
+    def __init__(self, source_id: str, detail: str = ""):
+        super().__init__(f"Query failed for source '{source_id}'. {detail}")
+        self.source_id = source_id
+
+
+class SecretNotFoundError(ProximaError):
+    """Secret not found in the platform secret store."""
+    def __init__(self, secret_name: str):
+        super().__init__(f"Secret '{secret_name}' not found in platform secret store.")
+        self.secret_name = secret_name
+
+
+class PermissionDeniedError(ProximaError):
+    """Insufficient permissions for the requested operation."""
+    def __init__(self, operation: str, detail: str = ""):
+        super().__init__(f"Permission denied for '{operation}'. {detail}")
+        self.operation = operation
+
+
+class TimeoutError(ProximaError):
+    """Request timed out."""
+    def __init__(self, service: str, timeout_seconds: float):
+        super().__init__(f"Request to {service} timed out after {timeout_seconds}s.")
+        self.service = service
+        self.timeout_seconds = timeout_seconds

proxima_sdk-1.0.0/knowledge.py

@@ -0,0 +1,269 @@
+"""
+Proxima SDK — Knowledge Client
+
+The primary interface for toolboxes to access enterprise data.
+All access goes through the gateway (authenticated, RBAC-enforced, governance-logged).
+
+The toolbox NEVER calls Knowledge Service directly. It authenticates to the gateway
+using the agent's service principal credentials and calls POST /knowledge/{base_id}/query.
+
+Usage:
+    from proxima_sdk import PlatformContext
+
+    def validate_invoice(params: dict, ctx: PlatformContext) -> dict:
+        results = ctx.knowledge.query("finance-kb", "overdue invoices over $50K")
+        invoices = ctx.knowledge.read("invoices-gold")
+        # ... business logic
+"""
+
+import os
+import time
+from typing import Optional
+
+import httpx
+import pandas as pd
+
+from .types import SearchResult, SearchResults, Citation, QueryMetadata
+from .exceptions import (
+    SourceNotFoundError,
+    ConnectionFailedError,
+    QueryFailedError,
+    TimeoutError as ProximaTimeoutError,
+)
+
+
+class KnowledgeClient:
+    """
+    Access enterprise data through the Proxima Gateway.
+
+    Provides:
+    - query(base_id, query) → dict (full KB query via gateway)
+    - read(source_id) → pd.DataFrame (structured data via gateway)
+    - search(source_id, query) → SearchResults (unstructured/vector via gateway)
+
+    All access authenticated, RBAC-enforced, governance-logged.
+    """
+
+    def __init__(self, gateway_url: str, knowledge_bases: list[str], sources: list[dict],
+                 token: str = "", client_id: str = "", client_secret: str = "",
+                 tenant_id: str = "", audience: str = "", timeout: float = 30.0):
+        """
+        Args:
+            gateway_url: Platform gateway URL (e.g., https://gateway.example.com)
+            knowledge_bases: List of KB IDs this agent can access
+            sources: Legacy source definitions (for backward compat with read())
+            token: Pre-obtained token (dev mode / _context HMAC)
+            client_id: Agent SP client ID (production - client credentials flow)
+            client_secret: Agent SP client secret (production)
+            tenant_id: IdP tenant ID (for token endpoint)
+            audience: Gateway audience (for token scope)
+            timeout: HTTP timeout in seconds
+        """
+        self._gateway_url = gateway_url.rstrip("/")
+        self._knowledge_bases = knowledge_bases
+        self._sources = {s["id"]: s for s in sources}
+        self._timeout = timeout
+        self._cache: dict[str, pd.DataFrame] = {}
+
+        # Auth
+        self._token = token
+        self._client_id = client_id or os.getenv("PROXIMA_AGENT_CLIENT_ID", "")
+        self._client_secret = client_secret or os.getenv("PROXIMA_AGENT_CLIENT_SECRET", "")
+        self._tenant_id = tenant_id or os.getenv("PROXIMA_TENANT_ID", "")
+        self._audience = audience or os.getenv("PROXIMA_AUDIENCE", "")
+        self._token_expires_at: float = 0
+
+    def _get_token(self) -> str:
+        """Get a valid access token. Uses cached token if not expired."""
+        # If we have a pre-set token (dev mode / _context), use it
+        if self._token and not self._client_id:
+            return self._token
+
+        # Check if cached token is still valid (with 60s buffer)
+        if self._token and time.time() < self._token_expires_at - 60:
+            return self._token
+
+        # Client credentials flow
+        if not self._client_id or not self._client_secret or not self._tenant_id:
+            return self._token  # Fall back to whatever we have
+
+        token_url = f"https://login.microsoftonline.com/{self._tenant_id}/oauth2/v2.0/token"
+        scope = f"{self._audience}/.default" if self._audience else ""
+
+        try:
+            res = httpx.post(token_url, data={
+                "client_id": self._client_id,
+                "client_secret": self._client_secret,
+                "scope": scope,
+                "grant_type": "client_credentials",
+            }, timeout=10.0)
+
+            if res.status_code == 200:
+                data = res.json()
+                self._token = data["access_token"]
+                self._token_expires_at = time.time() + data.get("expires_in", 3600)
+                return self._token
+        except Exception:
+            pass
+
+        return self._token
+
+    def _headers(self) -> dict:
+        """Build request headers with auth token."""
+        token = self._get_token()
+        headers = {"Content-Type": "application/json"}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        return headers
+
+    def query(self, base_id: str, query: str, top_k: int = 5) -> dict:
+        """
+        Query a knowledge base through the gateway.
+
+        Args:
+            base_id: Knowledge base ID
+            query: Natural language query
+            top_k: Number of results
+
+        Returns:
+            dict with results, citations, metadata
+
+        Raises:
+            QueryFailedError: Gateway returned an error
+            ConnectionFailedError: Gateway unreachable
+        """
+        try:
+            start = time.time()
+            res = httpx.post(
+                f"{self._gateway_url}/knowledge/{base_id}/query",
+                json={"query": query, "top_k": top_k},
+                headers=self._headers(),
+                timeout=self._timeout,
+            )
+            duration = int((time.time() - start) * 1000)
+
+            if res.status_code == 403:
+                raise QueryFailedError(base_id, "Access denied. Check role_assignments for this agent.")
+            if res.status_code == 404:
+                raise SourceNotFoundError(base_id)
+            if res.status_code != 200:
+                raise QueryFailedError(base_id, f"HTTP {res.status_code}: {res.text[:200]}")
+
+            return res.json()
+
+        except httpx.ConnectError:
+            raise ConnectionFailedError("Gateway", self._gateway_url, "Gateway unreachable.")
+        except httpx.TimeoutException:
+            raise ProximaTimeoutError("Gateway", self._timeout)
+
+    def read(self, source_id: str, use_cache: bool = True) -> pd.DataFrame:
+        """
+        Read structured data from a knowledge source.
+        Routes through gateway /knowledge/{base_id}/query.
+
+        Args:
+            source_id: ID of the registered knowledge source
+            use_cache: If True, returns cached data within same tool execution
+
+        Returns:
+            pd.DataFrame with the source data
+        """
+        if use_cache and source_id in self._cache:
+            return self._cache[source_id]
+
+        # Find which KB contains this source
+        # For now, query the first available KB with the source name
+        base_id = self._knowledge_bases[0] if self._knowledge_bases else "default"
+
+        result = self.query(base_id, f"read all data from {source_id}", top_k=1)
+
+        # Parse results into DataFrame
+        for r in result.get("results", []):
+            content = r.get("content", "")
+            if "rows" in content and "|" in content:
+                # Try to parse markdown table
+                try:
+                    lines = [l.strip() for l in content.split("\n") if l.strip() and "|" in l]
+                    if len(lines) >= 3:
+                        headers = [h.strip() for h in lines[0].split("|") if h.strip()]
+                        rows = []
+                        for line in lines[2:]:
+                            if "---" in line or "..." in line:
+                                continue
+                            row = [c.strip() for c in line.split("|") if c.strip()]
+                            if len(row) == len(headers):
+                                rows.append(row)
+                        if rows:
+                            df = pd.DataFrame(rows, columns=headers)
+                            if use_cache:
+                                self._cache[source_id] = df
+                            return df
+                except Exception:
+                    pass
+
+        # Fallback: return empty DataFrame
+        df = pd.DataFrame()
+        if use_cache:
+            self._cache[source_id] = df
+        return df
+
+    def search(self, source_id: str, query: str, top_k: int = 5) -> SearchResults:
+        """
+        Search knowledge via gateway.
+
+        Args:
+            source_id: Source or KB ID to search
+            query: Natural language search query
+            top_k: Number of results
+
+        Returns:
+            SearchResults with content and citations
+        """
+        base_id = source_id if source_id in self._knowledge_bases else (self._knowledge_bases[0] if self._knowledge_bases else source_id)
+
+        result = self.query(base_id, query, top_k=top_k)
+
+        results = []
+        for r in result.get("results", []):
+            citation_data = r.get("citation", {})
+            results.append(SearchResult(
+                content=r.get("content", ""),
+                citation=Citation(
+                    source=citation_data.get("source", ""),
+                    title=citation_data.get("title", ""),
+                    confidence=citation_data.get("confidence", 0.0),
+                    metadata=citation_data,
+                ),
+                score=0.0,
+            ))
+
+        return SearchResults(
+            results=results,
+            query=query,
+            sources_queried=result.get("metadata", {}).get("sources_queried", 0),
+            duration_ms=result.get("metadata", {}).get("duration_ms", 0),
+        )
+
+    @property
+    def available_bases(self) -> list[str]:
+        """List KB IDs available to this agent."""
+        return list(self._knowledge_bases)
+
+    @property
+    def available_sources(self) -> list[str]:
+        """List source IDs (legacy compat)."""
+        return list(self._sources.keys())
+
+    def clear_cache(self):
+        """Clear the in-memory read cache."""
+        self._cache.clear()
+
+    def close(self):
+        """No persistent client to close (stateless HTTP calls)."""
+        pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

proxima_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "proxima-sdk"
+version = "1.0.0"
+description = "Proxima AIP SDK — build AI agents on the Proxima Intelligence platform"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Proxima Intelligence", email = "hello@proximaintel.com" },
+]
+keywords = ["ai", "agents", "platform", "enterprise", "proxima"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://proximaintel.com/aip"
+Documentation = "https://docs.proximaintel.com/sdk"
+Repository = "https://github.com/proximaintel/proxima-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["proxima_sdk"]

proxima_sdk-1.0.0/testing.py

@@ -0,0 +1,90 @@
+"""
+Proxima SDK — Testing Utilities
+
+Mock clients for unit testing toolbox code without the full platform stack.
+
+Usage:
+    from proxima_sdk.testing import mock_context
+    import pandas as pd
+
+    def test_validate_invoice():
+        ctx = mock_context(sources={
+            "invoices-gold": pd.DataFrame([{"invoice_id": "INV-001", "amount": 1000}]),
+            "vendors-gold": pd.DataFrame([{"vendor_id": "V-001", "name": "Acme"}]),
+        })
+        result = validate_invoice({"invoice_id": "INV-001"}, ctx)
+        assert result["validation"] == "pass"
+"""
+
+from typing import Optional
+import pandas as pd
+from .types import SearchResult, SearchResults, Citation
+from .context import PlatformContext
+
+
+class MockKnowledgeClient:
+    """Mock knowledge client for testing. Returns pre-loaded DataFrames."""
+
+    def __init__(self, sources: dict[str, pd.DataFrame] | None = None, search_results: dict[str, list[dict]] | None = None):
+        self._sources = sources or {}
+        self._search_results = search_results or {}
+
+    def read(self, source_id: str, use_cache: bool = True) -> pd.DataFrame:
+        if source_id not in self._sources:
+            from .exceptions import SourceNotFoundError
+            raise SourceNotFoundError(source_id)
+        return self._sources[source_id]
+
+    def search(self, source_id: str, query: str, top_k: int = 5) -> SearchResults:
+        results = self._search_results.get(source_id, [])
+        return SearchResults(
+            results=[SearchResult(content=r.get("content", ""), citation=Citation(source=source_id, title=r.get("title", "")), score=r.get("score", 0.9)) for r in results[:top_k]],
+            query=query,
+            sources_queried=1,
+            duration_ms=1,
+        )
+
+    @property
+    def available_sources(self) -> list[str]:
+        return list(self._sources.keys())
+
+    def clear_cache(self):
+        pass
+
+    def close(self):
+        pass
+
+
+class MockGovernanceClient:
+    """Mock governance client — records actions for assertion."""
+
+    def __init__(self):
+        self.actions: list[dict] = []
+
+    def log_action(self, action: str, detail: dict | None = None):
+        self.actions.append({"action": action, "detail": detail or {}})
+
+
+class MockSecretsClient:
+    """Mock secrets client — returns pre-configured values."""
+
+    def __init__(self, secrets: dict[str, str] | None = None):
+        self._secrets = secrets or {}
+
+    def resolve(self, name: str) -> str:
+        return self._secrets.get(name, "")
+
+
+class MockPlatformContext(PlatformContext):
+    """Mock platform context for testing."""
+
+    def __init__(self, sources: dict[str, pd.DataFrame] | None = None, search_results: dict[str, list[dict]] | None = None, secrets: dict[str, str] | None = None):
+        super().__init__({"agent_id": "test-agent", "knowledge_service_url": "", "gateway_url": "", "sources": []})
+        self._knowledge = MockKnowledgeClient(sources=sources, search_results=search_results)
+        self._governance = MockGovernanceClient()
+        self._secrets = MockSecretsClient(secrets=secrets)
+
+
+def mock_context(sources: dict[str, pd.DataFrame] | None = None, search_results: dict[str, list[dict]] | None = None, secrets: dict[str, str] | None = None) -> MockPlatformContext:
+    """Create a mock PlatformContext for unit testing."""
+    return MockPlatformContext(sources=sources, search_results=search_results, secrets=secrets)

proxima_sdk-1.0.0/types.py

@@ -0,0 +1,62 @@
+"""
+Proxima SDK — Types
+
+Typed data structures for toolbox developers.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class Citation:
+    """Source attribution for a knowledge retrieval result."""
+    source: str
+    title: str = ""
+    section: str = ""
+    page: Optional[int] = None
+    url: str = ""
+    confidence: float = 0.0
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class SearchResult:
+    """A single result from a knowledge search (unstructured/vector)."""
+    content: str
+    citation: Citation
+    score: float = 0.0
+
+
+@dataclass
+class SearchResults:
+    """Collection of search results with metadata."""
+    results: list[SearchResult]
+    query: str
+    sources_queried: int = 0
+    duration_ms: int = 0
+
+    def __len__(self) -> int:
+        return len(self.results)
+
+    def __iter__(self):
+        return iter(self.results)
+
+    @property
+    def top(self) -> Optional[SearchResult]:
+        return self.results[0] if self.results else None
+
+    @property
+    def contents(self) -> list[str]:
+        return [r.content for r in self.results]
+
+
+@dataclass
+class QueryMetadata:
+    """Metadata about a structured data query."""
+    source: str
+    row_count: int
+    columns: list[str]
+    query_executed: str = ""
+    duration_ms: int = 0
+    cached: bool = False