copilotkit-intelligence-runtime 0.1.0__py3-none-any.whl

copilotkit_intelligence/entitlements.py

@@ -0,0 +1,142 @@
+"""Typed Runtime entitlement responses and strict platform normalization."""
+
+import math
+from typing import Any, Literal, NotRequired, TypedDict
+
+
+class RuntimeEntitlement(TypedDict):
+    """The Runtime grant and its platform-defined features and limits."""
+
+    active: bool
+    source: Literal[
+        "managedOrgSubscription", "selfHostedDeploymentLicense", "awsMarketplaceDeploymentLicense"
+    ]
+    features: dict[str, bool]
+    limits: dict[str, float]
+    planCode: NotRequired[str]
+    entitlementSource: NotRequired[str]
+
+
+class RuntimeEntitlementProblem(TypedDict):
+    """A structured reason why the platform cannot supply a ready grant."""
+
+    code: str
+    message: str
+    retryable: bool
+    requestId: NotRequired[str]
+    traceId: NotRequired[str]
+
+
+class RuntimeEntitlementReady(TypedDict):
+    """A resolved grant. An inactive grant does not authorize Runtime access."""
+
+    status: Literal["ready"]
+    entitlement: RuntimeEntitlement
+
+
+class RuntimeEntitlementUnavailable(TypedDict):
+    """A non-ready platform result with retry and correlation details."""
+
+    status: Literal["degraded", "misconfigured", "unavailable"]
+    error: RuntimeEntitlementProblem
+
+
+RuntimeEntitlementResponse = RuntimeEntitlementReady | RuntimeEntitlementUnavailable
+
+
+def _finite_number(value: Any) -> bool:
+    """Reject booleans and numbers outside the finite JavaScript number range."""
+    if type(value) not in (int, float):
+        return False
+    try:
+        return math.isfinite(value)
+    except OverflowError:
+        return False
+
+
+def _entitlement(value: Any) -> RuntimeEntitlement | None:
+    """Reject malformed or unknown authority fields instead of widening a grant."""
+    required = {"active", "source", "features", "limits"}
+    if (
+        not isinstance(value, dict)
+        or not required <= value.keys()
+        or value.keys() - required - {"planCode", "entitlementSource"}
+    ):
+        return None
+    if type(value["active"]) is not bool or value["source"] not in (
+        "managedOrgSubscription",
+        "selfHostedDeploymentLicense",
+        "awsMarketplaceDeploymentLicense",
+    ):
+        return None
+    if not isinstance(value["features"], dict) or any(
+        not isinstance(key, str) or type(flag) is not bool
+        for key, flag in value["features"].items()
+    ):
+        return None
+    if not isinstance(value["limits"], dict) or any(
+        not isinstance(key, str) or not _finite_number(limit)
+        for key, limit in value["limits"].items()
+    ):
+        return None
+    result: RuntimeEntitlement = {
+        "active": value["active"],
+        "source": value["source"],
+        "features": dict(value["features"]),
+        "limits": dict(value["limits"]),
+    }
+    if "planCode" in value:
+        if not isinstance(value["planCode"], str):
+            return None
+        result["planCode"] = value["planCode"]
+    if "entitlementSource" in value:
+        if not isinstance(value["entitlementSource"], str):
+            return None
+        result["entitlementSource"] = value["entitlementSource"]
+    return result
+
+
+def normalize_runtime_entitlements(value: Any) -> RuntimeEntitlementResponse | None:
+    """Accept the current strict union or the legacy flat organization response."""
+    if not isinstance(value, dict):
+        return None
+    if value.get("status") == "ready" and value.keys() == {"status", "entitlement"}:
+        grant = _entitlement(value["entitlement"])
+        return {"status": "ready", "entitlement": grant} if grant is not None else None
+    if value.get("status") in ("degraded", "misconfigured", "unavailable") and value.keys() == {
+        "status",
+        "error",
+    }:
+        error = value["error"]
+        required = {"code", "message", "retryable"}
+        if (
+            not isinstance(error, dict)
+            or not required <= error.keys()
+            or error.keys() - required - {"requestId", "traceId"}
+        ):
+            return None
+        if (
+            not isinstance(error["code"], str)
+            or not isinstance(error["message"], str)
+            or type(error["retryable"]) is not bool
+        ):
+            return None
+        problem: RuntimeEntitlementProblem = {
+            "code": error["code"],
+            "message": error["message"],
+            "retryable": error["retryable"],
+        }
+        if "requestId" in error:
+            if not isinstance(error["requestId"], str):
+                return None
+            problem["requestId"] = error["requestId"]
+        if "traceId" in error:
+            if not isinstance(error["traceId"], str):
+                return None
+            problem["traceId"] = error["traceId"]
+        return {"status": value["status"], "error": problem}
+    if isinstance(value.get("organizationId"), str):
+        grant = _entitlement({key: item for key, item in value.items() if key != "organizationId"})
+        if grant is not None:
+            return {"status": "ready", "entitlement": grant}
+    return None

