orkaia 0.1.0__tar.gz

orkaia-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+*.egg-info/
+.env
+
+# Node
+node_modules/
+.next/
+.env.local
+.env*.local
+
+# OS
+.DS_Store
+*.log
+.vercel

orkaia-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: orkaia
+Version: 0.1.0
+Summary: Governance and audit SDK for AI agents
+Project-URL: Homepage, https://orka.ia.br
+Project-URL: Documentation, https://orka.ia.br/docs
+Project-URL: Repository, https://github.com/orka-runtime/orka-sdk
+License: MIT
+Keywords: agents,ai,audit,compliance,eu-ai-act,governance
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Description-Content-Type: text/markdown
+
+# orka-sdk
+
+Governance and audit SDK for AI agents. Add policy enforcement, immutable audit trails, and trust scoring to any agent with one decorator.
+
+## Install
+
+```bash
+pip install orka-sdk
+```
+
+## Quickstart
+
+```python
+import orka
+
+# Initialize once at startup (get your API key at orka.ia.br)
+orka.init(api_key="orka_your_key_here")
+
+# Wrap any agent function
+@orka.guard(agent_id="your-agent-uuid", task_type="summarize")
+def summarize(text: str) -> str:
+    return openai_client.chat(text)
+
+# Works with async too
+@orka.guard(agent_id="your-agent-uuid", task_type="financial_transfer", risk="HIGH")
+async def transfer_funds(amount: float, to_account: str) -> dict:
+    return await payment_api.transfer(amount, to_account)
+```
+
+That's it. Every call now:
+- ✅ Checks your X-Shield policies before executing
+- ✅ Logs to X-Ledger with immutable hash chain
+- ✅ Updates the agent's trust score
+- ✅ Blocks execution if policy denies it (raises `OrkaPolicyBlocked`)
+
+## Handle policy blocks
+
+```python
+from orka import OrkaPolicyBlocked
+
+try:
+    result = transfer_funds(10000, "acc_123")
+except OrkaPolicyBlocked as e:
+    print(f"Blocked: {e.reason}")
+    print(f"Policy: {e.policy_name}")
+```
+
+## Works with LangChain, CrewAI, any framework
+
+```python
+from langchain.agents import AgentExecutor
+import orka
+
+orka.init(api_key="orka_...")
+
+@orka.guard(agent_id="langchain-agent-uuid", task_type="web_search")
+def run_agent(query: str) -> str:
+    return agent_executor.invoke({"input": query})
+```
+
+## Never breaks your production code
+
+If Orka is unreachable, your agent continues running. Governance failures are silent — your users never see Orka errors.
+
+## Risk levels
+
+```python
+@orka.guard(agent_id="...", task_type="...", risk="HIGH")
+# EU AI Act risk classification: UNACCEPTABLE | HIGH | LIMITED | MINIMAL | NONE
+```
+
+## Environment variables
+
+```bash
+ORKA_API_KEY=orka_your_key
+ORKA_BASE_URL=https://orka-backend.onrender.com/api/v1  # optional
+```
+
+```python
+import os, orka
+orka.init(api_key=os.environ["ORKA_API_KEY"])
+```

orkaia-0.1.0/README.md

@@ -0,0 +1,82 @@
+# orka-sdk
+
+Governance and audit SDK for AI agents. Add policy enforcement, immutable audit trails, and trust scoring to any agent with one decorator.
+
+## Install
+
+```bash
+pip install orka-sdk
+```
+
+## Quickstart
+
+```python
+import orka
+
+# Initialize once at startup (get your API key at orka.ia.br)
+orka.init(api_key="orka_your_key_here")
+
+# Wrap any agent function
+@orka.guard(agent_id="your-agent-uuid", task_type="summarize")
+def summarize(text: str) -> str:
+    return openai_client.chat(text)
+
+# Works with async too
+@orka.guard(agent_id="your-agent-uuid", task_type="financial_transfer", risk="HIGH")
+async def transfer_funds(amount: float, to_account: str) -> dict:
+    return await payment_api.transfer(amount, to_account)
+```
+
+That's it. Every call now:
+- ✅ Checks your X-Shield policies before executing
+- ✅ Logs to X-Ledger with immutable hash chain
+- ✅ Updates the agent's trust score
+- ✅ Blocks execution if policy denies it (raises `OrkaPolicyBlocked`)
+
+## Handle policy blocks
+
+```python
+from orka import OrkaPolicyBlocked
+
+try:
+    result = transfer_funds(10000, "acc_123")
+except OrkaPolicyBlocked as e:
+    print(f"Blocked: {e.reason}")
+    print(f"Policy: {e.policy_name}")
+```
+
+## Works with LangChain, CrewAI, any framework
+
+```python
+from langchain.agents import AgentExecutor
+import orka
+
+orka.init(api_key="orka_...")
+
+@orka.guard(agent_id="langchain-agent-uuid", task_type="web_search")
+def run_agent(query: str) -> str:
+    return agent_executor.invoke({"input": query})
+```
+
+## Never breaks your production code
+
+If Orka is unreachable, your agent continues running. Governance failures are silent — your users never see Orka errors.
+
+## Risk levels
+
+```python
+@orka.guard(agent_id="...", task_type="...", risk="HIGH")
+# EU AI Act risk classification: UNACCEPTABLE | HIGH | LIMITED | MINIMAL | NONE
+```
+
+## Environment variables
+
+```bash
+ORKA_API_KEY=orka_your_key
+ORKA_BASE_URL=https://orka-backend.onrender.com/api/v1  # optional
+```
+
+```python
+import os, orka
+orka.init(api_key=os.environ["ORKA_API_KEY"])
+```

