cadreen-sdk 0.1.0__tar.gz

cadreen_sdk-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+*.pyc
+__pycache__/
+.env
+.DS_Store

cadreen_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: cadreen-sdk
+Version: 0.1.0
+Summary: Python SDK for Cadreen — intelligence-native automation infrastructure
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx-sse>=0.4
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'

cadreen_sdk-0.1.0/README.md

@@ -0,0 +1,93 @@
+# cadreen-sdk
+
+Python SDK for Cadreen — intelligence-native automation infrastructure.
+
+## Install
+
+```bash
+pip install cadreen-sdk
+```
+
+## Quick Start
+
+```python
+import os
+import asyncio
+from cadreen import Cadreen
+
+cadreen = Cadreen(api_key=os.environ["CADREEN_API_KEY"])
+
+async def main():
+    # Intent — the main entry point
+    result = await cadreen.intent(
+        "Handle a refund request for invoice inv_123",
+        domain="support",
+    )
+    print(result.explain())
+
+    # Discriminated union with match/case
+    match result.type:
+        case "direct":
+            print(result.message.content)
+        case "clarify":
+            for q in result.questions:
+                print(q)
+        case "execution":
+            async for event in cadreen.executions.stream(result.execution["id"]):
+                print(event.type, event.data)
+        case "blocked":
+            print(result.policy["reason"])
+        case "connect_required":
+            print(result.connection["endpoint"])
+
+    # Memory — store knowledge
+    await cadreen.memory.remember(
+        type="reference",
+        content={"text": "GDPR Article 17...", "title": "GDPR Art. 17"},
+        authority=10,
+    )
+
+    # Policies — governance guardrails
+    await cadreen.policies.require_approval("Refunds over $500 require human approval")
+
+    # Traces — intelligence observability
+    trace = await cadreen.traces.get(result.trace_id)
+    explanation = trace.explain()
+    print(explanation.summary)
+
+    # Connections — register external services
+    await cadreen.connections.register_openapi(
+        name="internal-erp",
+        spec_url="https://erp.example.com/openapi.json",
+    )
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+cadreen = Cadreen(
+    api_key="...",
+    base_url="https://accomplishanything.today",  # default, configurable
+    max_retries=2,      # default 2
+    timeout=30,          # default 30s
+    profile="lean",     # optional: "lean" | "audit" | "full" (default "full")
+)
+```
+
+### Response Profiles
+
+Control how much intelligence metadata you get back:
+
+| Profile | What you get | Use when |
+|---------|-------------|----------|
+| `"full"` (default) | Full intelligence envelope | You want full transparency |
+| `"audit"` | Only governance decision + confidence + blocking gaps | You need to react to gates |
+| `"lean"` | No envelope. Just `trace_id` | Hot-looping, minimal payload |
+
+## Requirements
+
+- Python 3.10+
+- httpx >= 0.25
+- httpx-sse >= 0.4

cadreen_sdk-0.1.0/cadreen/__init__.py

