kobil-agent-sdk 1.2.0__tar.gz

kobil_agent_sdk-1.2.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

kobil_agent_sdk-1.2.0/LICENSE

@@ -0,0 +1,128 @@
+KOBIL Agent Trust SDK License
+Version 1.0
+
+Copyright (c) 2026 KOBIL GmbH. All rights reserved.
+The Software is developed by the KOBIL AI Team.
+
+In short: you may install and use the Software free of charge, also in
+commercial products, and ship it inside your own application. You may not
+change it, copy it into other software, or pass it on or sell it on its
+own. The numbered terms below are the license; this summary is not.
+
+1. Definitions
+
+   "The Software" is the code and documentation in this package.
+
+   "You" is the person or organization that accepts these terms.
+
+   "Your company" is the organization you work for, and the organizations
+   that control it, that it controls, or that are under common control
+   with it.
+
+   "Your application" is software or a service that you build and that
+   does more than give access to the Software. Your application is not a
+   work based on the Software just because it uses the Software.
+
+2. Acceptance
+
+   By installing, copying or using the Software you accept these terms.
+   If you do not accept them, do not use the Software.
+
+3. What you may do
+
+   KOBIL grants you and your company a non-exclusive, worldwide,
+   non-transferable license, free of charge, to:
+
+   a. install and use the Software, unchanged, to build, test and run your
+      applications, including commercial ones that you charge for;
+   b. make the copies of the Software that this needs, for example on
+      developer machines, on build servers and in your application's
+      environments;
+   c. ship the Software, unchanged, as part of your application, for
+      example inside its container image, package or bundle.
+
+   Your company's employees and contractors may do the same on your
+   company's behalf.
+
+   Building your application with tools such as bundlers, minifiers,
+   transpilers or compilers is not a change to the Software. Using AI
+   coding tools to write applications that use the Software is allowed.
+
+4. Shipping the Software inside your application
+
+   When you ship the Software as part of your application:
+
+   a. the Software must be needed for your application to work, and must
+      not be offered as a library, SDK or tool of its own;
+   b. the people who receive your application get no right to use the
+      Software apart from your application;
+   c. keep this license and the copyright notice with the Software, or in
+      your application's third-party notices.
+
+5. What you may not do
+
+   You may not:
+
+   a. change, adapt or translate the Software, or make works based on it;
+   b. copy the Software's code, or substantial parts of it, into other
+      software, whether by hand or with automated or AI tools, or use the
+      Software to train AI models;
+   c. publish, share, sublicense, sell, rent or lease the Software on its
+      own, or as part of another SDK, library, framework or developer
+      tool;
+   d. remove or change this license or any copyright notice in the
+      Software;
+   e. use the Software to break the law, or to suggest that KOBIL endorses
+      your application.
+
+   These limits apply to the Software itself. You may sell and
+   commercially distribute your application.
+
+6. KOBIL services
+
+   The Software can connect to KOBIL services. Using those services is
+   governed by their own terms, not by this license. This license does not
+   give you access to any KOBIL service.
+
+7. Ownership
+
+   KOBIL keeps all rights in the Software that this license does not
+   expressly grant. This license gives you no right to KOBIL's names,
+   logos or trademarks, except to say truthfully that your application
+   uses the Software.
+
+8. Other software
+
+   The Software uses third-party open-source packages. Each of them is
+   covered by its own license, not by this one.
+
+9. New versions
+
+   KOBIL may release new versions of the Software under a new version of
+   this license. Each copy of the Software is covered by the license that
+   came with it.
+
+10. Violations
+
+   If you break these terms, KOBIL may tell you so in writing. The first
+   time this happens, your license continues if, within 30 days of that
+   notice, you fully comply again and take practical steps to correct past
+   violations. Otherwise, and after any later violation, your license
+   ends. You must then stop using and shipping the Software.
+
+11. No warranty
+
+   As far as the law allows, the Software comes "as is", without any
+   warranty or condition, express or implied, including fitness for a
+   particular purpose and non-infringement.
+
+12. Limitation of liability
+
+   As far as the law allows, KOBIL is not liable for any damages that come
+   from these terms or from using, or not being able to use, the Software,
+   under any kind of legal claim.
+
+13. Other permissions
+
+   For any use these terms do not allow, ask KOBIL for written permission
+   at www.kobil.com.