copilotkit_intelligence/inspector.py

@@ -0,0 +1,182 @@
+"""Typed, sanitized Inspector metadata from the Intelligence project."""
+
+from typing import Literal, NotRequired, TypedDict
+from urllib.parse import unquote, urlsplit
+
+import httpx
+
+
+class InspectorIdentity(TypedDict):
+    """Project and organization display names."""
+
+    organizationName: str
+    projectName: str
+
+
+class InspectorPlan(TypedDict):
+    """The plan identifier and display label."""
+
+    code: str
+    label: str
+
+
+class InspectorLicense(TypedDict):
+    """The displayed license state, not an authorization grant."""
+
+    state: Literal["valid", "none", "expired", "unknown"]
+
+
+class InspectorAction(TypedDict):
+    """A plan action with a URL that excludes credentials, queries, and fragments."""
+
+    kind: Literal["manage_plan", "renew", "enable_intelligence"]
+    url: str
+
+
+class InspectorFiniteLimit(TypedDict):
+    """A positive, finite usage limit."""
+
+    kind: Literal["finite"]
+    value: int
+
+
+class InspectorUnlimitedLimit(TypedDict):
+    """A plan with no finite usage limit."""
+
+    kind: Literal["unlimited"]
+
+
+class InspectorUnknownLimit(TypedDict):
+    """A plan whose usage limit is not available."""
+
+    kind: Literal["unknown"]
+
+
+InspectorUsageLimit = InspectorFiniteLimit | InspectorUnlimitedLimit | InspectorUnknownLimit
+
+
+class InspectorUsage(TypedDict):
+    """Usage counts and the plan limit."""
+
+    used: int
+    limit: InspectorUsageLimit
+    expiringSoonCount: NotRequired[int]
+
+
+class InspectorMetadata(TypedDict):
+    """Version 1 metadata with independent optional display modules."""
+
+    schemaVersion: Literal[1]
+    identity: NotRequired[InspectorIdentity]
+    plan: NotRequired[InspectorPlan]
+    license: NotRequired[InspectorLicense]
+    action: NotRequired[InspectorAction]
+    usage: NotRequired[InspectorUsage]
+
+
+def _text(value: object) -> str | None:
+    """Trim the ECMAScript whitespace set used by the TypeScript parser."""
+    if not isinstance(value, str):
+        return None
+    return (
+        value.strip(
+            "\u0009\u000a\u000b\u000c\u000d\u0020\u00a0\u1680"
+            "\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007"
+            "\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff"
+        )
+        or None
+    )
+
+
+def _integer(value: object, minimum: int = 0) -> int | None:
+    """Accept only JSON numbers within JavaScript's safe integer range."""
+    if type(value) not in (int, float):
+        return None
+    if (
+        isinstance(value, (int, float))
+        and minimum <= value <= 9007199254740991
+        and value == int(value)
+    ):
+        return int(value)
+    return None
+
+
+def _action_url(value: object) -> str | None:
+    """Permit HTTPS and loopback HTTP links without embedded private parameters."""
+    url = _text(value)
+    if url is None or "?" in url or "#" in url or "://" not in url:
+        return None
+    authority = url.split("://", 1)[1].split("/", 1)[0]
+    if "@" in authority:
+        return None
+    try:
+        # Browsers treat backslashes as path separators in HTTP(S) URLs.
+        candidate = url.replace("\\", "/")
+        structural = urlsplit(candidate)
+        structural.port  # Reject malformed and out-of-range ports.
+        parsed = httpx.URL(candidate)
+        host = unquote(parsed.host, errors="strict")
+    except (httpx.InvalidURL, ValueError, UnicodeError):
+        return None
+    if (
+        not host
+        or parsed.userinfo
+        or any(character in host for character in "\x00\t\n\r #%/<>?@[\\]^|")
+    ):
+        return None
+    if parsed.scheme == "https" or (
+        parsed.scheme == "http" and parsed.host in ("localhost", "127.0.0.1", "::1")
+    ):
+        return url
+    return None
+
+
+def parse_inspector_metadata(value: object) -> InspectorMetadata | None:
+    """Copy supported fields without letting one invalid module hide valid modules."""
+    if (
+        not isinstance(value, dict)
+        or type(value.get("schemaVersion")) not in (int, float)
+        or value.get("schemaVersion") != 1
+    ):
+        return None
+    result: InspectorMetadata = {"schemaVersion": 1}
+    identity = value.get("identity")
+    if isinstance(identity, dict):
+        organization = _text(identity.get("organizationName"))
+        project = _text(identity.get("projectName"))
+        if organization is not None and project is not None:
+            result["identity"] = {"organizationName": organization, "projectName": project}
+    plan = value.get("plan")
+    if isinstance(plan, dict):
+        code, label = _text(plan.get("code")), _text(plan.get("label"))
+        if code is not None and label is not None:
+            result["plan"] = {"code": code, "label": label}
+    license = value.get("license")
+    if isinstance(license, dict):
+        state = license.get("state")
+        if state in ("valid", "none", "expired", "unknown"):
+            result["license"] = {"state": state}
+    action = value.get("action")
+    if isinstance(action, dict):
+        kind, url = action.get("kind"), _action_url(action.get("url"))
+        if kind in ("manage_plan", "renew", "enable_intelligence") and url is not None:
+            result["action"] = {"kind": kind, "url": url}
+    usage = value.get("usage")
+    if isinstance(usage, dict):
+        used, limit = _integer(usage.get("used")), usage.get("limit")
+        if used is not None and isinstance(limit, dict):
+            parsed_limit: InspectorUsageLimit | None = None
+            if limit.get("kind") == "finite":
+                count = _integer(limit.get("value"), 1)
+                if count is not None:
+                    parsed_limit = {"kind": "finite", "value": count}
+            elif limit.get("kind") == "unlimited":
+                parsed_limit = {"kind": "unlimited"}
+            elif limit.get("kind") == "unknown":
+                parsed_limit = {"kind": "unknown"}
+            if parsed_limit is not None:
+                result["usage"] = {"used": used, "limit": parsed_limit}
+                expiring = _integer(usage.get("expiringSoonCount"))
+                if expiring is not None:
+                    result["usage"]["expiringSoonCount"] = expiring
+    return result

