noukai-sdk 0.2.0__tar.gz

noukai_sdk-0.2.0/.env.example

@@ -0,0 +1,53 @@
+# noukai-sdk Python — local env for integration tests
+#
+# Setup:
+#   cp .env.example .env
+#   # fill in real values below
+#   uv run pytest tests/integration -v
+#
+# The .env file is loaded automatically by tests/integration/conftest.py
+# via python-dotenv. It is NOT loaded by the SDK at runtime — only by tests.
+# NEVER commit .env (it's in .gitignore).
+
+# ----------------------------------------------------------------------------
+# SDK runtime env (read by the SDK itself at Noukai() construction)
+# ----------------------------------------------------------------------------
+
+# Deployment target. "dev" → http://localhost:8080/api/v1
+#                   unset/"production" → https://api.noukai.xyz/api/v1
+NOUKAI_ENV=dev
+
+# ----------------------------------------------------------------------------
+# Integration test env (read only by tests/integration/, not the SDK)
+# ----------------------------------------------------------------------------
+
+# Real nk_* API key for the integration test account.
+# For local dev: a key minted against your local Noukai server.
+# For staging/prod: a dedicated test-account key (NOT a production user key).
+NOUKAI_INTEGRATION_KEY=nk_replace_me
+
+# "org/project" pair holding the fixture flows.
+# Recommended convention: a dedicated "tests-integration" project.
+NOUKAI_INTEGRATION_PROJECT=acme/tests-integration
+
+# Slug of a single-step flow that takes `message` and returns a response.
+# Used by test_execute, test_execute_async, test_run_proxy.
+NOUKAI_INTEGRATION_HELLO_SLUG=hello-world
+
+# Slug of a two-block flow used to test steps()/events() iteration.
+# Used by test_steps, test_events, test_run_proxy.
+NOUKAI_INTEGRATION_TWO_STEP_SLUG=two-step
+
+# Slug of a flow configured with `tools` for tool-call resume testing.
+# Used by test_tool_calls.
+NOUKAI_INTEGRATION_TOOLS_SLUG=tools-enabled
+
+# ----------------------------------------------------------------------------
+# Optional: zero-credit org for the InsufficientCreditsError test
+# ----------------------------------------------------------------------------
+
+# If you have a separate test account with 0 credits, fill these in to enable
+# the test_zero_credits_raises_insufficient_credits test. Otherwise it skips.
+# NOUKAI_INTEGRATION_ZERO_CREDIT_KEY=nk_zero_credit_account
+# NOUKAI_INTEGRATION_ZERO_CREDIT_PROJECT=acme/integration-zero
+# NOUKAI_INTEGRATION_ZERO_CREDIT_SLUG=hello-world

noukai_sdk-0.2.0/.github/CODEOWNERS

@@ -0,0 +1,6 @@
+# .github/CODEOWNERS
+# All files: SDK maintainers own everything by default.
+* @noukai/sdk-maintainers
+
+# Docs: co-owned by the docs team.
+docs/ @noukai/sdk-maintainers @noukai/docs

noukai_sdk-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Something is not working as expected
+labels: bug
+---
+
+## Description
+
+<!-- A clear, concise description of what the bug is. -->
+
+## Minimal reproducer
+
+```python
+from noukai_sdk import Noukai
+
+# Paste the smallest code snippet that triggers the problem.
+```
+
+## Expected behaviour
+
+<!-- What you expected to happen. -->
+
+## Actual behaviour
+
+<!-- What actually happened. Include any error messages or tracebacks. -->
+
+## Environment
+
+| Field | Value |
+|-------|-------|
+| SDK version | <!-- e.g. 0.1.0 — run: python -c "import noukai_sdk; print(noukai_sdk.__version__)" --> |
+| Python version | <!-- e.g. 3.11.9 --> |
+| OS | <!-- e.g. macOS 14.5, Ubuntu 22.04, Windows 11 --> |
+| Install method | <!-- pip / uv / conda / other --> |
+
+## Additional context
+
+<!-- Anything else that might help — logs, related issues, etc. -->