kobil_agent_sdk-1.2.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: kobil-agent-sdk
+Version: 1.2.0
+Summary: KOBIL AI Trust Platform Agent SDK — OAuth 2.1, CIBA, DPoP, agent identity, and framework integrations
+License-Expression: LicenseRef-KOBIL-Agent-Trust-SDK-1.0
+License-File: LICENSE
+Keywords: agent,ai-trust,ciba,dpop,kobil,oauth,sdk
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: all
+Requires-Dist: anthropic>=0.20; extra == 'all'
+Requires-Dist: claude-agent-sdk>=0.1; extra == 'all'
+Requires-Dist: google-adk>=2.10; extra == 'all'
+Requires-Dist: google-genai>=0.1; extra == 'all'
+Requires-Dist: openai-agents>=0.1; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20; extra == 'anthropic'
+Requires-Dist: claude-agent-sdk>=0.1; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Provides-Extra: google
+Requires-Dist: google-adk>=2.10; extra == 'google'
+Requires-Dist: google-genai>=0.1; extra == 'google'
+Provides-Extra: openai
+Requires-Dist: openai-agents>=0.1; extra == 'openai'
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# kobil-agent-sdk (Python)
+
+Python mirror of the `@uveysservetoglu/kobil-agent-sdk` TypeScript SDK.
+
+This is a behavioral 1:1 port of the TypeScript package in `../src`, delivered
+in layers given its size (~11k LOC). The **current layer** is the self-contained
+auth foundation:
+
+- **config** — `KobilSDKConfig`, `create_config` (endpoint derivation, defaults)
+- **OAuth 2.1** — PKCE (`generate_code_verifier`/`generate_code_challenge`),
+  authorization-code exchange, client-credentials via the Management API proxy
+  (mTLS), RFC 8693 token exchange, refresh; automatic retry with backoff
+- **CIBA** — initiate / poll / status
+- **DPoP** — ECDSA P-256 (ES256), emitted in IEEE-P1363 raw `R||S` form to match
+  WebCrypto so proofs are byte-compatible with the TypeScript SDK
+
+Subsequent layers add `KobilAI`, the tool registry, agent identity, platform,
+the isolated key-signer subprocess, and the vendor framework adapters
+(OpenAI / Anthropic / Google).
+
+## Install (dev)
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Test
+
+```bash
+pytest
+```

kobil_agent_sdk-1.2.0/README.md

@@ -0,0 +1,32 @@
+# kobil-agent-sdk (Python)
+
+Python mirror of the `@uveysservetoglu/kobil-agent-sdk` TypeScript SDK.
+
+This is a behavioral 1:1 port of the TypeScript package in `../src`, delivered
+in layers given its size (~11k LOC). The **current layer** is the self-contained
+auth foundation:
+
+- **config** — `KobilSDKConfig`, `create_config` (endpoint derivation, defaults)
+- **OAuth 2.1** — PKCE (`generate_code_verifier`/`generate_code_challenge`),
+  authorization-code exchange, client-credentials via the Management API proxy
+  (mTLS), RFC 8693 token exchange, refresh; automatic retry with backoff
+- **CIBA** — initiate / poll / status
+- **DPoP** — ECDSA P-256 (ES256), emitted in IEEE-P1363 raw `R||S` form to match
+  WebCrypto so proofs are byte-compatible with the TypeScript SDK
+
+Subsequent layers add `KobilAI`, the tool registry, agent identity, platform,
+the isolated key-signer subprocess, and the vendor framework adapters
+(OpenAI / Anthropic / Google).
+
+## Install (dev)
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Test
+
+```bash
+pytest
+```

kobil_agent_sdk-1.2.0/kobil_agent_sdk/__init__.py