@@ -0,0 +1,208 @@
+from .client import CadreenError
+from .types import (
+    CadreenConfig,
+    HealthStatus,
+    ConnectorType,
+    CapabilitySource,
+    TransportType,
+    EscalationStatus,
+    CredentialType,
+    AtomScope,
+    AtomType,
+    ErrorCategory,
+    RecoveryStrategyType,
+    StackItemSource,
+    StackItemStatus,
+    GovernanceDecisionType,
+    RecoveryStatus,
+    IntentMode,
+    Pagination,
+    Pathway,
+    ConnectionGroup,
+    ListConnectionsResponse,
+    AtomContent,
+    Atom,
+    CreateMemoryResponse,
+    SearchMemoryResponse,
+    Policy,
+    PolicyBundle,
+    GovernanceDecision,
+    EvaluatePolicyResponse,
+    CreatePolicyResponse,
+    ConfirmPolicyResponse,
+    Escalation,
+    ListEscalationsResponse,
+    CredentialMetadata,
+    ListCredentialsResponse,
+    CapabilityMatch,
+    ListCapabilitiesResponse,
+    ListPoliciesResponse,
+    Gap,
+    Outcome,
+    Assessment,
+    PolicyRecommendation,
+    StackItem,
+    StackBreakdown,
+    CapabilityTrace,
+    ReasoningTrace,
+    MemoryTrace,
+    GovernanceTrace,
+    HumilityTrace,
+    ProcessTrace,
+    IntelligenceMeta,
+    IntelligenceTraceEntry,
+    ListIntelligenceResponse,
+    IntelligenceStats,
+    IntentMessage,
+    IntentContext,
+    IntentRequest,
+    ResponseMessage,
+    TraceExplain,
+    ExecutionEvent,
+    ExecutionStatus,
+    IntentResult,
+    IntentResultType,
+    DirectResult,
+    ClarifyResult,
+    ExecutionResult,
+    BlockedResult,
+    ConnectRequiredResult,
+    RegisterOpenAPIRequest,
+    RegisterOpenAPIResponse,
+    RegisterMCPRequest,
+    RegisterMCPResponse,
+    InstallComposioRequest,
+    SearchMemoryRequest,
+    RememberRequest,
+    CreatePolicyRequest,
+    EvaluatePolicyRequest,
+    RequestOptions,
+    ConnectResult,
+    ConnectResultType,
+    ConnectPrebuiltDetail,
+    ConnectSchemaRequiredDetail,
+    ConnectManualDetail,
+    ConnectPathway,
+    ConnectUnknownDetail,
+    intent_status,
+    SetupRequest,
+    SetupResult,
+    SetupConnection,
+    SetupCredential,
+    SetupMemory,
+    SetupPolicy,
+    SetupConnectionResult,
+    SetupCredentialResult,
+    SetupMemoryResult,
+    SetupPolicyResult,
+)
+
+from .client import HttpClient
+from .resources.intent import IntentResource
+from .resources.memory import MemoryResource
+from .resources.policies import PoliciesResource
+from .resources.connections import ConnectionsResource
+from .resources.traces import TracesResource
+from .resources.executions import ExecutionsResource
+from .resources.guardrails import GuardrailsResource
+from .redaction import redact_string, redact_trace, redact_messages, RedactOptions
+from .telemetry import TelemetryProvider, TelemetrySpan, TelemetryMeter, OpenTelemetryAdapter, NoOpProvider
+
+
+class Cadreen:
+    def __init__(self, api_key: str, base_url: str | None = None, max_retries: int | None = None, timeout: int | None = None, *, sandbox: bool = False, fixtures: dict | None = None) -> None:
+        config = CadreenConfig(api_key=api_key, base_url=base_url, max_retries=max_retries, timeout=timeout, sandbox=sandbox, fixtures=fixtures)
+        self._client = HttpClient(config)
+        self.intent = IntentResource(self._client)
+        self.memory = MemoryResource(self._client)
+        self.policies = PoliciesResource(self._client)
+        self.connections = ConnectionsResource(self._client)
+        self.traces = TracesResource(self._client)
+        self.executions = ExecutionsResource(self._client)
+        self.guardrails = GuardrailsResource(self.policies)
+
+    async def invoke(self, request: IntentRequest) -> IntentResult:
+        return await self.intent.invoke(request)
+
+    async def ask(
+        self,
+        prompt: str,
+        *,
+        conversation_id: str | None = None,
+        context: IntentContext | None = None,
+        stream: bool | None = None,
+    ) -> IntentResult:
+        return await self.intent.invoke(
+            IntentRequest(
+                messages=[IntentMessage(role="user", content=prompt)],
+                mode="chat",
+                conversation_id=conversation_id,
+                context=context,
+                stream=stream,
+            )
+        )
+
+    async def act(
+        self,
+        prompt: str,
+        *,
+        conversation_id: str | None = None,
+        context: IntentContext | None = None,
+        stream: bool | None = None,
+    ) -> IntentResult:
+        return await self.intent.invoke(
+            IntentRequest(
+                messages=[IntentMessage(role="user", content=prompt)],
+                mode="execution",
+                conversation_id=conversation_id,
+                context=context,
+                stream=stream,
+            )
+        )
+
+    async def remember(
+        self,
+        type: str,
+        content: dict,
+        *,
+        domain: str | None = None,
+        scope: str | None = None,
+        authority: int | None = None,
+        tags: list[str] | None = None,
+    ) -> CreateMemoryResponse:
+        return await self.memory.remember(type, content, domain=domain, scope=scope, authority=authority, tags=tags)
+
+    async def context(self, request: SearchMemoryRequest) -> SearchMemoryResponse:
+        return await self.memory.search(request)
+
+    async def connect(self, capability: str) -> ConnectResult:
+        return await self.connections.connect(capability)
+
+    async def setup(self, request: SetupRequest) -> SetupResult:
+        payload: dict = {}
+        if request.connections:
+            payload["connections"] = [{"capability": c.capability} for c in request.connections]
+        if request.credentials:
+            payload["credentials"] = [{"provider": c.provider, "name": c.name, "key_data": c.key_data} for c in request.credentials]
+        if request.memory:
+            mem_items = []
+            for m in request.memory:
+                item: dict = {"content": m.content}
+                if m.type:
+                    item["type"] = m.type
+                if m.domain:
+                    item["domain"] = m.domain
+                if m.tags:
+                    item["tags"] = m.tags
+                if m.authority:
+                    item["authority"] = m.authority
+                mem_items.append(item)
+            payload["memory"] = mem_items
+        if request.policies:
+            payload["policies"] = [{"name": p.name, "rule": p.rule, "description": p.description, "severity": p.severity} for p in request.policies]
+        resp = await self._client.post("/api/v1/cadreen/setup", json=payload)
+        conns = [SetupConnectionResult(capability=c["capability"], status=c["status"], detail=c.get("detail"), error=c.get("error")) for c in resp.get("connections", [])]
+        creds = [SetupCredentialResult(provider=c["provider"], name=c.get("name", ""), status=c["status"], id=c.get("id"), error=c.get("error")) for c in resp.get("credentials", [])]
+        mems = [SetupMemoryResult(id=m["id"], type=m["type"], classified=m["classified"], status=m["status"], kind=m.get("kind"), error=m.get("error")) for m in resp.get("memory", [])]
+        pols = [SetupPolicyResult(name=p["name"], status=p["status"], id=p.get("id"), error=p.get("error")) for p in resp.get("policies", [])]
+        return SetupResult(connections=conns, credentials=creds, memory=mems, policies=pols, applied=resp["applied"], failed=resp["failed"])

