tensormesh 0.1.0

Tensormesh Python SDK with CLI support.

Tensormesh SDK

Python SDK and CLI for Tensormesh AI inference and control-plane management.

Install

pip install tensormesh

Python SDK Quick Start

from tensormesh import Tensormesh
from tensormesh.types import ChatMessage

# Inference
with Tensormesh(inference_api_key="YOUR_INFERENCE_API_KEY") as client:
    completion = client.inference.serverless.chat.completions.create(
        model="SERVERLESS_MODEL_NAME",
        messages=[ChatMessage(role="user", content="Say hello.")],
    )
print(completion.choices[0].message.content)

# Control Plane
with Tensormesh(control_plane_token="YOUR_CONTROL_PLANE_TOKEN") as client:
    profile = client.control_plane.users.get_auth_profile()
    models = client.control_plane.models.list()

Full SDK docs: docs/sdk/index.mdx

---

Repository

This repository has three primary surfaces:

• A published-docs path for the Python SDK under docs/sdk/
• A Mintlify docs site under docs/ for Tensormesh inference APIs and generated Control Plane API reference.
• A library-first Python SDK under src/tensormesh/, with a Python CLI, tm, under src/tensormesh_cli/ consuming that SDK for Control Plane and inference workflows.

Supporting scripts live under scripts/ for bootstrap, docs/spec sync, validation, and network verification.

No credentials are required for most local validation. npm run sync, npm test, npm run verify, and the default GitHub Actions verify workflow are all designed to run without Control Plane or gateway secrets. Credentials are only needed for the optional live network checks. For SaaS upgrade checks against the latest published SDK wheel, use npm run verify:released-client-compatibility, which is also wired into the same-repo reusable/manual GitHub Actions workflow .github/workflows/released-client-compatibility.yml.

Release-facing docs:

• CHANGELOG.md
• dev/sdk-release-policy.md

Main Components

• docs/api-reference/src/*.yaml: canonical inference API source inputs
• docs/api-reference/on-demand.openapi.yaml: generated On-Demand inference OpenAPI output
• docs/api-reference/serverless.openapi.yaml: generated Serverless inference OpenAPI output
• openapi/tensormesh/**/*.swagger.json: canonical Control Plane Swagger sources
• openapi/.generated/tensormesh-api/specs/**/*.openapi.json: normalized generated Control Plane OpenAPI outputs
• docs/openapi/.generated/tensormesh-api/published-specs/**/*.openapi.json: published generated Control Plane OpenAPI outputs materialized locally for docs validation
• docs/docs.base.json: hand-maintained Mintlify config source
• docs/docs.json: generated Mintlify config and navigation
• src/tensormesh/: Tensormesh Python SDK implementation
• src/tensormesh_cli/: Tensormesh CLI implementation
• scripts/: bootstrap, sync, verify, and e2e helpers

Prerequisites

• Node.js 22 LTS recommended (see .nvmrc; CI and Mintlify require a modern Node runtime)
• Python 3.12 for repo scripts and the local venv
• jq for Swagger-to-OpenAPI conversion and network verification scripts

macOS example:

brew install node@22 jq
export PATH="/opt/homebrew/opt/node@22/bin:$PATH"

Quickstart

1. Bootstrap the repo:

npm run bootstrap

2. Start the docs site locally:

npm run dev

3. Optional: log in to the Control Plane:

./.venv/bin/tm auth login
./.venv/bin/tm auth whoami

4. Optional: sync managed gateway config and run a gateway smoke test:

./.venv/bin/tm auth login
./.venv/bin/tm init --sync

./.venv/bin/tm infer chat \
  --json '[{"role":"user","content":"Say hello."}]'

tm init --sync fetches the gateway provider, API key, user id, and served model name from the Control Plane, then stores them under [managed] in ~/.config/tensormesh/config.toml.

gateway_api_key is the CLI config name for the same underlying inference API key the SDK accepts as inference_api_key, and gateway_model_id remains a config compatibility key whose value is the served model name sent as model.

@latest resolves from Control Plane model inventory, so it still requires valid gateway credentials plus Control Plane auth:

./.venv/bin/tm infer chat \
  --model @latest \
  --json '[{"role":"user","content":"Say hello."}]'

Python SDK

The repository packages a library-first Python SDK from src/tensormesh/ with parallel sync and async clients.

Start with the published SDK docs:

• docs/sdk/index.mdx
• docs/sdk/guides/getting-started.mdx
• docs/sdk/guides/auth-and-config.mdx
• docs/sdk/guides/inference.mdx
• docs/sdk/guides/control-plane.mdx
• docs/cli/guides/control-plane-workflows.mdx
• docs/tensormesh-api/index.mdx

The CLI ships in the same distribution and consumes the SDK internally, but external Python applications should start from the SDK docs rather than the CLI setup flow.

Basic serverless inference:

from tensormesh import Tensormesh
from tensormesh.types import ChatMessage

with Tensormesh(
    inference_api_key="YOUR_INFERENCE_API_KEY",
) as client:
    completion = client.inference.serverless.chat.completions.create(
        model="SERVERLESS_MODEL_NAME",
        messages=[ChatMessage(role="user", content="Say hello.")],
    )

print(completion.choices[0].message.content)

Streaming on-demand inference:

from tensormesh import Tensormesh
from tensormesh.types import ChatMessage

with Tensormesh(
    inference_api_key="YOUR_INFERENCE_API_KEY",
    on_demand_base_url="https://external.nebius.tensormesh.ai",
    on_demand_user_id="00000000-0000-0000-0000-000000000000",
) as client:
    stream = client.inference.on_demand.chat.completions.create(
        model="SERVED_GATEWAY_MODEL_NAME",
        messages=[ChatMessage(role="user", content="Stream a short reply.")],
        stream=True,
    )

    for text in stream.text_deltas():
        print(text, end="")

Async serverless inference:

import asyncio

from tensormesh import AsyncTensormesh
from tensormesh.types import ChatMessage


async def main() -> None:
    async with AsyncTensormesh(
        inference_api_key="YOUR_INFERENCE_API_KEY",
    ) as client:
        completion = await client.inference.serverless.chat.completions.create(
            model="SERVERLESS_MODEL_NAME",
            messages=[ChatMessage(role="user", content="Say hello.")],
        )
        print(completion.choices[0].message.content)


asyncio.run(main())

Control plane user profile lookup:

from tensormesh import Tensormesh

with Tensormesh(control_plane_token="YOUR_CONTROL_PLANE_TOKEN") as client:
    profile = client.control_plane.users.get_auth_profile()

print(profile.display_name)

Control plane billing and support:

from tensormesh import Tensormesh

with Tensormesh(control_plane_token="YOUR_CONTROL_PLANE_TOKEN") as client:
    balance = client.control_plane.billing.balance.get()
    tickets = client.control_plane.support.tickets.list(size=20)

print(balance.units if balance is not None else "0")
print([ticket.subject for ticket in tickets.tickets])

Auto-pagination for paged control-plane resources:

from tensormesh import Tensormesh

with Tensormesh(control_plane_token="YOUR_CONTROL_PLANE_TOKEN") as client:
    for transaction in client.control_plane.billing.transactions.auto_paging_iter(
        page_size=100,
    ):
        print(transaction.transaction_id, transaction.amount)

Raw and streaming inference responses:

from tensormesh import AsyncTensormesh
from tensormesh import Tensormesh
from tensormesh.types import ChatMessage

with Tensormesh(inference_api_key="YOUR_INFERENCE_API_KEY") as client:
    raw_response = client.inference.serverless.chat.completions.with_raw_response.create(
        model="SERVERLESS_MODEL_NAME",
        messages=[ChatMessage(role="user", content="Say hello.")],
    )
print(raw_response.json())


async def inspect_stream() -> None:
    async with AsyncTensormesh(
        inference_api_key="YOUR_INFERENCE_API_KEY",
    ) as async_client:
        raw_stream = await async_client.inference.serverless.chat.completions.with_streaming_response.create(
            model="SERVERLESS_MODEL_NAME",
            messages=[ChatMessage(role="user", content="Stream a short reply.")],
        )
        async for line in raw_stream.iter_lines():
            print(line)

Environment And Auth

For Python applications, prefer explicit SDK configuration through constructor arguments or environment variables. The SDK does not read CLI config or auth files by default.

The bullets below describe CLI and local-operator behavior:

• The standard persistent CLI setup lives under ~/.config/tensormesh/.
• Set TM_CONFIG_HOME when you want the CLI to use a different local root for both config.toml and auth.json.
• The SDK default Control Plane base in this repo is https://api.gcpstaging.tensormesh.ai, and it can be overridden with control_plane_base_url or TENSORMESH_CONTROL_PLANE_BASE_URL.
• The CLI resolves the same host via --controlplane-base, TENSORMESH_CONTROL_PLANE_BASE_URL, or top-level controlplane_base in config.toml.
• ./.venv/bin/tm auth login stores Control Plane tokens in ~/.config/tensormesh/auth.json.
• ./.venv/bin/tm config init writes the canonical config file to ~/.config/tensormesh/config.toml.
• ./.venv/bin/tm init --sync updates [managed] in ~/.config/tensormesh/config.toml.
• Global CLI options such as --output must come before the subcommand: tm --output json auth status.
• Control Plane auth is always read from ~/.config/tensormesh/auth.json.
• ./.venv/bin/tm auth whoami is the live bearer-token check and uses GET /auth/profile.
• ./.venv/bin/tm auth print-token --yes-i-know prints the raw bearer token for controlled scripts.
• On-Demand inference commands normally read provider, API key, user id, and served model name from [managed] in ~/.config/tensormesh/config.toml.

Example:

./.venv/bin/tm auth login
./.venv/bin/tm init --sync
./.venv/bin/tm config show --sources

Common Commands

• npm run bootstrap: install Node deps, create .venv, and run local validation
• ./scripts/lint-shell.sh: lint repo shell scripts using shellcheck from your PATH or ./.venv/bin
• npm run build:python-dist: build SDK-first Python wheel artifacts, checksums, and the release manifest under dist/python
• npm run dev: start Mintlify locally
• npm run doctor: check local prerequisites and repo state
• npm run clean: remove local caches and build artifacts
• npm run sync: regenerate generated Control Plane OpenAPI outputs, semi-generated control-plane SDK resources, async SDK mirrors, inference OpenAPI outputs, CLI reference pages, and docs navigation
• npm test: run the fast network-free local verification path without regen
• npm run verify:python: run compile, ShellCheck, Ruff, and Python tests with coverage
• npm run verify:compatibility: run opt-in compatibility tests for removed surfaces and migration behavior
• npm run verify:dist: build fresh wheel and source-distribution artifacts, then smoke-test the packaged SDK+CLI install paths
• ./scripts/smoke-test-python-sdist.sh: smoke-test an installed source distribution artifact
• npm run verify: run sync plus CI-parity local validation without network probes
• npm run verify:network: run live auth and gateway smoke tests using configured credentials, including the opt-in pytest smoke under tests/integration/
• ./.venv/bin/tm --help: inspect the current CLI surface

CI

• GitHub Actions CI is token-free. verify.yml runs docs/spec validation, Python linting, unit tests with coverage, and dist packaging smoke tests without requiring Control Plane or gateway credentials.

Documentation Map

Use these docs by audience and task:

• Getting started with the repo: README.md
• Developer setup and local environment: dev/setup.md
• Validation, CI parity, release flow, and network verification: dev/workflows.md
• CLI guides and command reference: docs/cli/index.mdx
• Docs/OpenAPI generation pipeline: dev/docs-system.md
• Mintlify hosting/proxy operational requirements: dev/runbook-mintlify-hosting.md
• Troubleshooting setup, TLS, and local verification: dev/troubleshooting.md
• Contributing expectations and generated-file rules: CONTRIBUTING.md
• Security reporting: SECURITY.md
• Docs site landing page and published API reference: docs/index.mdx

Generated Files

• Do not hand-edit openapi/.generated/tensormesh-api/specs/**/*.openapi.json.
• Do not hand-edit docs/openapi/.generated/tensormesh-api/published-specs/**/*.openapi.json.
• Do not hand-edit docs/cli/reference/**/*.mdx.
• Update the source Swagger under openapi/tensormesh/ and regenerate with npm run sync, which rebuilds the normalized raw specs, republishes the docs-facing specs, and refreshes the semi-generated SDK control-plane resource modules.
• Hand-maintain docs/docs.base.json and let npm run sync regenerate docs/docs.json.
• docs/tensormesh-api/publish-manifest.json declares merged published Control Plane nav specs such as the combined Model surface.
• docs/cli/reference/**/*.mdx is generated from the Click command tree plus structured metadata attached in src/tensormesh_cli/docs_meta.py.

Governance

• Contributing guide
• Security policy
• License