@@ -0,0 +1,120 @@
+"""kobil-agent-sdk — KOBIL AI Trust Platform Agent SDK (Python).
+
+Python mirror of the ``@uveysservetoglu/kobil-agent-sdk`` TypeScript package.
+
+This package is being ported in layers. The current layer covers the
+self-contained **auth foundation**: configuration, OAuth 2.1 (PKCE, client
+credentials via the Management API proxy/mTLS, token exchange, refresh),
+CIBA, FGA, and DPoP (ECDSA P-256 / ES256). The ``KobilAI`` facade, registry,
+identity, platform, key-signer isolation, and vendor adapters follow in
+subsequent layers.
+"""
+
+from __future__ import annotations
+
+from .auth import (
+    CIBAClient,
+    DPoPManager,
+    OAuthClient,
+    TokenExchangeClient,
+    TokenExchangeError,
+    TokenExchangeRequest,
+    TokenExchangeResponse,
+    generate_code_challenge,
+    generate_code_verifier,
+)
+from .config import KobilSDKConfig, create_config
+from .easy import (
+    KobilToolContext,
+    KobilToolOptions,
+    SecureOptions,
+    UnifiedConfig,
+    create_kobil,
+    extract_tool_context,
+    kobil_tool,
+    secure,
+)
+from .fga import FGAClient, FGAClientConfig
+from .identity.agent_identity import AgentIdentityManager
+from .kobil_ai import KobilAI
+from .registry import ToolRegistry
+from .types import (
+    AgentIdentity,
+    AuthorizationDeniedError,
+    AuthorizationTimeoutError,
+    AuthResult,
+    CIBAAuthRequest,
+    CIBAAuthResponse,
+    ConfigurationError,
+    FGAError,
+    FGACheckRequest,
+    FGACheckResponse,
+    KobilConfig,
+    KobilSDKError,
+    OAuthError,
+    ToolDescriptor,
+)
+from .web import (
+    KobilIdentity,
+    KobilIdentityOptions,
+    KobilUser,
+    create_kobil_identity,
+)
+
+# The release pipeline stamps the version into pyproject.toml only, so read it back from the installed metadata.
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError, version as _version
+
+try:
+    __version__ = _version("kobil-agent-sdk")
+except _PackageNotFoundError:  # running from a source checkout that is not installed
+    __version__ = "0.0.0"
+
+__all__ = [
+    # facade + core
+    "KobilAI",
+    "ToolRegistry",
+    "AgentIdentityManager",
+    "KobilToolContext",
+    "KobilToolOptions",
+    "SecureOptions",
+    "UnifiedConfig",
+    "kobil_tool",
+    "secure",
+    "create_kobil",
+    "extract_tool_context",
+    "FGAClient",
+    "FGAClientConfig",
+    # config
+    "KobilSDKConfig",
+    "create_config",
+    # auth
+    "OAuthClient",
+    "CIBAClient",
+    "DPoPManager",
+    "TokenExchangeClient",
+    "TokenExchangeError",
+    "TokenExchangeRequest",
+    "TokenExchangeResponse",
+    "generate_code_verifier",
+    "generate_code_challenge",
+    # types
+    "KobilConfig",
+    "AuthResult",
+    "AgentIdentity",
+    "CIBAAuthRequest",
+    "CIBAAuthResponse",
+    "FGACheckRequest",
+    "FGACheckResponse",
+    "ToolDescriptor",
+    "KobilSDKError",
+    "OAuthError",
+    "ConfigurationError",
+    "FGAError",
+    "AuthorizationTimeoutError",
+    "AuthorizationDeniedError",
+    # web identity (OIDC login for MiniApp / web agents)
+    "create_kobil_identity",
+    "KobilIdentity",
+    "KobilIdentityOptions",
+    "KobilUser",
+]

kobil_agent_sdk-1.2.0/kobil_agent_sdk/auth/__init__.py

@@ -0,0 +1,23 @@
+"""Auth subpackage — OAuth, CIBA, DPoP, token exchange."""
+
+from .ciba import CIBAClient
+from .oauth import OAuthClient, generate_code_challenge, generate_code_verifier
+from .vault_compat import (
+    DPoPManager,
+    TokenExchangeClient,
+    TokenExchangeError,
+    TokenExchangeRequest,
+    TokenExchangeResponse,
+)
+
+__all__ = [
+    "CIBAClient",
+    "OAuthClient",
+    "generate_code_verifier",
+    "generate_code_challenge",
+    "DPoPManager",
+    "TokenExchangeClient",
+    "TokenExchangeError",
+    "TokenExchangeRequest",
+    "TokenExchangeResponse",
+]

