onkernel 0.2.0__tar.gz

onkernel-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+# ─── Python ──────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# ─── Secrets ─────────────────────────────────────────────────────────────
+*.pem
+!*-pub.pem
+*.key
+.env
+.env.*
+!.env.example
+
+# ─── OS / editor ─────────────────────────────────────────────────────────
+.DS_Store
+.idea/
+.vscode/

onkernel-0.2.0/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to the `onkernel` Python SDK are documented here. This
+project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.2.0 — 2026-06-17
+
+First public PyPI release — the Kernel governance SDK with agent-to-agent
+delegation. Designed to be obvious to use from an LLM-tool-dispatch layer
+without a custom wrapper.
+
+### Added
+
+- **A2A delegation (`delegate()`)** — record agent-to-agent delegation chains
+  in the signed audit log. When one agent's ALLOW decision authorizes another
+  agent to act, pass the parent's `decision_id` so Kernel links the child
+  decision to its parent and unions their regulatory anchors:
+
+  ```python
+  decision = orchestrator.execute("triage_refund", params=…)   # root
+  kyc.delegate(decision.decision_id, "verify_identity", params=…)  # child
+  ```
+
+  `delegate(parent_decision_id, …)` is sugar over the new
+  `execute(…, parent_decision_id=…)` keyword (sends the
+  `X-Kernel-Parent-Decision-Id` header). A cross-tenant or unknown parent is
+  refused identically to a missing one (no existence fingerprinting).
+- **`ActionResponse.decision_id`** — the ALLOW decision's audit-event id, now
+  parsed off the response. Feed it to a downstream agent's `delegate()`. `None`
+  on non-ALLOW outcomes and on proxies predating execution verification.
+- **`KernelOutcome` enum** on `ActionResponse.outcome`. Callers branch on
+  the outcome via `match/case` instead of catching an exception for the
+  "ask a human" path:
+
+  ```python
+  resp = k.execute(action="refund", target="stripe", params={"amount_cents": 12000})
+  match resp.outcome:
+      case KernelOutcome.ALLOWED:        do_thing(resp.result)
+      case KernelOutcome.REQUIRES_HUMAN: queue_for_review(resp.approval_id)
+      case KernelOutcome.BLOCKED:        log_scanner_block(resp.violations)
+      case KernelOutcome.DENIED:         log_policy_deny(resp.reason)
+  ```
+
+- **`ScannerBlockedError`** — sibling of `PolicyDeniedError` for 403
+  responses with a populated `violations` list (PII / secrets / prompt
+  injection detector fired). Exposes `.violation_type` and
+  `.violation_details` so callers don't have to fish through
+  `e.violations[0]["type"]` themselves.
+
+  In v0.2 `ScannerBlockedError` inherits from `PolicyDeniedError` so
+  existing `except PolicyDeniedError:` blocks keep catching both. In v0.3
+  the two will become true siblings under `KernelDeniedError`; migrate by
+  catching them separately:
+
+  ```python
+  try:
+      k.execute(...)
+  except ScannerBlockedError as e:
+      # PII / secret / injection — fix the input
+      ...
+  except PolicyDeniedError as e:
+      # Policy rule denied — pick a different tool or escalate
+      ...
+  ```
+
+- **`KernelDeniedError`** — alias for the shared base of the 403-denial
+  family. Forward-compatible with the v0.3 split:
+
+  ```python
+  except KernelDeniedError:  # catches both scanner blocks and policy denies
+      ...
+  ```
+
+- **`ActionResponse.result_message: str`** — always-non-empty
+  human-readable summary alongside `result: dict | None`. Removes the
+  LLM-anthropomorphizes-None failure mode ("the result was empty, should I
+  retry?"). Populated by the proxy when available; the SDK derives a
+  summary from `status` + `result` keys when the proxy is on an older
+  build.
+
+  Note: the Kernel proxy as of this release does NOT emit `result_message`
+  on successful action responses (only `message` on error paths). The SDK
+  derives a summary client-side and emits a `UserWarning` so operators can
+  tell stale proxies apart from current ones. Upgrade the Kernel proxy to
+  benefit from richer, server-side summaries.
+
+### Deprecated
+
+- **`ApprovalRequiredError`** — the 202-pending-approval path no longer
+  raises. The SDK returns `ActionResponse(outcome=REQUIRES_HUMAN,
+  approval_id=...)` and callers branch on `outcome`. The class is kept
+  importable for v0.2 and removed in v0.3; importing it emits a
+  `DeprecationWarning`.
+
+- **`ActionResponse.message`** — renamed to `result_message`. Reading
+  `.message` emits a `DeprecationWarning`; removed in v0.3.
+
+### Packaging
+
+- First PyPI release as `onkernel` (namespace claimed; `kernel-sdk` was
+  already taken). `pip install onkernel` replaces the
+  `git+https://github.com/onkernel-ai/kernel-python` install string in
+  downstream `pyproject.toml`s.
+- Added `LICENSE` (MIT), classifiers, `project.urls`, `[project.authors]`,
+  and `[project.optional-dependencies.dev]`.
+- Added a `.github/workflows/test.yml` matrix (3.10–3.13) and a
+  `.github/workflows/publish.yml` that builds + publishes on tag push via
+  PyPI Trusted Publishing (no API token in secrets). Pre-release tags
+  (e.g. `v0.2.0-rc.1`) publish to TestPyPI first.
+
+## 0.1.0
+
+Initial baseline.

onkernel-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kernel (onkernel.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

onkernel-0.2.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: onkernel
+Version: 0.2.0
+Summary: Python SDK for Kernel — deterministic governance for AI agents
+Project-URL: Homepage, https://onkernel.ai
+Project-URL: Documentation, https://github.com/onkernel-ai/kernel-python#readme
+Project-URL: Repository, https://github.com/onkernel-ai/kernel-python
+Project-URL: Issues, https://github.com/onkernel-ai/kernel-python/issues
+Project-URL: Changelog, https://github.com/onkernel-ai/kernel-python/blob/main/CHANGELOG.md
+Author-email: Kernel <engineering@onkernel.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,governance,guardrails,llm,policy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: crypto
+Requires-Dist: cryptography>=44.0; extra == 'crypto'
+Provides-Extra: dev
+Requires-Dist: cryptography>=44.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# onkernel
+
+Python SDK for [Kernel](https://onkernel.ai) — deterministic governance for AI agents.
+
+## Install
+
+```bash
+pip install onkernel
+```
+
+For encrypted response decryption:
+
+```bash
+pip install onkernel[crypto]
+```
+
+## Quick Start
+
+```python
+from kernel import Kernel, KernelOutcome
+
+k = Kernel(api_key="ok_live_acme_bot1_abc123")
+
+resp = k.execute(action="send_email", target="user@example.com", params={"body": "Hello"})
+
+match resp.outcome:
+    case KernelOutcome.ALLOWED:
+        # resp.result and resp.result_message are populated
+        print(resp.result_message)
+    case KernelOutcome.REQUIRES_HUMAN:
+        # 202 — escalate to your approval queue
+        approval_id = resp.approval_id
+    case KernelOutcome.BLOCKED:
+        # a scanner fired; resp.violations is populated
+        ...
+    case KernelOutcome.DENIED:
+        # a policy rule denied; resp.reason explains why
+        ...
+```
+
+`ActionResponse` always carries a non-empty `result_message: str` — a
+human-readable summary that's safe to surface in an LLM tool-call result.
+
+### Handling errors
+
+The denial path raises typed exceptions on 403:
+
+```python
+from kernel import (
+    Kernel,
+    ScannerBlockedError,   # scanner fired (PII, secrets, prompt injection, …)
+    PolicyDeniedError,     # policy rule denied with no scanner involvement
+    KernelDeniedError,     # base / alias — catch both
+)
+
+try:
+    k.execute(action="export_pii_report", target="customers")
+except ScannerBlockedError as e:
+    # e.violation_type, e.violation_details, e.violations
+    pass
+except PolicyDeniedError as e:
+    # e.rule_id, e.policy_id, e.reason
+    pass
+```
+
+### 3-step token flow
+
+```python
+session = k.create_session(intent="onboard new customer")
+token = k.request_token(session.id, action="create_account", target="stripe")
+result = k.execute_token(token.token_id, agent_id="bot1")
+```
+
+## Decrypting Responses
+
+When a policy has `encryption_enabled: true`, responses arrive encrypted:
+
+```python
+from kernel import Kernel
+from kernel.crypto import load_private_key
+
+k = Kernel(api_key="ok_live_acme_bot1_abc123")
+private_key = load_private_key("path/to/private_key.pem")
+
+resp = k.execute(action="fetch_records", target="db")
+if resp.encrypted:
+    data = resp.decrypt(private_key)
+```
+
+## Publishing (maintainers)
+
+The SDK is published to PyPI as `onkernel`. Releases go out via tag push;
+the `publish.yml` workflow handles build + Trusted-Publishing OIDC.
+
+**Always release to TestPyPI first.** PyPI is fussy about metadata and
+artifact integrity; a TestPyPI dry-run catches mistakes before they're
+permanent (PyPI does not allow overwriting a released version).
+
+### One-time setup
+
+1. Create the project on PyPI: `pip install build twine && python -m build && twine upload --repository testpypi dist/*` (first manual upload claims the namespace).
+2. On PyPI → project → Publishing, add a pending publisher:
+   - Owner: `onkernel-ai`
+   - Repository: `kernel-python`
+   - Workflow: `publish.yml`
+   - Environment: `pypi`
+3. Repeat the publisher binding on test.pypi.org with environment `testpypi`.
+4. In the GitHub repo Settings → Environments, create `pypi` and `testpypi`. Add required reviewers on `pypi` if you want a release gate.
+
+### Cutting a release
+
+1. Bump `pyproject.toml` `[project].version` and `src/kernel/__init__.py` `__version__` together.
+2. Update `CHANGELOG.md`.
+3. Pre-release dry-run:
+   ```bash
+   git tag v0.X.Y-rc.1
+   git push --tags
+   ```
+   The `publish.yml` workflow detects the `-rc.N` suffix and routes to TestPyPI. Validate:
+   ```bash
+   pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ onkernel==0.X.Y-rc.1
+   python -c "from kernel import Kernel, KernelOutcome; print(KernelOutcome.ALLOWED)"
+   ```
+4. Real release:
+   ```bash
+   git tag v0.X.Y
+   git push --tags
+   ```
+   The same workflow routes the un-suffixed tag to real PyPI.
+
+The workflow verifies that the tag matches `pyproject.toml [project].version`
+before building — a mismatched tag fails fast instead of publishing the
+wrong artifact.
+
+### Fallback: manual API token
+
+If Trusted Publishing isn't yet bound, set repo secret `PYPI_API_TOKEN`
+and replace the OIDC publish step with:
+
+```yaml
+- run: twine upload -u __token__ -p "$PYPI_API_TOKEN" dist/*
+```
+
+Tokens carry blast-radius risk (leak = arbitrary release). Migrate to OIDC
+as soon as the binding is approved on the PyPI side.

onkernel-0.2.0/README.md

@@ -0,0 +1,145 @@
+# onkernel
+
+Python SDK for [Kernel](https://onkernel.ai) — deterministic governance for AI agents.
+
+## Install
+
+```bash
+pip install onkernel
+```
+
+For encrypted response decryption:
+
+```bash
+pip install onkernel[crypto]
+```
+
+## Quick Start
+
+```python
+from kernel import Kernel, KernelOutcome
+
+k = Kernel(api_key="ok_live_acme_bot1_abc123")
+
+resp = k.execute(action="send_email", target="user@example.com", params={"body": "Hello"})
+
+match resp.outcome:
+    case KernelOutcome.ALLOWED:
+        # resp.result and resp.result_message are populated
+        print(resp.result_message)
+    case KernelOutcome.REQUIRES_HUMAN:
+        # 202 — escalate to your approval queue
+        approval_id = resp.approval_id
+    case KernelOutcome.BLOCKED:
+        # a scanner fired; resp.violations is populated
+        ...
+    case KernelOutcome.DENIED:
+        # a policy rule denied; resp.reason explains why
+        ...
+```
+
+`ActionResponse` always carries a non-empty `result_message: str` — a
+human-readable summary that's safe to surface in an LLM tool-call result.
+
+### Handling errors
+
+The denial path raises typed exceptions on 403:
+
+```python
+from kernel import (
+    Kernel,
+    ScannerBlockedError,   # scanner fired (PII, secrets, prompt injection, …)
+    PolicyDeniedError,     # policy rule denied with no scanner involvement
+    KernelDeniedError,     # base / alias — catch both
+)
+
+try:
+    k.execute(action="export_pii_report", target="customers")
+except ScannerBlockedError as e:
+    # e.violation_type, e.violation_details, e.violations
+    pass
+except PolicyDeniedError as e:
+    # e.rule_id, e.policy_id, e.reason
+    pass
+```
+
+### 3-step token flow
+
+```python
+session = k.create_session(intent="onboard new customer")
+token = k.request_token(session.id, action="create_account", target="stripe")
+result = k.execute_token(token.token_id, agent_id="bot1")
+```
+
+## Decrypting Responses
+
+When a policy has `encryption_enabled: true`, responses arrive encrypted:
+
+```python
+from kernel import Kernel
+from kernel.crypto import load_private_key
+
+k = Kernel(api_key="ok_live_acme_bot1_abc123")
+private_key = load_private_key("path/to/private_key.pem")
+
+resp = k.execute(action="fetch_records", target="db")
+if resp.encrypted:
+    data = resp.decrypt(private_key)
+```
+
+## Publishing (maintainers)
+
+The SDK is published to PyPI as `onkernel`. Releases go out via tag push;
+the `publish.yml` workflow handles build + Trusted-Publishing OIDC.
+
+**Always release to TestPyPI first.** PyPI is fussy about metadata and
+artifact integrity; a TestPyPI dry-run catches mistakes before they're
+permanent (PyPI does not allow overwriting a released version).
+
+### One-time setup
+
+1. Create the project on PyPI: `pip install build twine && python -m build && twine upload --repository testpypi dist/*` (first manual upload claims the namespace).
+2. On PyPI → project → Publishing, add a pending publisher:
+   - Owner: `onkernel-ai`
+   - Repository: `kernel-python`
+   - Workflow: `publish.yml`
+   - Environment: `pypi`
+3. Repeat the publisher binding on test.pypi.org with environment `testpypi`.
+4. In the GitHub repo Settings → Environments, create `pypi` and `testpypi`. Add required reviewers on `pypi` if you want a release gate.
+
+### Cutting a release
+
+1. Bump `pyproject.toml` `[project].version` and `src/kernel/__init__.py` `__version__` together.
+2. Update `CHANGELOG.md`.
+3. Pre-release dry-run:
+   ```bash
+   git tag v0.X.Y-rc.1
+   git push --tags
+   ```
+   The `publish.yml` workflow detects the `-rc.N` suffix and routes to TestPyPI. Validate:
+   ```bash
+   pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ onkernel==0.X.Y-rc.1
+   python -c "from kernel import Kernel, KernelOutcome; print(KernelOutcome.ALLOWED)"
+   ```
+4. Real release:
+   ```bash
+   git tag v0.X.Y
+   git push --tags
+   ```
+   The same workflow routes the un-suffixed tag to real PyPI.
+
+The workflow verifies that the tag matches `pyproject.toml [project].version`
+before building — a mismatched tag fails fast instead of publishing the
+wrong artifact.
+
+### Fallback: manual API token
+
+If Trusted Publishing isn't yet bound, set repo secret `PYPI_API_TOKEN`
+and replace the OIDC publish step with:
+
+```yaml
+- run: twine upload -u __token__ -p "$PYPI_API_TOKEN" dist/*
+```
+
+Tokens carry blast-radius risk (leak = arbitrary release). Migrate to OIDC
+as soon as the binding is approved on the PyPI side.

onkernel-0.2.0/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "onkernel"
+version = "0.2.0"
+description = "Python SDK for Kernel — deterministic governance for AI agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Kernel", email = "engineering@onkernel.ai" },
+]
+keywords = ["ai", "agents", "governance", "policy", "llm", "guardrails"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+crypto = ["cryptography>=44.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "cryptography>=44.0",
+    "respx>=0.21",
+]
+
+[project.urls]
+Homepage = "https://onkernel.ai"
+Documentation = "https://github.com/onkernel-ai/kernel-python#readme"
+Repository = "https://github.com/onkernel-ai/kernel-python"
+Issues = "https://github.com/onkernel-ai/kernel-python/issues"
+Changelog = "https://github.com/onkernel-ai/kernel-python/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kernel"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/kernel",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B018"]
+
+[tool.mypy]
+python_version = "3.10"
+strict_optional = true
+warn_unused_ignores = true
+ignore_missing_imports = true
+packages = ["kernel"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = [
+    # Tests should fail if they trigger an unexpected DeprecationWarning so
+    # callers see clean output. Individual tests assert deprecations with
+    # `pytest.warns`.
+    "error::DeprecationWarning:kernel.*",
+]

onkernel-0.2.0/src/kernel/__init__.py

@@ -0,0 +1,85 @@
+"""Kernel SDK — deterministic governance for AI agents."""
+
+from __future__ import annotations
+
+import warnings as _warnings
+from typing import Any as _Any
+
+__version__ = "0.2.0"
+
+import contextlib as _contextlib
+
+from kernel.client import Kernel
+from kernel.errors import (
+    AuthError,
+    CircuitOpenError,
+    FeatureNotInTier,
+    KernelDeniedError,
+    KernelError,
+    PlanCeilingHit,
+    PlanLimitExceeded,
+    PlanSoftWarning,
+    PolicyDeniedError,
+    RateLimitError,
+    ScannerBlockedError,
+    WebhookError,
+)
+from kernel.types import (
+    ActionResponse,
+    ApprovalResult,
+    ExecuteResponse,
+    KernelOutcome,
+    Session,
+    TokenResponse,
+)
+
+with _contextlib.suppress(ImportError):
+    from kernel.crypto import decrypt, decrypt_json  # noqa: F401 — re-export
+
+
+def __getattr__(name: str) -> _Any:
+    """Lazy deprecation for `kernel.ApprovalRequiredError` import.
+
+    The SDK no longer raises this exception (the 202 path now returns an
+    `ActionResponse` with `outcome == KernelOutcome.REQUIRES_HUMAN`). The
+    name is kept exported for one minor version so existing
+    `from kernel import ApprovalRequiredError` keeps importing. Reading
+    the symbol emits a `DeprecationWarning`; the class is removed in v0.3.
+    """
+    if name == "ApprovalRequiredError":
+        _warnings.warn(
+            "ApprovalRequiredError is deprecated and will be removed in v0.3. "
+            "The SDK no longer raises on 202 responses; branch on "
+            "ActionResponse.outcome (KernelOutcome.REQUIRES_HUMAN) instead. "
+            "See CHANGELOG for migration.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from kernel.errors import ApprovalRequiredError as _AR
+        return _AR
+    raise AttributeError(f"module 'kernel' has no attribute {name!r}")
+
+
+__all__ = [
+    "Kernel",
+    "KernelError",
+    "AuthError",
+    "KernelDeniedError",
+    "PolicyDeniedError",
+    "ScannerBlockedError",
+    "RateLimitError",
+    "CircuitOpenError",
+    "WebhookError",
+    "PlanLimitExceeded",
+    "PlanCeilingHit",
+    "FeatureNotInTier",
+    "PlanSoftWarning",
+    "ActionResponse",
+    "KernelOutcome",
+    "Session",
+    "TokenResponse",
+    "ExecuteResponse",
+    "ApprovalResult",
+    # Deprecated, retained one minor version:
+    "ApprovalRequiredError",
+]