Skip to content

Commit bbbf79f

Browse files
committed
Add the tensicai Python SDK
1 parent 9ead5df commit bbbf79f

98 files changed

Lines changed: 34296 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
tags-ignore: ["v*"]
7+
pull_request:
8+
workflow_dispatch:
9+
10+
concurrency:
11+
group: ci-${{ github.ref }}
12+
cancel-in-progress: true
13+
14+
permissions:
15+
contents: read
16+
17+
jobs:
18+
test:
19+
name: Python ${{ matrix.python-version }}
20+
runs-on: ubuntu-latest
21+
strategy:
22+
fail-fast: false
23+
matrix:
24+
python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
25+
steps:
26+
- uses: actions/checkout@v4
27+
28+
- name: Install uv
29+
uses: astral-sh/setup-uv@v6
30+
with:
31+
python-version: ${{ matrix.python-version }}
32+
enable-cache: true
33+
34+
- name: Install dependencies
35+
# --locked: a uv.lock that no longer matches pyproject.toml fails the run
36+
# instead of being silently re-resolved (CONTRIBUTING.md documents the guarantee).
37+
run: uv sync --locked --extra dev
38+
39+
- name: Lint
40+
run: uv run ruff check src tests examples
41+
42+
- name: Format check
43+
run: uv run ruff format --check src tests examples
44+
45+
- name: Type check
46+
run: uv run mypy src examples
47+
48+
- name: Test
49+
run: uv run pytest -q
50+
51+
build:
52+
name: Build and install wheel
53+
runs-on: ubuntu-latest
54+
steps:
55+
- uses: actions/checkout@v4
56+
57+
- name: Install uv
58+
uses: astral-sh/setup-uv@v6
59+
with:
60+
python-version: "3.12"
61+
62+
- name: Build sdist and wheel
63+
run: uv build
64+
65+
- name: Check long description
66+
run: uvx twine check dist/*
67+
68+
- name: Install the wheel in a clean venv and import it
69+
run: |
70+
uv venv /tmp/clean-venv
71+
uv pip install --python /tmp/clean-venv/bin/python dist/*.whl
72+
/tmp/clean-venv/bin/python -c "import tensicai, sys; print(tensicai.__version__, sys.version)"
73+
74+
- uses: actions/upload-artifact@v4
75+
with:
76+
name: dist
77+
path: dist/

‎.github/workflows/publish.yml‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
name: Publish
2+
3+
# Releases go out through PyPI Trusted Publishing: push a tag `vX.Y.Z` that matches
4+
# `__version__` in src/tensicai/_version.py and this workflow tests, builds, verifies and
5+
# uploads. Nothing reaches PyPI unless ruff, mypy and the full test suite pass in this run.
6+
#
7+
# Production PyPI is reached ONLY by a pushed `v*` tag. A manual run (workflow_dispatch) never
8+
# publishes to pypi.org: it builds and verifies the package and, when the "testpypi" input is
9+
# enabled (the default), uploads it to TestPyPI as a rehearsal. TestPyPI needs its own pending
10+
# Trusted Publisher (environment `testpypi`) — see "Releasing" in the README.
11+
12+
on:
13+
push:
14+
tags: ["v*"]
15+
workflow_dispatch:
16+
inputs:
17+
testpypi:
18+
description: "Publish to TestPyPI (untick for a build-and-verify dry run only)"
19+
type: boolean
20+
default: true
21+
22+
permissions:
23+
contents: read
24+
25+
jobs:
26+
build:
27+
name: Build and verify
28+
runs-on: ubuntu-latest
29+
steps:
30+
- uses: actions/checkout@v4
31+
32+
- name: Install uv
33+
uses: astral-sh/setup-uv@v6
34+
with:
35+
python-version: "3.12"
36+
37+
- name: Assert the tag matches the package version
38+
if: github.event_name == 'push'
39+
run: |
40+
# Pure shell on purpose: this step gates every release, and `setup-uv` sets
41+
# UV_PYTHON rather than putting a bare `python` on PATH.
42+
version="$(sed -n 's/^__version__[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' src/tensicai/_version.py | head -1)"
43+
if [ -z "${version}" ]; then
44+
echo "::error::could not read __version__ from src/tensicai/_version.py"
45+
exit 1
46+
fi
47+
tag="${GITHUB_REF_NAME}"
48+
echo "tag=${tag} version=${version}"
49+
if [ "${tag}" != "v${version}" ]; then
50+
echo "::error::tag ${tag} does not match src/tensicai/_version.py (${version})"
51+
exit 1
52+
fi
53+
54+
# An upload to PyPI is irreversible (a version number can never be re-used), and ci.yml
55+
# runs on the branch push, in parallel, so it cannot gate this job. Run the suite here.
56+
- name: Install dependencies
57+
# --locked: a uv.lock that no longer matches pyproject.toml fails the run
58+
# instead of being silently re-resolved (CONTRIBUTING.md documents the guarantee).
59+
run: uv sync --locked --extra dev
60+
61+
- name: Lint
62+
run: uv run ruff check src tests examples
63+
64+
- name: Type check
65+
run: uv run mypy src examples
66+
67+
- name: Test
68+
run: uv run pytest -q
69+
70+
- name: Build sdist and wheel
71+
run: uv build
72+
73+
- name: Check long description
74+
run: uvx twine check dist/*
75+
76+
- name: Smoke-test the wheel
77+
run: |
78+
uv venv /tmp/clean-venv
79+
uv pip install --python /tmp/clean-venv/bin/python dist/*.whl
80+
/tmp/clean-venv/bin/python -c "import tensicai; print(tensicai.__version__)"
81+
82+
- uses: actions/upload-artifact@v4
83+
with:
84+
name: dist
85+
path: dist/
86+
if-no-files-found: error
87+
88+
publish:
89+
name: Publish to PyPI
90+
needs: build
91+
# Tag pushes only — a manual dispatch can never reach production PyPI.
92+
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
93+
runs-on: ubuntu-latest
94+
environment:
95+
name: pypi
96+
url: https://pypi.org/project/tensicai/
97+
permissions:
98+
id-token: write
99+
steps:
100+
- uses: actions/download-artifact@v4
101+
with:
102+
name: dist
103+
path: dist/
104+
105+
- name: Publish (Trusted Publishing)
106+
uses: pypa/gh-action-pypi-publish@release/v1
107+
108+
publish-testpypi:
109+
name: Publish to TestPyPI
110+
needs: build
111+
if: github.event_name == 'workflow_dispatch' && inputs.testpypi == true
112+
runs-on: ubuntu-latest
113+
environment:
114+
name: testpypi
115+
url: https://test.pypi.org/project/tensicai/
116+
permissions:
117+
id-token: write
118+
steps:
119+
- uses: actions/download-artifact@v4
120+
with:
121+
name: dist
122+
path: dist/
123+
124+
- name: Publish (Trusted Publishing, TestPyPI)
125+
uses: pypa/gh-action-pypi-publish@release/v1
126+
with:
127+
repository-url: https://test.pypi.org/legacy/
128+
skip-existing: true

‎.gitignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,3 +216,13 @@ __marimo__/
216216

217217
# Streamlit
218218
.streamlit/secrets.toml
219+
220+
# tensicai SDK: build artefacts and tool caches (uv.lock IS committed, see CONTRIBUTING.md)
221+
dist/
222+
build/
223+
*.egg-info/
224+
.venv/
225+
.mypy_cache/
226+
.ruff_cache/
227+
.pytest_cache/
228+
.python-version

‎CHANGELOG.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Changelog
2+
3+
All notable changes to this project are documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
6+
project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
Nothing yet.
11+
12+
## [0.1.0] - 2026-09-02
13+
14+
Initial release, targeting tensic.ai server 1.6 and newer.
15+
16+
### Added
17+
18+
- `Tensic` / `AsyncTensic` clients with identical APIs: env-based configuration
19+
(`TENSIC_URL`, `TENSIC_API_KEY`), API-key or username/password (`Tensic.login`, TOTP aware)
20+
authentication, `Tensic.ldap_login()` / `AsyncTensic.ldap_login()` for instances with LDAP
21+
authentication enabled (`POST /ldap`, the same cookie session as `login()`, no TOTP step),
22+
timeouts, retries with back-off and `Retry-After` support, `with_options()`,
23+
bring-your-own `httpx` client, `TENSIC_LOG=debug` logging.
24+
- `client.chat`: `send`, `stream` (typed SSE events, resume via `last_event_id`, error frames
25+
raised as `ChatStreamError`), `stop`, `upload_attachment`, `get_asset`, `conversation()`
26+
helper with turn history, automatic `Idempotency-Key` on non-streaming turns.
27+
- `client.knowledge`: text/URL/file/bulk ingestion, semantic search, source listing, chunk
28+
inspection, deletion, reset, sync and re-embed jobs.
29+
- `client.projects` with sub-resources: prompts, secrets, routines, widgets, logs,
30+
conversations, analytics, evals, memory, comments, guards, custom tools, webhooks,
31+
integrations; plus `iter()` auto-paging and `find(name)`.
32+
- `client.teams`, `client.users` (with `api_keys`), `client.llms`, `client.embeddings`,
33+
`client.tools`, `client.statistics`, `client.templates`, `client.image`, `client.audio`,
34+
`client.settings`, `client.classifiers`, `client.image_generators`,
35+
`client.speech_to_text`, `client.invitations`, `client.examples`, `client.news`,
36+
`client.search()`, `client.whoami()`, `client.version()`, and
37+
`client.health(probe="ready"|"live")` addressing either container probe route
38+
(`GET /health/ready`, `GET /health/live`).
39+
- `client.direct`: OpenAI-compatible chat completions (sync/async, streaming
40+
`ChatCompletionStream`), completions, embeddings, models, image generation, audio
41+
transcription/translation, moderations, plus `client.openai_base_url` for the official
42+
`openai` package.
43+
- `WidgetClient` / `AsyncWidgetClient` for widget-key access (`config`, `chat`, `stream`).
44+
- Typed exception hierarchy (`tensicai.errors`) parsing the tensic error envelope, legacy
45+
`detail` shapes and the OpenAI error shape, exposing `request_id`, `retry_after` and rate
46+
limit headers.
47+
- Lenient dataclass models under `tensicai.types` (unknown fields kept in `.extra`),
48+
`Page` / `ProjectsPage` pagination helpers, `py.typed`.
49+
- The request-side type aliases used by the SDK's own signatures are public, so typed wrapper
50+
code never reaches into a private module: `FileInput`, `FileContent`, `AttachmentInput`,
51+
`Timeout`, `TimeoutOrNotGiven`, `NotGiven`, `NotGivenOr` and `Probe` are exported from
52+
`tensicai` and `tensicai.types`, and the wire-value literal aliases (`Splitter`,
53+
`IngestMethod`, `Privacy`, `TemplateVisibility`) each live in exactly one domain type module.
54+
- `image=` is validated client-side: a `str` is a base64 payload or an `http(s)`/`data:` URL
55+
and is never read from disk, so a filename raises `ValueError` pointing at `Path(...)`
56+
before any request rather than sending the model a name it cannot see. `bytes` and a
57+
`pathlib.Path` are base64-encoded for you. `client.image.generate(image=...)` is stricter
58+
still — that endpoint decodes rather than fetches, so it takes base64, a `data:` URL,
59+
`bytes` or a `Path`, but not an `http(s)` URL.
60+
- Runnable examples under `examples/`, GitHub Actions CI (Python 3.10–3.14) and a PyPI
61+
Trusted Publishing release workflow.
62+
63+
### Packaging
64+
65+
- Two declared runtime dependencies: `httpx>=0.25,<1` and `anyio>=3.5`. `anyio` is imported
66+
directly by the async client (retry back-off sleeps, threaded file reads for `Path`/file-object
67+
uploads) and is declared in its own right rather than relied on transitively through
68+
httpx/httpcore.
69+
- PyPI metadata: `authors` names team.blue (`pedro.dias@team.blue`) with the individual under
70+
`maintainers`; the license is the PEP 639 expression `Apache-2.0` with no deprecated
71+
`License ::` classifier; `Programming Language :: Python :: 3 :: Only` is declared. The
72+
project URLs are `Documentation` (the README), `Repository`, `Issues`, `Architecture`
73+
(docs/INTERNALS.md, the contributor guide) and `Changelog` — every link points at a host we
74+
control, never at the parked `tensic.cloud` domain.
75+
- The sdist ships `.github/` and `Makefile` alongside `tests/`, so the test suite it carries
76+
passes from an extracted sdist and the `make` targets CONTRIBUTING.md documents run there.
77+
- CI and the release workflow install with `uv sync --locked`, so a `uv.lock` that no longer
78+
matches `pyproject.toml` fails the run instead of being silently re-resolved.
79+
- `publish.yml` runs ruff, mypy and the full test suite before building, so a tag push cannot
80+
upload to PyPI ahead of (or despite) a red CI run.
81+
82+
[Unreleased]: https://github.com/tensicai/python-sdk/compare/v0.1.0...HEAD
83+
[0.1.0]: https://github.com/tensicai/python-sdk/releases/tag/v0.1.0

0 commit comments

Comments
 (0)