kobil_agent_sdk-1.2.0/kobil_agent_sdk/auth/ciba.py

@@ -0,0 +1,207 @@
+"""CIBA client (mirror of src/auth/ciba.ts)."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+
+import httpx
+
+from ..config import KobilSDKConfig
+from ..types import (
+    AuthorizationDeniedError,
+    AuthorizationTimeoutError,
+    AuthResult,
+    CIBAAuthRequest,
+    CIBAAuthResponse,
+    KobilSDKError,
+    OAuthError,
+)
+
+DEFAULT_POLL_INTERVAL_SECONDS = 5
+MAX_POLL_DURATION_SECONDS = 300
+
+
+def _now_ms() -> int:
+    import time
+
+    return int(time.time() * 1000)
+
+
+class CIBAClient:
+    def __init__(self, config) -> None:
+        self._cfg = KobilSDKConfig(config)
+
+    async def initiate_auth(self, request: CIBAAuthRequest) -> CIBAAuthResponse:
+        # Accept either a CIBAAuthRequest or a plain dict (some callers pass a
+        # raw dict, e.g. kobil_aitrust.trust.require_approval). Coercing here
+        # fixes every caller without breaking object-style callers.
+        if isinstance(request, dict):
+            request = CIBAAuthRequest(
+                login_hint=request["login_hint"],
+                binding_message=request.get("binding_message") or "Approval required",
+                scope=request.get("scope"),
+                requested_expiry=request.get("requested_expiry"),
+                tool_name=request.get("tool_name"),
+            )
+        if not self._cfg.client_secret:
+            raise OAuthError("invalid_client", "clientSecret is required for CIBA authentication")
+
+        body = {
+            "client_id": self._cfg.client_id,
+            "client_secret": self._cfg.client_secret,
+            "login_hint": request.login_hint,
+            "binding_message": request.binding_message,
+        }
+        if request.tool_name:
+            body["tool_name"] = request.tool_name
+        if request.scope:
+            body["scope"] = request.scope
+        elif self._cfg.scopes:
+            body["scope"] = " ".join(self._cfg.scopes)
+        if request.requested_expiry is not None:
+            body["requested_expiry"] = str(request.requested_expiry)
+        if self._cfg.audience:
+            body["audience"] = self._cfg.audience
+
+        headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Accept": "application/json",
+            **(self._cfg.config.get("custom_headers") or {}),
+        }
+        timeout = self._cfg.timeout_ms / 1000
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as http:
+                response = await http.post(self._cfg.backchannel_auth_endpoint, headers=headers, data=body)
+        except Exception as error:  # noqa: BLE001
+            raise KobilSDKError(f"CIBA initiation request failed: {error}", "NETWORK_ERROR")
+
+        try:
+            data = response.json()
+        except Exception:
+            raise KobilSDKError(
+                f"CIBA initiation endpoint returned non-JSON response ({response.status_code}): {response.text[:200]}",
+                "INVALID_RESPONSE",
+            )
+        if not response.is_success:
+            raise OAuthError(data.get("error") or "unknown_error", data.get("error_description"), response.status_code)
+
+        return CIBAAuthResponse(
+            auth_req_id=data["auth_req_id"],
+            expires_in=data.get("expires_in", 120),
+            interval=data.get("interval", DEFAULT_POLL_INTERVAL_SECONDS),
+            status="pending",
+        )
+
+    async def poll_for_token(self, auth_req_id: str, interval: Optional[int] = None) -> AuthResult:
+        current_interval_ms = (interval if interval is not None else DEFAULT_POLL_INTERVAL_SECONDS) * 1000
+        deadline = _now_ms() + MAX_POLL_DURATION_SECONDS * 1000
+
+        while _now_ms() < deadline:
+            await asyncio.sleep(current_interval_ms / 1000)
+
+            body = {
+                "grant_type": "urn:openid:params:grant-type:ciba",
+                "client_id": self._cfg.client_id,
+                "auth_req_id": auth_req_id,
+            }
+            if self._cfg.client_secret:
+                body["client_secret"] = self._cfg.client_secret
+            headers = {
+                "Content-Type": "application/x-www-form-urlencoded",
+                "Accept": "application/json",
+                **(self._cfg.config.get("custom_headers") or {}),
+            }
+            timeout = self._cfg.timeout_ms / 1000
+            try:
+                async with httpx.AsyncClient(timeout=timeout) as http:
+                    response = await http.post(self._cfg.token_endpoint, headers=headers, data=body)
+            except Exception as error:  # noqa: BLE001
+                raise KobilSDKError(f"CIBA poll request failed: {error}", "NETWORK_ERROR")
+
+            try:
+                data = response.json()
+            except Exception:
+                raise KobilSDKError(
+                    f"CIBA poll endpoint returned non-JSON response ({response.status_code}): {response.text[:200]}",
+                    "INVALID_RESPONSE",
+                )
+
+            if response.is_success:
+                return AuthResult(
+                    access_token=data["access_token"],
+                    token_type=data.get("token_type", "Bearer"),
+                    expires_in=data.get("expires_in", 3600),
+                    refresh_token=data.get("refresh_token"),
+                    id_token=data.get("id_token"),
+                    dpop_nonce=response.headers.get("DPoP-Nonce"),
+                )
+
+            error_type = data.get("error")
+            if error_type == "slow_down":
+                current_interval_ms += 5000
+                continue
+            if error_type == "authorization_pending":
+                continue
+            if error_type == "access_denied":
+                raise AuthorizationDeniedError()
+            if error_type == "expired_token":
+                raise AuthorizationTimeoutError("CIBA authentication request expired")
+            raise OAuthError(error_type or "unknown_error", data.get("error_description"), response.status_code)
+
+        raise AuthorizationTimeoutError(
+            f"CIBA polling exceeded maximum duration of {MAX_POLL_DURATION_SECONDS}s"
+        )
+
+    async def get_status(self, auth_req_id: str) -> CIBAAuthResponse:
+        body = {
+            "grant_type": "urn:openid:params:grant-type:ciba",
+            "client_id": self._cfg.client_id,
+            "auth_req_id": auth_req_id,
+        }
+        if self._cfg.client_secret:
+            body["client_secret"] = self._cfg.client_secret
+        headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Accept": "application/json",
+            **(self._cfg.config.get("custom_headers") or {}),
+        }
+        timeout = self._cfg.timeout_ms / 1000
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as http:
+                response = await http.post(self._cfg.token_endpoint, headers=headers, data=body)
+        except Exception as error:  # noqa: BLE001
+            raise KobilSDKError(f"CIBA status request failed: {error}", "NETWORK_ERROR")
+
+        try:
+            data = response.json()
+        except Exception:
+            raise KobilSDKError(
+                f"CIBA status endpoint returned non-JSON response ({response.status_code}): {response.text[:200]}",
+                "INVALID_RESPONSE",
+            )
+
+        if response.is_success:
+            return CIBAAuthResponse(
+                auth_req_id=auth_req_id,
+                expires_in=data.get("expires_in", 0),
+                interval=data.get("interval", DEFAULT_POLL_INTERVAL_SECONDS),
+                status="approved",
+            )
+
+        error_type = data.get("error")
+        if error_type in ("authorization_pending", "slow_down"):
+            return CIBAAuthResponse(
+                auth_req_id=auth_req_id,
+                expires_in=data.get("expires_in", 0),
+                interval=data.get("interval", DEFAULT_POLL_INTERVAL_SECONDS),
+                status="pending",
+            )
+        if error_type == "access_denied":
+            return CIBAAuthResponse(auth_req_id=auth_req_id, expires_in=0, interval=0, status="denied")
+        if error_type == "expired_token":
+            return CIBAAuthResponse(auth_req_id=auth_req_id, expires_in=0, interval=0, status="expired")
+        raise OAuthError(error_type or "unknown_error", data.get("error_description"), response.status_code)
+
+
+__all__ = ["CIBAClient", "DEFAULT_POLL_INTERVAL_SECONDS", "MAX_POLL_DURATION_SECONDS"]