orkaia-0.1.0/orka/__init__.py

@@ -0,0 +1,25 @@
+from .client import OrkaClient
+from .decorators import guard
+from .exceptions import OrkaAuthError, OrkaConnectionError, OrkaPolicyBlocked
+
+_client: OrkaClient | None = None
+
+
+def init(api_key: str, base_url: str = "https://orka-backend.onrender.com/api/v1") -> OrkaClient:
+    """Initialize the Orka SDK. Call once at startup.
+
+    Args:
+        api_key: Your Orka API key (from dashboard → API Keys)
+        base_url: Orka backend URL (default: production)
+
+    Example:
+        import orka
+        orka.init(api_key="orka_your_key_here")
+    """
+    global _client
+    _client = OrkaClient(api_key=api_key, base_url=base_url)
+    return _client
+
+
+__all__ = ["init", "guard", "OrkaClient", "OrkaPolicyBlocked", "OrkaAuthError", "OrkaConnectionError"]
+__version__ = "0.1.0"

orkaia-0.1.0/orka/client.py

@@ -0,0 +1,91 @@
+import asyncio
+import time
+import uuid
+from typing import Any
+
+import httpx
+
+from .exceptions import OrkaAuthError, OrkaConnectionError, OrkaPolicyBlocked
+
+
+class OrkaClient:
+    def __init__(self, api_key: str, base_url: str = "https://orka-backend.onrender.com/api/v1"):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
+
+    def _sync_request(self, method: str, path: str, **kwargs) -> dict:
+        try:
+            with httpx.Client(timeout=10) as client:
+                r = client.request(method, f"{self.base_url}{path}", headers=self._headers, **kwargs)
+            if r.status_code == 401:
+                raise OrkaAuthError("Invalid API key")
+            if r.status_code == 403:
+                data = r.json()
+                raise OrkaPolicyBlocked(
+                    reason=data.get("reason", "Policy denied"),
+                    policy_name=data.get("policy_name"),
+                )
+            r.raise_for_status()
+            return r.json() if r.content else {}
+        except httpx.ConnectError as e:
+            raise OrkaConnectionError(f"Cannot reach Orka at {self.base_url}") from e
+
+    async def _async_request(self, method: str, path: str, **kwargs) -> dict:
+        try:
+            async with httpx.AsyncClient(timeout=10) as client:
+                r = await client.request(method, f"{self.base_url}{path}", headers=self._headers, **kwargs)
+            if r.status_code == 401:
+                raise OrkaAuthError("Invalid API key")
+            if r.status_code == 403:
+                data = r.json()
+                raise OrkaPolicyBlocked(
+                    reason=data.get("reason", "Policy denied"),
+                    policy_name=data.get("policy_name"),
+                )
+            r.raise_for_status()
+            return r.json() if r.content else {}
+        except httpx.ConnectError as e:
+            raise OrkaConnectionError(f"Cannot reach Orka at {self.base_url}") from e
+
+    def check_policy(self, agent_id: str, task_type: str, payload: dict) -> dict:
+        return self._sync_request("POST", "/xshield/check", json={
+            "agent_id": agent_id,
+            "task_type": task_type,
+            "payload": payload,
+        })
+
+    async def check_policy_async(self, agent_id: str, task_type: str, payload: dict) -> dict:
+        return await self._async_request("POST", "/xshield/check", json={
+            "agent_id": agent_id,
+            "task_type": task_type,
+            "payload": payload,
+        })
+
+    def log_execution(self, agent_id: str, task_type: str, status: str,
+                      input_payload: dict, output_payload: Any = None,
+                      error: str | None = None, duration_ms: int = 0) -> dict:
+        return self._sync_request("POST", "/executions", json={
+            "requesting_agent_id": agent_id,
+            "executing_agent_target": agent_id,
+            "task_type": task_type,
+            "task_payload": input_payload,
+            "status": status,
+            "output_payload": output_payload,
+            "error": error,
+            "duration_ms": duration_ms,
+        })
+
+    async def log_execution_async(self, agent_id: str, task_type: str, status: str,
+                                   input_payload: dict, output_payload: Any = None,
+                                   error: str | None = None, duration_ms: int = 0) -> dict:
+        return await self._async_request("POST", "/executions", json={
+            "requesting_agent_id": agent_id,
+            "executing_agent_target": agent_id,
+            "task_type": task_type,
+            "task_payload": input_payload,
+            "status": status,
+            "output_payload": output_payload,
+            "error": error,
+            "duration_ms": duration_ms,
+        })

