Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,8 @@ jobs:
uv run --locked python scripts/generate.py --check
uv run --locked mypy
uv run --locked pytest
- name: Build and install the Python SDK distributions
run: scripts/release/build-python-sdk.sh "$RUNNER_TEMP/python-dist"
- run: npm ci
- name: Check every Node consumer and integration boundary
env:
Expand Down
51 changes: 50 additions & 1 deletion .github/workflows/release-tag.yml
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,31 @@ jobs:
echo "version=$LIGHTSPEED_PRODUCT_VERSION" >> "$GITHUB_OUTPUT"
echo "staging_tag=staging-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "$GITHUB_OUTPUT"

python:
needs: identity
runs-on: ubuntu-latest
outputs:
artifact_id: ${{ steps.upload.outputs.artifact-id }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ needs.identity.outputs.sha }}
- uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
version: 0.13.8
python-version: "3.12"
cache-dependency-glob: clients/python/uv.lock
- run: scripts/release/build-python-sdk.sh "$RUNNER_TEMP/python-dist"
- id: upload
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: python-sdk-${{ github.run_id }}-${{ github.run_attempt }}
path: |
${{ runner.temp }}/python-dist/*.whl
${{ runner.temp }}/python-dist/*.tar.gz
if-no-files-found: error
retention-days: 30

linux:
needs: identity
runs-on: [self-hosted, linux, x64, hz01, protected]
Expand Down Expand Up @@ -311,8 +336,32 @@ jobs:
if-no-files-found: error
retention-days: 30

publish-python:
needs: [build, python]
runs-on: ubuntu-latest
environment: official-release
permissions:
id-token: write
steps:
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
with:
artifact-ids: ${{ needs.python.outputs.artifact_id }}
path: python-dist
merge-multiple: true
- uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
version: 0.13.8
enable-cache: false
- name: Publish the verified wheel and source distribution to PyPI
env:
VERSION: ${{ needs.build.outputs.version }}
run: |
uv publish --trusted-publishing always --check-url https://pypi.org/simple/ \
"python-dist/lightspeed_ai_sdk-${VERSION}-py3-none-any.whl" \
"python-dist/lightspeed_ai_sdk-${VERSION}.tar.gz"

publish-release:
needs: build
needs: [build, publish-python]
runs-on: [self-hosted, linux, x64, hz01, protected]
environment: official-release
permissions:
Expand Down
38 changes: 23 additions & 15 deletions clients/python/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ remain full-authority infrastructure credentials.

```python
from uuid import uuid4
from lightspeed_ai import AsyncLightspeedClient
from lightspeed import AsyncLightspeedClient

async with AsyncLightspeedClient(
"https://lightspeed.example", token=platform_key
Expand All @@ -40,7 +40,7 @@ administrators supply an explicit `initialOwner` when provisioning. Native helpe
take one parameter dictionary using API field names. The same operations are
available through typed `client.call`, for example
`await client.call("platform/organizations/list")`. Native parameter and result types
live in `lightspeed_ai.platform_types`.
live in `lightspeed.platform_types`.

For local scripts, reuse the named or selected connection saved by `lightspeed login`
or `lightspeed connect add`:
Expand Down Expand Up @@ -70,11 +70,19 @@ its user is an organization Admin. API keys cannot mint other keys.
Requires Python 3.12 or newer. [HTTPX](https://www.python-httpx.org/) is the only
runtime dependency.

Install from the repository, at the tag of your Lightspeed release, because the
client's types follow that release's API:
Install the stable SDK from PyPI:

```bash
python -m pip install "lightspeed-ai @ git+https://github.com/smartcomputer-ai/lightspeed@v<release-version>#subdirectory=clients/python"
python -m pip install lightspeed-ai-sdk
```

Import the SDK with `from lightspeed import AsyncLightspeedClient`. The client's
types follow the Lightspeed release. Pin `lightspeed-ai-sdk==<release-version>`
to match your deployment. For a release that predates PyPI publication, install
from its Git tag and use the import shown in that tag's README:

```bash
python -m pip install "git+https://github.com/smartcomputer-ai/lightspeed@v<release-version>#subdirectory=clients/python"
```

From a checkout, `python -m pip install ./clients/python` installs the same package.
Expand All @@ -88,7 +96,7 @@ You need the gateway's `/api/v1` URL, a
import asyncio
import os

from lightspeed_ai import AsyncLightspeedClient
from lightspeed import AsyncLightspeedClient


async def main() -> None:
Expand Down Expand Up @@ -300,7 +308,7 @@ merges them into one list in the order they happened, with each tool call joined
result:

```python
from lightspeed_ai import run_timeline
from lightspeed import run_timeline

run = (await client.read_run(session_id, run_id))["run"]

Expand All @@ -324,12 +332,12 @@ To keep a view current, follow the run with `await_run` and read it again when

## Types

`lightspeed_ai.types` holds every type in the API, named as the API names them and
`lightspeed.types` holds every type in the API, named as the API names them and
documented from the contract. Each variant of a tagged union is named after its tag,
and checking the tag narrows the type:

```python
from lightspeed_ai.types import SessionEventView
from lightspeed.types import SessionEventView


def failure_message(event: SessionEventView) -> str | None:
Expand Down Expand Up @@ -360,9 +368,9 @@ new ones.
## Write workflow code

Temporal workflows that receive tool calls from an integrated session import
`lightspeed_ai.workflow`. It has the contract's signal, query and activity names, and
`lightspeed.workflow`. It has the contract's signal, query and activity names, and
helpers for parsing envelopes, deriving IDs, fingerprinting recipes, and building
replies. `lightspeed_ai.workflow_types` has the generated types, which work as the type
replies. `lightspeed.workflow_types` has the generated types, which work as the type
hints Temporal decodes workflow arguments and signals from, such as
`WorkflowToolStartArgs` and `EmissionEnvelope`. The module depends on no Temporal
package and is deterministic. Its functions raise `ValueError` for a value the contract
Expand All @@ -382,14 +390,14 @@ from temporalio import workflow
from temporalio.exceptions import ApplicationError

with workflow.unsafe.imports_passed_through():
from lightspeed_ai.workflow import (
from lightspeed.workflow import (
DELIVER_EMISSION_SIGNAL,
REPLY_COMPLETION_KEY,
WORKFLOW_TOOL_RECOVERY_QUERY,
reply_promise_id,
source_resolution_envelope,
)
from lightspeed_ai.workflow_types import (
from lightspeed.workflow_types import (
PromiseResolution,
WorkflowToolRecoveryResult,
WorkflowToolStartArgs,
Expand Down Expand Up @@ -452,13 +460,13 @@ recovery query answers from those keys. A bound receiver takes `EmissionEnvelope
The types, method tables, and most helpers are generated from the committed contracts in
`crates/api/contract/` and `crates/temporal-workflow/contract/`, so don't edit
`types.py`, `_generated.py`, `workflow_types.py`, or `_workflow_manifest.py` under
`src/lightspeed_ai/` by hand. Helpers come from the TypeScript SDK's
`src/lightspeed/` by hand. Helpers come from the TypeScript SDK's
inventory, [`clients/typescript/scripts/helpers.mjs`](../typescript/scripts/helpers.mjs),
which the generator reads with Node.js. It requires one named helper for every
runtime operation, rejects name collisions and missing implementations, and checks
that handwritten helpers expose the complete wire parameters and transport. The
helper table above is generated from that same inventory. Helpers that need behavior
of their own live in `src/lightspeed_ai/client.py`; native Platform names come from
of their own live in `src/lightspeed/client.py`; native Platform names come from
its shared contract.

With [uv](https://docs.astral.sh/uv/) and Node.js installed, from `clients/python`:
Expand Down
6 changes: 3 additions & 3 deletions clients/python/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ requires = ["hatchling>=1.27,<2"]
build-backend = "hatchling.build"

[project]
name = "lightspeed-ai"
name = "lightspeed-ai-sdk"
version = "0.12.0"
description = "Async Python SDK for the Lightspeed HTTP API"
readme = "README.md"
Expand All @@ -27,7 +27,7 @@ dev = [
]

[tool.hatch.build.targets.wheel]
packages = ["src/lightspeed_ai"]
packages = ["src/lightspeed"]

[tool.pytest.ini_options]
asyncio_mode = "auto"
Expand All @@ -36,4 +36,4 @@ testpaths = ["tests"]

[tool.mypy]
strict = true
files = ["src/lightspeed_ai", "tests/typing_examples.py"]
files = ["src/lightspeed", "tests/typing_examples.py"]
2 changes: 1 addition & 1 deletion clients/python/scripts/generate.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
CONTRACT = CLIENTS.parent / "crates/api/contract"
PLATFORM_CONTRACT = CLIENTS.parent / "platform/shared/contract"
WORKFLOW_CONTRACT = CLIENTS.parent / "crates/temporal-workflow/contract"
OUTPUT = PACKAGE / "src/lightspeed_ai"
OUTPUT = PACKAGE / "src/lightspeed"
BANNER = "# Generated by clients/python/scripts/generate.py. Do not edit.\n"


Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
"""Async Python client for the Lightspeed API.

`AsyncLightspeedClient` is the entry point. Wire types live in
`lightspeed_ai.types` and are generated from the Lightspeed API contract.
`lightspeed_ai.workflow` has helpers for Temporal workflow code.
`lightspeed.types` and are generated from the Lightspeed API contract.
`lightspeed.workflow` has helpers for Temporal workflow code.
"""

from . import types, platform_types
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
A workflow that receives tool calls from an integrated session, or answers
them, uses this module for the contract's names, IDs and envelopes. It depends
on no Temporal package and does nothing but hash, compare and validate, so it
is deterministic. `lightspeed_ai.workflow_types` holds the contract's types.
is deterministic. `lightspeed.workflow_types` holds the contract's types.

Every function raises `ValueError` for a value the contract does not allow.
"""
Expand Down
2 changes: 1 addition & 1 deletion clients/python/tests/live_platform_connections.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
import pytest
import httpx

from lightspeed_ai import AsyncLightspeedClient, LightspeedApiError
from lightspeed import AsyncLightspeedClient, LightspeedApiError


async def typescript_check(directory: Path, name: str, mode: str, blob_ref: str = "") -> dict:
Expand Down
6 changes: 3 additions & 3 deletions clients/python/tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
import httpx
import pytest

from lightspeed_ai import (
from lightspeed import (
CLIENT_HELPERS,
MANUAL_CLIENT_HELPERS,
OPERATION_INFO,
Expand All @@ -18,8 +18,8 @@
LightspeedApiError,
LightspeedTransportError,
)
from lightspeed_ai import client as implementation
from lightspeed_ai._http import HTTP_OPERATIONS
from lightspeed import client as implementation
from lightspeed._http import HTTP_OPERATIONS

PARITY = json.loads((Path(__file__).resolve().parents[2] / "fixtures/gateway-parity.json").read_text())

Expand Down
6 changes: 3 additions & 3 deletions clients/python/tests/test_connections.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@
import httpx
import pytest

from lightspeed_ai import AsyncLightspeedClient, LightspeedApiError, LightspeedTransportError
from lightspeed_ai._endpoint import normalize_endpoint
from lightspeed_ai import _connection
from lightspeed import AsyncLightspeedClient, LightspeedApiError, LightspeedTransportError
from lightspeed._endpoint import normalize_endpoint
from lightspeed import _connection

ENDPOINTS = json.loads((Path(__file__).resolve().parents[2] / "fixtures/endpoints.json").read_text())

Expand Down
2 changes: 1 addition & 1 deletion clients/python/tests/test_gateway_live.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

import pytest

from lightspeed_ai import AsyncLightspeedClient
from lightspeed import AsyncLightspeedClient

pytestmark = pytest.mark.skipif(
os.getenv("LIGHTSPEED_TEST_GATEWAY") != "1", reason="opt-in test requires a configured local gateway",
Expand Down
2 changes: 1 addition & 1 deletion clients/python/tests/test_platform.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
import httpx
import pytest

from lightspeed_ai import AsyncLightspeedClient, LightspeedApiError
from lightspeed import AsyncLightspeedClient, LightspeedApiError


async def test_native_platform_uses_shared_credentials_and_preserves_path_prefix():
Expand Down
2 changes: 1 addition & 1 deletion clients/python/tests/test_timeline.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
from lightspeed_ai import run_timeline
from lightspeed import run_timeline


def test_timeline_merges_call_entries_and_preserves_in_flight_calls():
Expand Down
4 changes: 2 additions & 2 deletions clients/python/tests/test_workflow.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import pytest

from lightspeed_ai.workflow import (
from lightspeed.workflow import (
DELIVER_EMISSION_SIGNAL,
REPLY_COMPLETION_KEY,
WORKFLOW_CONTRACT_VECTORS,
Expand Down Expand Up @@ -132,7 +132,7 @@ def test_temporals_data_converter_decodes_the_generated_types():
# arguments decoded from the type hints, before any of its code runs.
from temporalio.converter import value_to_type

from lightspeed_ai import AwaitRunResult, RunTimelineItem, types, workflow_types
from lightspeed import AwaitRunResult, RunTimelineItem, types, workflow_types

assert value_to_type(workflow_types.WorkflowToolStartArgs, VECTORS["startArgs"]) == VECTORS["startArgs"]
assert value_to_type(
Expand Down
8 changes: 4 additions & 4 deletions clients/python/tests/typing_examples.py
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
from typing import assert_type
from collections.abc import AsyncIterator
from lightspeed_ai import types as Api
from lightspeed import types as Api

from lightspeed_ai import AsyncLightspeedClient, ClientConnectionResponse
from lightspeed_ai import platform_types as Platform
from lightspeed_ai.types import (
from lightspeed import AsyncLightspeedClient, ClientConnectionResponse
from lightspeed import platform_types as Platform
from lightspeed.types import (
CredentialGrantPutResponse,
McpServerPutResponse,
RunReadResponse,
Expand Down
2 changes: 1 addition & 1 deletion clients/python/uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion docs/documentation/development/changing-contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ which a test checks.
The Python generator needs [uv](https://docs.astral.sh/uv/) and Node.js. It reads the
API and workflow exports and the same helper table, and writes `types.py`,
`_generated.py`, `workflow_types.py`, and `_workflow_manifest.py` under
`clients/python/src/lightspeed_ai/`. A new helper belongs in the Python client's
`clients/python/src/lightspeed/`. A new helper belongs in the Python client's
README too, which its tests check.

The method-action generator updates `platform/backend/src/routes/method-actions.ts`:
Expand Down
14 changes: 13 additions & 1 deletion docs/documentation/development/contributing-and-releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -234,8 +234,20 @@ Pushing the tag starts publication. The protected Linux amd64 and Windows x64
environment must contain `NPM_TOKEN`. The environment only pauses publication
if approval rules have actually been configured in GitHub.

Before the first Python release, create the `lightspeed-ai-sdk` project under
**Projects** in the `lightspeed-ai` PyPI organization. [PyPI project setup](https://docs.pypi.org/organization-accounts/actions/project-actions/#create-a-project)

In the project's **Publishing** settings, add a GitHub trusted publisher.
Enter `smartcomputer-ai` as the GitHub owner, `lightspeed` as
the repository, `release-tag.yml` as the workflow filename and
`official-release` as the environment. The workflow exchanges its GitHub
identity for a short-lived PyPI upload token. [PyPI trusted publisher setup](https://docs.pypi.org/trusted-publishers/adding-a-publisher/)

The release workflow independently tests and builds the tagged source. It
does not promote an already-built main snapshot. Final publication runs
builds a Python wheel and source distribution and installs each in isolation.
After release assembly succeeds, a protected job uploads those exact files
to PyPI. On retry, it checks the hashes of files already published for that
version. Final publication runs
through the `official-release` environment, validates the staged bundle by
digest, and publishes exact-version OCI aliases, the npm package, and the
GitHub Release with its assets. Existing aliases are checked against their
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ Or use the asynchronous Python client.

```python
import asyncio
from lightspeed_ai import AsyncLightspeedClient
from lightspeed import AsyncLightspeedClient

async def main():
async with await AsyncLightspeedClient.from_connection("work") as client:
Expand Down
Loading