copilotkit_intelligence/learned_skills.py

@@ -0,0 +1,98 @@
+"""Safe learned-skill delivery errors and raw snapshot result shapes."""
+
+from typing import Literal, TypeAlias, TypedDict, cast
+
+LearnedSkillsErrorCode: TypeAlias = Literal[
+    "INVALID_CONFIG",
+    "AUTHENTICATION_FAILED",
+    "AUTHORIZATION_FAILED",
+    "ENTITLEMENT_REQUIRED",
+    "DELIVERY_DISABLED",
+    "CONTAINER_NOT_FOUND",
+    "REVISION_NOT_FOUND",
+    "REVISION_REVOKED",
+    "NETWORK_ERROR",
+    "TIMEOUT",
+    "INVALID_SNAPSHOT",
+    "UNSUPPORTED_SERVER",
+]
+_MESSAGES: dict[LearnedSkillsErrorCode, str] = {
+    "INVALID_CONFIG": "Invalid learned-skills request configuration.",
+    "AUTHENTICATION_FAILED": "Learned-skills authentication failed.",
+    "AUTHORIZATION_FAILED": "Learned-skills access was denied.",
+    "ENTITLEMENT_REQUIRED": "Learned-skills delivery requires an entitlement.",
+    "DELIVERY_DISABLED": "Learned-skills delivery is disabled.",
+    "CONTAINER_NOT_FOUND": "The learning container was not found.",
+    "REVISION_NOT_FOUND": "The learned-skills revision was not found.",
+    "REVISION_REVOKED": "The learned-skills revision was revoked.",
+    "NETWORK_ERROR": "The learned-skills request failed during transport.",
+    "TIMEOUT": "The learned-skills request timed out.",
+    "INVALID_SNAPSHOT": "The learned-skills response metadata is invalid.",
+    "UNSUPPORTED_SERVER": "The server returned an unsupported learned-skills response.",
+}
+_DENIAL_CODES = frozenset(
+    {
+        "AUTHENTICATION_FAILED",
+        "AUTHORIZATION_FAILED",
+        "ENTITLEMENT_REQUIRED",
+        "DELIVERY_DISABLED",
+        "CONTAINER_NOT_FOUND",
+        "REVISION_NOT_FOUND",
+        "REVISION_REVOKED",
+    }
+)
+
+
+class LearnedSkillsError(Exception):
+    """Stable safe failure; an optional cause is available for explicit diagnostics."""
+
+    def __init__(
+        self, code: LearnedSkillsErrorCode, retryable: bool, cause: BaseException | None = None
+    ) -> None:
+        self.code = code
+        self.message = _MESSAGES[code]
+        self.retryable = retryable
+        self.cause = cause
+        super().__init__(self.message)
+
+
+class LearnedSkillsSnapshot(TypedDict):
+    """Raw ZIP response; archive validation belongs to the framework adapter."""
+
+    status: Literal["snapshot"]
+    bytes: bytes
+    revision: str
+    etag: str
+    contentType: str
+
+
+class LearnedSkillsUnchanged(TypedDict):
+    """Conditional response; the caller owns the previous snapshot."""
+
+    status: Literal["unchanged"]
+    revision: str
+    etag: str
+
+
+LearnedSkillsSnapshotResult: TypeAlias = LearnedSkillsSnapshot | LearnedSkillsUnchanged
+
+
+def response_error(status: int, body: object) -> LearnedSkillsError:
+    """Discard response text and preserve only recognized structured failure fields."""
+    if status == 401:
+        return LearnedSkillsError("AUTHENTICATION_FAILED", False)
+    error = body.get("error") if isinstance(body, dict) else None
+    if (
+        isinstance(error, dict)
+        and isinstance(error.get("code"), str)
+        and error["code"] in _MESSAGES
+        and isinstance(error.get("message"), str)
+        and isinstance(error.get("category"), str)
+        and isinstance(error.get("retryable"), bool)
+    ):
+        code = cast(LearnedSkillsErrorCode, error["code"])
+        if status != 403 or code in _DENIAL_CODES:
+            return LearnedSkillsError(code, error["retryable"])
+    return LearnedSkillsError(
+        "AUTHORIZATION_FAILED" if status == 403 else "UNSUPPORTED_SERVER", False
+    )