orkaia-0.1.0/orka/decorators.py

@@ -0,0 +1,123 @@
+import asyncio
+import functools
+import time
+from typing import Any, Callable, Literal
+
+from .exceptions import OrkaPolicyBlocked
+
+RiskLevel = Literal["UNACCEPTABLE", "HIGH", "LIMITED", "MINIMAL", "NONE"]
+
+
+def guard(
+    agent_id: str,
+    task_type: str,
+    risk: RiskLevel = "MINIMAL",
+    block_on_policy: bool = True,
+):
+    """
+    Decorator that wraps any function with Orka governance.
+
+    - Checks X-Shield policies before execution
+    - Logs result to X-Ledger after execution
+    - Updates trust score automatically
+
+    Usage:
+        @orka.guard(agent_id="uuid", task_type="summarize")
+        def my_agent(text: str) -> str:
+            return llm.call(text)
+
+        @orka.guard(agent_id="uuid", task_type="transfer", risk="HIGH")
+        async def transfer_funds(amount: float) -> dict:
+            ...
+    """
+    from . import _client
+
+    def decorator(fn: Callable) -> Callable:
+        if asyncio.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def async_wrapper(*args, **kwargs):
+                if _client is None:
+                    return await fn(*args, **kwargs)
+
+                input_payload = {"args": list(args), "kwargs": kwargs}
+                start = time.monotonic()
+
+                try:
+                    await _client.check_policy_async(agent_id, task_type, input_payload)
+                except OrkaPolicyBlocked:
+                    if block_on_policy:
+                        raise
+                except Exception:
+                    pass  # never block execution due to Orka connectivity issues
+
+                error = None
+                output = None
+                status = "COMPLETED"
+                try:
+                    output = await fn(*args, **kwargs)
+                    return output
+                except Exception as e:
+                    error = str(e)
+                    status = "FAILED"
+                    raise
+                finally:
+                    duration_ms = int((time.monotonic() - start) * 1000)
+                    try:
+                        await _client.log_execution_async(
+                            agent_id=agent_id,
+                            task_type=task_type,
+                            status=status,
+                            input_payload=input_payload,
+                            output_payload=str(output) if output is not None else None,
+                            error=error,
+                            duration_ms=duration_ms,
+                        )
+                    except Exception:
+                        pass  # never break production code due to Orka
+
+            return async_wrapper
+        else:
+            @functools.wraps(fn)
+            def sync_wrapper(*args, **kwargs):
+                if _client is None:
+                    return fn(*args, **kwargs)
+
+                input_payload = {"args": list(args), "kwargs": kwargs}
+                start = time.monotonic()
+
+                try:
+                    _client.check_policy(agent_id, task_type, input_payload)
+                except OrkaPolicyBlocked:
+                    if block_on_policy:
+                        raise
+                except Exception:
+                    pass
+
+                error = None
+                output = None
+                status = "COMPLETED"
+                try:
+                    output = fn(*args, **kwargs)
+                    return output
+                except Exception as e:
+                    error = str(e)
+                    status = "FAILED"
+                    raise
+                finally:
+                    duration_ms = int((time.monotonic() - start) * 1000)
+                    try:
+                        _client.log_execution(
+                            agent_id=agent_id,
+                            task_type=task_type,
+                            status=status,
+                            input_payload=input_payload,
+                            output_payload=str(output) if output is not None else None,
+                            error=error,
+                            duration_ms=duration_ms,
+                        )
+                    except Exception:
+                        pass
+
+            return sync_wrapper
+
+    return decorator

orkaia-0.1.0/orka/exceptions.py

@@ -0,0 +1,14 @@
+class OrkaError(Exception):
+    pass
+
+class OrkaPolicyBlocked(OrkaError):
+    def __init__(self, reason: str, policy_name: str | None = None):
+        self.reason = reason
+        self.policy_name = policy_name
+        super().__init__(f"Blocked by policy: {reason}")
+
+class OrkaAuthError(OrkaError):
+    pass
+
+class OrkaConnectionError(OrkaError):
+    pass

orkaia-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "orkaia"
+version = "0.1.0"
+description = "Governance and audit SDK for AI agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["ai", "agents", "governance", "compliance", "audit", "eu-ai-act"]
+dependencies = [
+    "httpx>=0.27.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["orka"]
+
+[project.urls]
+Homepage = "https://orka.ia.br"
+Documentation = "https://orka.ia.br/docs"
+Repository = "https://github.com/orka-runtime/orka-sdk"