noukai_sdk-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature request
+about: Suggest an improvement or new capability
+labels: enhancement
+---
+
+## Summary
+
+<!-- One sentence: what would you like the SDK to do? -->
+
+## Motivation
+
+<!-- Why do you need this? What use case does it unlock? -->
+
+## Proposed API
+
+```python
+# Optional: sketch what the API might look like.
+```
+
+## Alternatives considered
+
+<!-- Have you worked around this another way? Are there existing methods that partially cover the need? -->
+
+## Additional context
+
+<!-- Anything else — links to Noukai docs, related issues, etc. -->

noukai_sdk-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+## Summary
+
+<!-- What does this PR do? One to three bullet points. -->
+
+- 
+
+## Related issues
+
+<!-- Link any issues this PR addresses: "Closes #123" or "Relates to #456". -->
+
+## Test plan
+
+- [ ] Existing tests pass (`uv run pytest tests/unit/ -v`)
+- [ ] New tests added for new behaviour (if applicable)
+- [ ] Type-check passes (`uv run mypy`)
+- [ ] Linting passes (`uv run ruff check && uv run ruff format --check`)
+- [ ] Manual verification steps:
+
+<!-- Describe any manual steps needed to verify this PR. -->
+
+## Checklist
+
+- [ ] CHANGELOG.md updated under `[Unreleased]`
+- [ ] `_version.py` and `pyproject.toml` bumped (if this is a release PR)
+- [ ] Docs updated (if public API changed)