copilotkit_intelligence/resources.py

@@ -0,0 +1,134 @@
+"""Public resource shapes. Results remain dictionaries with their wire field names."""
+
+from typing import Literal, NotRequired, TypeAlias, TypedDict
+
+
+class ThreadSummary(TypedDict):
+    """Thread metadata without message history."""
+
+    id: str
+    name: str | None
+    lastRunAt: NotRequired[str]
+    lastUpdatedAt: NotRequired[str]
+    createdAt: NotRequired[str]
+    updatedAt: NotRequired[str]
+    archived: NotRequired[bool]
+    agentId: NotRequired[str]
+    createdById: NotRequired[str]
+    organizationId: NotRequired[str]
+
+
+class ListThreadsResponse(TypedDict):
+    """A page of threads with its cursor and realtime join credentials."""
+
+    threads: list[ThreadSummary]
+    joinCode: str
+    joinToken: NotRequired[str]
+    nextCursor: NotRequired[str | None]
+
+
+class ThreadResolution(TypedDict):
+    """A thread and whether this call created it."""
+
+    thread: ThreadSummary
+    created: bool
+
+
+class ThreadToolCall(TypedDict):
+    """A persisted tool call with JSON-encoded arguments."""
+
+    id: str
+    name: str
+    args: str
+
+
+class ThreadMessage(TypedDict):
+    """A persisted AG-UI message with optional structured content."""
+
+    id: str
+    role: str
+    content: NotRequired[object]
+    activityType: NotRequired[str]
+    toolCalls: NotRequired[list[ThreadToolCall]]
+    toolCallId: NotRequired[str]
+
+
+class ThreadMessagesResponse(TypedDict):
+    """Persisted messages in chronological order."""
+
+    messages: list[ThreadMessage]
+
+
+class ThreadInspectEvent(TypedDict):
+    """A persisted event. Additional event fields remain in the dictionary."""
+
+    type: str
+
+
+class ThreadEventsResponse(TypedDict):
+    """Persisted events with decode failures and the event-cap marker."""
+
+    events: list[ThreadInspectEvent]
+    decodeErrorRowIds: list[str]
+    truncated: bool
+
+
+class ThreadNoSnapshot(TypedDict):
+    """The thread has no state snapshot."""
+
+    kind: Literal["no-snapshot"]
+
+
+class ThreadSnapshotDecodeError(TypedDict):
+    """The platform could not decode the stored snapshot."""
+
+    kind: Literal["snapshot-decode-error"]
+
+
+class ThreadSnapshot(TypedDict):
+    """Folded state and the number of deltas the platform skipped."""
+
+    kind: Literal["snapshot"]
+    state: object
+    skippedDeltas: int
+
+
+ThreadStateResponse: TypeAlias = ThreadNoSnapshot | ThreadSnapshotDecodeError | ThreadSnapshot
+
+
+class AnnotateResponse(TypedDict):
+    """The annotation ID and whether the platform recognized a repeated write."""
+
+    id: str
+    duplicate: bool
+
+
+class MemorySummary(TypedDict):
+    """A stored memory, with an optional relevance score from recall."""
+
+    id: str
+    kind: str
+    scope: str
+    content: str
+    sourceThreadIds: list[str]
+    invalidatedAt: str | None
+    score: NotRequired[float]
+
+
+class ListMemoriesResponse(TypedDict):
+    """Memories visible to the application user under the supplied grant."""
+
+    memories: list[MemorySummary]
+
+
+class RecallMemoriesResponse(TypedDict):
+    """Memories that match a recall query, with their relevance scores."""
+
+    memories: list[MemorySummary]
+
+
+class SaveMemoryResponse(MemorySummary):
+    """The saved memory and optional merge or replacement markers."""
+
+    absorbed: NotRequired[bool]
+    retiredId: NotRequired[str]