cadreen_sdk-0.1.0/cadreen/client.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Optional
+from urllib.parse import urlencode, quote
+
+import httpx
+from httpx_sse import aconnect_sse
+
+from .types import CadreenConfig, RequestOptions
+from .telemetry import TelemetryHooks, NoOpProvider
+
+
+class CadreenError(Exception):
+    status: int
+    code: str
+    error_type: str
+    details: Optional[list[dict[str, str]]]
+    intelligence: Optional[Any]
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        error_type: str,
+        message: str,
+        details: Optional[list[dict[str, str]]] = None,
+        intelligence: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.error_type = error_type
+        self.details = details
+        self.intelligence = intelligence
+
+
+DEFAULT_BASE_URL = "https://accomplishanything.today"
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_TIMEOUT = 30
+RETRYABLE_STATUS_CODES = {408, 429, 502, 503, 504}
+IDEMPOTENT_METHODS = {"GET", "PUT"}
+
+
+def _build_query_string(params: dict[str, Any]) -> str:
+    parts: list[str] = []
+    for key, value in params.items():
+        if value is not None and value != "":
+            parts.append(f"{quote(key)}={quote(str(value))}")
+    return f"?{'&'.join(parts)}" if parts else ""
+
+
+class HttpClient:
+    def __init__(self, config: CadreenConfig) -> None:
+        self._base_url = (config.base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._api_key = config.api_key
+        self._max_retries = config.max_retries if config.max_retries is not None else DEFAULT_MAX_RETRIES
+        self._timeout = config.timeout if config.timeout is not None else DEFAULT_TIMEOUT
+        self._sandbox = getattr(config, "sandbox", False) or False
+        self._fixtures = getattr(config, "fixtures", None) or {}
+        self._profile = getattr(config, "profile", None) or "full"
+        provider = config.telemetry if config.telemetry else NoOpProvider()
+        self._telemetry = TelemetryHooks(provider=provider)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Any] = None,
+        options: Optional[RequestOptions] = None,
+    ) -> Any:
+        if self._sandbox:
+            fixture_key = f"{method} {path}"
+            if fixture_key in self._fixtures:
+                return self._fixtures[fixture_key]
+            if path in self._fixtures:
+                return self._fixtures[path]
+            raise CadreenError(404, "not_found", "not_found", f"No fixture for {fixture_key}. Provide fixtures via CadreenConfig.fixtures keyed by 'METHOD /path' or '/path'.")
+
+        url = f"{self._base_url}{path}"
+        span = self._telemetry.on_request_start(method, path)
+        start_time = time.monotonic()
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": f'application/json; profile="{self._profile}"',
+            **(options.headers if options and options.headers else {}),
+        }
+
+        if method in ("POST", "PUT", "PATCH"):
+            headers["Idempotency-Key"] = (
+                (options.idempotency_key if options else None) or str(uuid.uuid4())
+            )
+
+        is_idempotent = method in IDEMPOTENT_METHODS or "Idempotency-Key" in headers
+        max_attempts = (self._max_retries + 1) if is_idempotent else 1
+
+        last_error: Optional[CadreenError] = None
+
+        for attempt in range(max_attempts):
+            if attempt > 0:
+                import asyncio
+                delay = min(1.0 * (2 ** (attempt - 1)), 10.0)
+                self._telemetry.on_retry(method, path, attempt)
+                await asyncio.sleep(delay)
+
+            try:
+                async with httpx.AsyncClient(timeout=self._timeout) as client:
+                    response = await client.request(
+                        method=method,
+                        url=url,
+                        headers=headers,
+                        json=body if body is not None else None,
+                    )
+
+                if not response.is_success:
+                    error_body: Optional[dict[str, Any]] = None
+                    try:
+                        error_body = response.json()
+                    except Exception:
+                        pass
+
+                    err = CadreenError(
+                        status=response.status_code,
+                        code=error_body.get("error", {}).get("code", "unknown") if error_body else "unknown",
+                        error_type=error_body.get("error", {}).get("type", "error") if error_body else "error",
+                        message=error_body.get("error", {}).get("message", response.text) if error_body else response.text,
+                        details=error_body.get("error", {}).get("details") if error_body else None,
+                        intelligence=error_body.get("intelligence") if error_body else None,
+                    )
+
+                    if response.status_code in RETRYABLE_STATUS_CODES and is_idempotent and attempt < max_attempts - 1:
+                        last_error = err
+                        continue
+
+                    self._telemetry.on_error(span, err.code, err.error_type)
+                    raise err
+
+                if response.status_code == 204:
+                    duration_ms = (time.monotonic() - start_time) * 1000
+                    self._telemetry.on_request_end(span, method, path, 204, duration_ms)
+                    return None
+
+                duration_ms = (time.monotonic() - start_time) * 1000
+                self._telemetry.on_request_end(span, method, path, response.status_code, duration_ms)
+                return response.json()
+
+            except CadreenError:
+                raise
+            except httpx.TimeoutException:
+                if is_idempotent and attempt < max_attempts - 1:
+                    last_error = CadreenError(408, "timeout", "timeout", "Request timed out")
+                    continue
+                raise CadreenError(408, "timeout", "timeout", "Request timed out")
+            except Exception as exc:
+                if is_idempotent and attempt < max_attempts - 1:
+                    last_error = CadreenError(0, "network_error", "network", str(exc))
+                    continue
+                raise CadreenError(0, "network_error", "network", str(exc))
+
+        raise last_error or CadreenError(0, "network_error", "network", "Request failed after retries")
+
+    async def get(self, path: str, params: Optional[dict[str, Any]] = None) -> Any:
+        qs = _build_query_string(params) if params else ""
+        return await self.request("GET", f"{path}{qs}")
+
+    async def post(self, path: str, body: Optional[Any] = None, options: Optional[RequestOptions] = None) -> Any:
+        return await self.request("POST", path, body, options)
+
+    async def put(self, path: str, body: Optional[Any] = None, options: Optional[RequestOptions] = None) -> Any:
+        return await self.request("PUT", path, body, options)
+
+    async def delete(self, path: str) -> Any:
+        return await self.request("DELETE", path)
+
+    async def stream(self, path: str) -> Any:
+        url = f"{self._base_url}{path}"
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "text/event-stream",
+        }
+
+        async with httpx.AsyncClient(timeout=None) as client:
+            async with aconnect_sse(client, "GET", url, headers=headers) as event_source:
+                async for event in event_source.aiter_sse():
+                    try:
+                        import json
+                        data = json.loads(event.data)
+                    except Exception:
+                        data = {"raw": event.data}
+                    yield {"type": event.event or "message", "data": data}

