Metadata-Version: 2.4
Name: ThinkPlatform-client
Version: 0.6.103
Summary: CLI and Python SDK for the ThinkPlatform API.
Author: ThinkPlatform team
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic
Requires-Dist: azure-identity>=1.25.3
Requires-Dist: msal-extensions>=1.3.1
Requires-Dist: click>=8.1.7
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: PyYAML>=6
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# ThinkPlatform Client

ThinkPlatform Client provides the `tp` command-line interface and Python SDK for working with a ThinkPlatform service. Install it into a supported Python environment and connect it to a service URL and credentials supplied by your deployment.

## Install

```bash
python -m pip install --upgrade pip
python -m pip install ThinkPlatform-client
```

The public binary wheels target CPython 3.11–3.13 on Linux x86_64 (glibc 2.28 or newer), macOS 11 or newer on Apple silicon (arm64), and Windows x86_64. Source distributions are not published. Other Python versions and platforms are outside the public wheel support matrix. Use a fresh virtual environment if migrating from a full ThinkPlatform runtime installation.

## Command line

```bash
tp --help
tp auth login
tp auth whoami
tp orgs
```

With no deployment settings configured, the CLI uses `https://thinkplatform.ai`, API audience `api://04d6aecc-4540-463a-87e3-4024ffad7428`, and interactive-browser sign-in through a shared public client registration. The built-in tenant is `5a959e94-a278-467d-ab33-d59909a75bad`; the built-in CLI application ID is `709439d2-4a99-44c2-8c35-9b1e71cc2e34`. These are non-secret public application settings. Users do not need to register an app per installation or provide a client secret.

The registration is single-tenant, supports the `http://localhost` loopback redirect, and has device-code public-client flow enabled. Your organization may require administrator consent. A successful sign-in does not grant ThinkPlatform membership or resource permissions. The CLI uses the same REST client as the SDK.

For production browser/device authentication, the CLI stores tokens in the operating system's encrypted credential store and keeps a separate non-secret account record under `~/.config/thinkplatform/auth/`. Later CLI processes reuse the account silently until Azure requires sign-in again. SDK `client_from_profile()` uses the same secure cache. If encrypted OS storage is unavailable, authentication fails closed without writing tokens in plaintext. On headless Linux without Secret Service, use Azure CLI authentication instead.

On macOS, this uses a dedicated `ThinkPlatform CLI` Keychain item. macOS may ask you to allow the Python interpreter to access it. A one-time permission can prompt again on later accesses; persistent permission is an optional trust decision for that interpreter. Changing Python installations can also require permission again. Older preview versions used a Microsoft shared item; the CLI does not read or migrate that item, so sign in again after upgrading if needed. Workspace managed-identity authentication does not use this local user cache.

### Custom deployments and sign-in

For a different deployment, set its URL and API audience explicitly. An existing configured deployment that has no explicit auth mode continues to use `azure-cli`; use the mode approved for that deployment. These environment variables can be replaced by CLI options or a saved CLI profile:

```bash
export THINKPLATFORM_API_BASE_URL="https://thinkplatform.example"
export THINKPLATFORM_API_AUDIENCE="api://<api-application-id>"
export THINKPLATFORM_AUTH_MODE="azure-cli"
tp auth login
```

The examples use POSIX shell syntax; on PowerShell set environment variables with `$env:NAME = "value"`. Azure CLI is a separate installation. Its credential uses the signed-in Azure CLI identity; the API must allow that identity and consent must permit access to its resource. Signing in alone does not establish service access. See [Microsoft's Azure CLI credential documentation](https://learn.microsoft.com/en-us/python/api/azure-identity/azure.identity.azureclicredential?view=azure-python).

For browser or device-code sign-in to a different deployment, provide its approved **public client** application ID and tenant:

```bash
export THINKPLATFORM_AZURE_CLIENT_ID="<cli-public-client-application-id>"
tp --auth-mode device-code whoami
# Or, on a machine with a local browser:
tp --auth-mode interactive-browser whoami
```

Keep `THINKPLATFORM_API_AUDIENCE` configured for the target API. The API audience identifies the **target API**; `THINKPLATFORM_AZURE_CLIENT_ID` identifies the **sign-in client**. They serve different purposes. The CLI requests the API audience with `/.default` appended. Set the audience explicitly rather than relying on the legacy `AZURE_CLIENT_ID` audience fallback, which can accidentally target the sign-in client instead of the API.

The production CLI defaults apply only when the effective URL and audience are exactly `https://thinkplatform.ai` and `api://04d6aecc-4540-463a-87e3-4024ffad7428`, with browser or device-code auth selected. Explicit client ID and tenant environment variables override the built-in values. For custom URL/audience combinations, set the deployment's approved IDs yourself. Tenant lookup prefers `THINKPLATFORM_AZURE_TENANT_ID` over `AZURE_TENANT_ID`; client ID lookup prefers `THINKPLATFORM_AZURE_CLIENT_ID` over `AZURE_CLIENT_ID`. Client ID and tenant are read from the environment rather than stored in CLI profiles. The base URL, audience, auth mode, and connection settings can be selected through CLI flags or profiles.

For custom deployments, administrators should provision and validate a dedicated CLI public-client registration, configure its delegated API permissions and required tenant consent, and distribute the non-secret client ID, tenant and API audience to users. Users can share that approved registration; they do not need to create an app per installation. Choose the supported account/tenant configuration for the deployment. Do not distribute a client secret or reuse a confidential web application's credentials. Device-code sign-in requires public client flows to be enabled. Browser sign-in uses a local loopback redirect; this CLI leaves the port selection to Azure Identity, so configure `http://localhost` under the Mobile and desktop applications platform in the registration. See [Microsoft's public-client setup guidance](https://learn.microsoft.com/en-us/azure/developer/python/sdk/authentication/additional-methods) and [desktop application configuration](https://learn.microsoft.com/en-us/entra/identity-platform/scenario-desktop-app-configuration). A registration is ready for onboarding only after both the Entra configuration and API admission have been verified for that deployment.

`workspace-delegation` is for a provisioned workspace using managed identity and a workspace assertion; its optional client ID selects a user-assigned managed identity, not a desktop sign-in registration. `execution-delegation` uses an API-issued execution token bound to its service and org/project context. Obtain these configurations from the workspace or execution environment rather than setting a public-client ID for them.

## Python SDK

```python
from thinkplatform.sdk import ThinkPlatformClient
from thinkplatform.sdk.credentials import AzureCliCredential

client = ThinkPlatformClient(
    base_url="https://thinkplatform.example",
    audience="api://your-service",
    credential=AzureCliCredential(),
)

user = client.auth.whoami()
organizations = client.organizations.list()
```

The SDK also provides profile and environment based client factories, typed resource clients, and context helpers. Flow and Agent API operations are available without installing their execution engines.

## Compatibility and security

The CLI and SDK are clients for an existing ThinkPlatform service; they do not include the service or grant access to it. The service remains responsible for authenticating requests and enforcing authorization. Cython wheels omit the original Python implementation files, but compiled code, names, documentation strings, and string constants can still be inspected. Do not treat the wheel format as a security boundary or put secrets in client code.