noukai_sdk-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-type:
+    name: Lint & type-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dev dependencies
+        run: uv sync --extra dev
+
+      - name: Check formatting (ruff)
+        run: uv run ruff format --check
+
+      - name: Lint (ruff)
+        run: uv run ruff check
+
+      - name: Type-check (mypy)
+        run: uv run mypy
+
+  test:
+    name: Tests (${{ matrix.os }} / Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dev dependencies
+        run: uv sync --extra dev
+
+      # Run unit tests with coverage reporting and enforce the floor in
+      # the same invocation (one pytest run is sufficient — the second
+      # invocation was producing duplicate output and re-running tests).
+      - name: Run unit tests with coverage
+        run: >
+          uv run pytest tests/unit/ -v
+          --cov=noukai_sdk
+          --cov-report=term-missing
+          --cov-fail-under=85

noukai_sdk-0.2.0/.github/workflows/integration.yml

@@ -0,0 +1,44 @@
+name: Integration (Python SDK)
+
+on:
+  schedule:
+    - cron: "0 6 * * *"   # daily 06:00 UTC
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:       # manual trigger
+
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      NOUKAI_INTEGRATION_KEY: ${{ secrets.NOUKAI_INTEGRATION_KEY }}
+      NOUKAI_INTEGRATION_PROJECT: ${{ vars.NOUKAI_INTEGRATION_PROJECT }}
+      NOUKAI_INTEGRATION_HELLO_SLUG: ${{ vars.NOUKAI_INTEGRATION_HELLO_SLUG }}
+      NOUKAI_INTEGRATION_TWO_STEP_SLUG: ${{ vars.NOUKAI_INTEGRATION_TWO_STEP_SLUG }}
+      NOUKAI_INTEGRATION_TOOLS_SLUG: ${{ vars.NOUKAI_INTEGRATION_TOOLS_SLUG }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: |
+          cd development/noukai/sdk/python
+          uv sync --extra dev
+
+      - name: Run integration tests
+        run: |
+          cd development/noukai/sdk/python
+          uv run pytest tests/integration/ -v --tb=short
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: integration-test-results
+          path: development/noukai/sdk/python/.pytest_cache/
+          retention-days: 7

noukai_sdk-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,64 @@
+name: Release
+
+# Triggers on semver tags like v0.1.0, v1.2.3, etc.
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build-and-publish:
+    name: Build, publish to PyPI & create GitHub release
+    runs-on: ubuntu-latest
+    # The "pypi" environment must be created in the GitHub repo settings
+    # (Settings → Environments → New environment: pypi) and the PyPI trusted
+    # publisher must be configured at:
+    #   https://pypi.org/manage/account/publishing/
+    # pointing at this workflow file path:
+    #   Workflow: .github/workflows/release.yml
+    #   Environment: pypi
+    environment: pypi
+    permissions:
+      id-token: write   # Required for OIDC trusted publisher (no API token needed)
+      contents: write   # Required to create the GitHub release
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install package (no extras — just needs to be importable for version check)
+        run: uv sync
+
+      # Safety guard: the pushed tag (e.g. v0.1.0) must match the version
+      # declared in noukai_sdk._version. Catches "forgot to bump _version.py"
+      # before we reach PyPI (uploads there are permanent).
+      - name: Verify tag matches package version
+        shell: bash
+        run: |
+          TAG_VER="${GITHUB_REF_NAME#v}"
+          FILE_VER=$(uv run python -c "import noukai_sdk; print(noukai_sdk.__version__)")
+          echo "Tag version  : $TAG_VER"
+          echo "Package version: $FILE_VER"
+          if [ "$TAG_VER" != "$FILE_VER" ]; then
+            echo "ERROR: tag $TAG_VER does not match package version $FILE_VER"
+            echo "Update src/noukai_sdk/_version.py and pyproject.toml, then retag."
+            exit 1
+          fi
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      # Uses PyPI's OIDC trusted publisher — no API token stored in GitHub secrets.
+      # See: https://docs.pypi.org/trusted-publishers/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      # Creates a GitHub release from the tag with auto-generated release notes
+      # and attaches the CHANGELOG as the body.
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          body_path: CHANGELOG.md

noukai_sdk-0.2.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# UV
+.uv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+
+# Linting
+.ruff_cache/
+
+# Documentation build output (mkdocs)
+site/
+
+# Local env (integration test secrets — never commit)
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# macOS
+.DS_Store

noukai_sdk-0.2.0/.python-version

@@ -0,0 +1 @@
+3.10

noukai_sdk-0.2.0/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The
+format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-06-06
+
+### Added
+
+- `@noukai_sdk.trace` decorator and `trace_scope` / `trace_scope_sync` context
+  managers. Wrapping a route (or any callable) in `@trace` groups every Noukai
+  SDK call it makes under a single session id so the full execution can be
+  replayed later.
+- `current_session_id() -> str | None` — returns the session id of the active
+  scope, or `None` when called outside a scope.
+- `session_id=` optional kwarg on `Flow.execute()`, `Flow.steps()`,
+  `Flow.events()`, `Flow.execute_async()`, and their `AsyncFlow` counterparts.
+  When passed outside a scope the SDK sends `X-Session-Id` on the wire;
+  when passed *inside* an active replay scope it triggers a one-shot fetch
+  of that explicit session instead of drawing from the scope cassette (see
+  Caveats in README).
+- `session_id=` optional kwarg on `Noukai(...)` / `AsyncNoukai(...)` — sets a
+  default session id for every call made through that client.
+- `ExecuteResult.session_id` property surfaces the captured or replayed session
+  id returned in the `X-Noukai-Session` response header.
+- **Replay mode.** When `NOUKAI_REPLAY_ENABLED=true` and the caller passes
+  `X-Noukai-Replay: <session_id>` to the adapter, the SDK fetches the recorded
+  session via `GET /seq/sessions/{id}` (idempotent; retried by default transport
+  retry logic — see R3 note in README) and serves each `Flow.execute()` /
+  `steps()` / `events()` call from the cassette instead of making live calls.
+- **Framework adapters:**
+  - `noukai_sdk.adapters.fastapi.NoukaiTraceMiddleware` — ASGI middleware for
+    FastAPI / Starlette; reads `X-Noukai-Replay`, opens/closes a trace scope
+    around the request, and writes `X-Noukai-Session` to the response.
+  - `noukai_sdk.adapters.flask.init_noukai_trace` — Flask before/after-request
+    hooks equivalent.
+- **9 replay error classes** (all extend `ReplayError` which extends
+  `NoukaiError`):
+  - `ReplayError` — base class for all replay errors.
+  - `ReplayMissError` — no matching execution found in the cassette for a
+    `(slug, position)` lookup.
+  - `ReplayLeftoverError` — scope exited with unconsumed executions remaining
+    in the cassette.
+  - `ReplayForbiddenError` — replay attempted against a session that belongs to
+    a different org/project.
+  - `ReplaySessionNotFoundError` — the requested session id does not exist on
+    the backend.
+  - `ReplaySessionExpiredError` — the session exists but its TTL has elapsed and
+    snapshots are no longer available.
+  - `ReplayInvalidSessionError` — the session payload is structurally invalid or
+    cannot be parsed.
+  - `ReplayNoSnapshotsError` — the session exists but `trace_capture_mode` was
+    `off` so no snapshot data was recorded.
+  - `ReplayDisabledError` — replay was requested but `NOUKAI_REPLAY_ENABLED` is
+    not set to `true` (raised only when the adapter is used without the guard).
+- Optional package extras: `noukai-sdk[fastapi]` (pulls FastAPI + Starlette)
+  and `noukai-sdk[flask]` (pulls `flask>=3.0`).
+- Centralized URL audit registry at `noukai_sdk/_paths.py` — single file
+  lists every backend route the SDK calls. Auditing the wire surface is one
+  file read.
+
+### Fixed
+
+- Replay session fetch now hits `GET /seq/sessions/{id}` (was incorrectly
+  `GET /sessions/{id}` — 404 in production).
+- Replay matcher now compares against the BE's bare `flow.slug` (e.g.
+  `"grade-3"`), not the synthesized `org/project/slug` that fixtures
+  previously used. Replay against the real backend now actually matches
+  recorded executions.
+- `SessionExecution` model aligned with BE schema: `status` includes
+  `"pending"` and `"cancelled"`; `flow_id`, `slug`, `trigger_type`,
+  `trace_capture_mode`, and `error_at_step` are now Optional so the SDK
+  does not crash when the underlying flow has been deleted.
+- Reserved-header guard on `extra_headers=`: a misconfigured caller cannot
+  overwrite `Authorization`, `X-Noukai-API-Version`, `User-Agent`,
+  `X-Request-ID`, `Content-Type`, or `Cookie` via per-request headers.
+- Unified `Flow.execute() / steps() / events()` REPLAY-mode dispatch — all
+  three now apply the same rule when an explicit `session_id` matches or
+  differs from the scope. Previously `events()` and `steps()` made a live
+  call for explicit-sid-matching-scope, asymmetric with `execute()`.
+- Session-id precedence chain uses `is not None` instead of `or`, so an
+  explicit empty-string `session_id=""` is no longer silently overridden
+  by the next tier.
+
+### Internal
+
+- Transport `request()` and `stream()` accept an `extra_headers=` kwarg; used
+  by the replay subsystem to inject `X-Session-Id` / `X-Noukai-Replay` without
+  touching the public client surface.
+- Log handler receives `scope_open` and `scope_close` events with `mode`
+  (`"normal"` | `"capture"` | `"replay"`) and `session_id` fields.
+
+### Requires
+
+- Backend session-grouping endpoint per BE design
+  `20260605-BE-execution-session-grouping` (`GET /seq/sessions/{id}`,
+  `X-Session-Id` header on `/execute` + `/step` routes).
+
+## [0.1.0] — 2026-05-31
+
+### Added
+- Initial release.
+- `Noukai` and `AsyncNoukai` clients (sync + async).
+- `flow.execute()`, `flow.execute_async()`, `flow.steps()`, `flow.events()`.
+- `flow.run(id).trace()`, `step_trace()`, `live_trace()`.
+- Tool-call auto-resume via `tool_handler=`; manual mode via `PausedResult.resume()`.
+- Typed Pydantic event hierarchy for SSE streams.
+- Exception hierarchy mapped to HTTP status; server error codes on `.code`.
+
+[Unreleased]: https://github.com/noukai/noukai-python/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/noukai/noukai-python/releases/tag/v0.1.0

noukai_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abigcircle
+
+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.