cadreen_sdk-0.1.0/cadreen/redaction.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import re
+from dataclasses import replace
+from typing import Any, Sequence
+
+_EMAIL_RE = re.compile(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}")
+_PHONE_RE = re.compile(r"(?:\+?\d{1,3}[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}")
+_UUID_RE = re.compile(r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", re.IGNORECASE)
+_API_KEY_RE = re.compile(r"sk_[a-zA-Z]+_[a-zA-Z0-9]{8,}")
+_IP_RE = re.compile(r"\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b")
+
+
+class RedactOptions:
+    def __init__(
+        self,
+        *,
+        preserve_uuids: bool = False,
+        keys_to_redact: Sequence[str] | None = None,
+    ) -> None:
+        self.preserve_uuids = preserve_uuids
+        self.keys_to_redact = list(keys_to_redact) if keys_to_redact else [
+            "content", "message", "text", "body", "email", "phone", "address", "name",
+        ]
+
+
+def redact_string(text: str, options: RedactOptions | None = None) -> str:
+    opts = options or RedactOptions()
+    result = _EMAIL_RE.sub("[email]", text)
+    result = _PHONE_RE.sub("[phone]", result)
+    result = _API_KEY_RE.sub("[api_key]", result)
+    result = _IP_RE.sub("[ip]", result)
+    if not opts.preserve_uuids:
+        result = _UUID_RE.sub("[id]", result)
+    return result
+
+
+def redact_value(value: Any, options: RedactOptions | None = None) -> Any:
+    opts = options or RedactOptions()
+    if isinstance(value, str):
+        return redact_string(value, opts)
+    if isinstance(value, list):
+        return [redact_value(v, opts) for v in value]
+    if isinstance(value, dict):
+        result: dict[str, Any] = {}
+        for key, val in value.items():
+            if key.lower() in opts.keys_to_redact and isinstance(val, str):
+                result[key] = redact_string(val, opts)
+            else:
+                result[key] = redact_value(val, opts)
+        return result
+    if hasattr(value, "__dict__") and hasattr(value, "__dataclass_fields__"):
+        changes: dict[str, Any] = {}
+        for field_name in value.__dataclass_fields__:
+            field_val = getattr(value, field_name)
+            if isinstance(field_val, str) and field_name.lower() in opts.keys_to_redact:
+                changes[field_name] = redact_string(field_val, opts)
+            elif isinstance(field_val, (list, dict)) or hasattr(field_val, "__dataclass_fields__"):
+                changes[field_name] = redact_value(field_val, opts)
+            elif isinstance(field_val, str):
+                changes[field_name] = redact_string(field_val, opts)
+        return replace(value, **changes)
+    return value
+
+
+def redact_trace(intel: Any, options: RedactOptions | None = None) -> Any:
+    return redact_value(intel, options)
+
+
+def redact_messages(messages: Sequence[Any], options: RedactOptions | None = None) -> list[Any]:
+    return [redact_value(msg, options) for msg in messages]