promptic-sdk 0.2.0__tar.gz

promptic_sdk-0.2.0/LICENSE

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

promptic_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: promptic-sdk
+Version: 0.2.0
+Summary: Python SDK for the Promptic platform — tracing, API client, and CLI.
+Author: Promptic GmbH
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: typer>=0.15.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli>=2.0.0 ; python_full_version < '3.11'
+Requires-Dist: promptic-sdk[openai,anthropic,langchain] ; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-anthropic>=0.30b0 ; extra == 'anthropic'
+Requires-Dist: opentelemetry-instrumentation-langchain>=0.30b0,!=0.53.0 ; extra == 'langchain'
+Requires-Dist: opentelemetry-instrumentation-openai>=0.30b0 ; extra == 'openai'
+Requires-Python: >=3.11
+Provides-Extra: all
+Provides-Extra: anthropic
+Provides-Extra: langchain
+Provides-Extra: openai
+Description-Content-Type: text/markdown
+
+# Promptic Python SDK
+
+Python SDK and CLI for the [Promptic](https://promptic.eu) platform — tracing, prompt optimization, and experiment management.
+
+## Installation
+
+```bash
+pip install promptic-sdk
+```
+
+### Optional LLM instrumentation
+
+Install extras to auto-instrument specific LLM providers:
+
+```bash
+pip install promptic-sdk[openai]       # OpenAI
+pip install promptic-sdk[anthropic]    # Anthropic
+pip install promptic-sdk[langchain]    # LangChain
+pip install promptic-sdk[all]          # All providers
+```
+
+## Quick start
+
+### 1. Authenticate
+
+Log in via browser (recommended for local development):
+
+```bash
+promptic login
+```
+
+This opens your browser for authentication, then auto-selects your workspace. Credentials are saved to `~/.promptic/config.toml`.
+
+For CI/CD or headless environments, use an API key instead:
+
+```bash
+promptic configure
+# or set the environment variable:
+export PROMPTIC_API_KEY="pk_..."
+```
+
+### 2. Send traces
+
+```python
+import promptic_sdk
+from openai import OpenAI
+
+# Initialize tracing (auto-instruments installed LLM libraries)
+promptic_sdk.init()
+
+client = OpenAI()
+
+# Tag traces with an AI Component name
+with promptic_sdk.ai_component("customer-support-agent"):
+    response = client.chat.completions.create(
+        model="gpt-4.1-nano",
+        messages=[{"role": "user", "content": "Hello!"}],
+    )
+```
+
+### 3. Use the API client
+
+```python
+from promptic_sdk import PrompticClient
+
+with PrompticClient() as client:
+    # List traces
+    traces = client.list_traces(limit=10)
+
+    # Get workspace info
+    workspace = client.get_workspace()
+
+    # Manage experiments
+    experiment = client.create_experiment(
+        ai_component_id="comp_...",
+        target_model="gpt-4.1-nano",
+        task_type="classification",
+        initial_prompt="Classify the following text.",
+    )
+
+    # Deploy the best prompt
+    client.deploy(component_id="comp_...", experiment_id="exp_...")
+
+    # Fetch a deployed prompt at runtime
+    prompt = client.get_deployed_prompt("comp_...")
+```
+
+## Tracing
+
+`promptic_sdk.init()` sets up OpenTelemetry to export spans to the Promptic platform.
+
+| Parameter          | Description                                         | Default                      |
+| ------------------ | --------------------------------------------------- | ---------------------------- |
+| `api_key`          | Promptic API key (falls back to `PROMPTIC_API_KEY`) | —                            |
+| `endpoint`         | Platform URL (falls back to `PROMPTIC_ENDPOINT`)    | `https://promptic.eu`    |
+| `auto_instrument`  | Auto-detect and instrument LLM client libraries     | `True`                       |
+| `service_name`     | OpenTelemetry `service.name` resource attribute      | —                            |
+
+Auto-detected instrumentors: OpenAI, Anthropic, Google Generative AI, LangChain, Cohere.
+
+### Using other OpenTelemetry instrumentors
+
+Since Promptic uses standard OpenTelemetry under the hood, you can add any OTel-compatible instrumentor alongside the auto-detected ones. Just call `promptic_sdk.init()` first, then instrument manually:
+
+```python
+import promptic_sdk
+from opentelemetry.instrumentation.requests import RequestsInstrumentor
+from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
+
+promptic_sdk.init()
+
+# Add any OpenTelemetry instrumentor — spans will be exported to Promptic
+RequestsInstrumentor().instrument()
+SQLAlchemyInstrumentor().instrument(engine=engine)
+```
+
+This works with any package from the [opentelemetry-python-contrib](https://github.com/open-telemetry/opentelemetry-python-contrib) ecosystem (HTTP clients, databases, web frameworks, etc.). All spans are exported to the Promptic platform as long as `init()` has been called.
+
+### AI Components
+
+Use `ai_component()` to tag spans with a component name. The platform links traces to the matching AI Component in your workspace:
+
+```python
+with promptic_sdk.ai_component("my-component"):
+    # All LLM calls here are tagged
+    ...
+```
+
+## API client
+
+Both a sync (`PrompticClient`) and async (`AsyncPrompticClient`) client are available. They share the same method signatures and return types.
+
+```python
+from promptic_sdk import PrompticClient
+
+with PrompticClient() as client:
+    traces = client.list_traces(limit=10)
+```
+
+```python
+from promptic_sdk import AsyncPrompticClient
+
+async with AsyncPrompticClient() as client:
+    traces = await client.list_traces(limit=10)
+```
+
+Both clients provide typed methods for the full Promptic REST API:
+
+| Resource       | Methods                                                                 |
+| -------------- | ----------------------------------------------------------------------- |
+| Workspace      | `get_workspace`                                                         |
+| Traces         | `list_traces`, `get_trace`, `get_stats`                                 |
+| Components     | `list_components`, `get_component`, `create_component`, `delete_component` |
+| Experiments    | `list_experiments`, `get_experiment`, `create_experiment`, `update_experiment`, `delete_experiment`, `start_experiment` |
+| Observations   | `list_observations`, `create_observations`, `update_observation`, `delete_observation` |
+| Evaluators     | `list_evaluators`, `create_evaluators`, `update_evaluator`, `delete_evaluator` |
+| Iterations     | `list_iterations`, `get_iteration`, `get_best_iteration`                |
+| Deployments    | `get_deployment`, `deploy`, `undeploy`, `get_deployed_prompt`           |
+
+The client reads `PROMPTIC_API_KEY` and `PROMPTIC_ENDPOINT` from the environment, or accepts them as constructor arguments.
+
+## CLI
+
+The `promptic` CLI mirrors the API client and supports both human-readable tables and `--json` output.
+
+```
+promptic [command] [subcommand] [options]
+```
+
+### Commands
+
+| Command                          | Description                          |
+| -------------------------------- | ------------------------------------ |
+| `promptic login`                 | Authenticate via browser (device flow) |
+| `promptic logout`                | Clear saved credentials              |
+| `promptic configure`             | Save API key and endpoint (CI/CD)    |
+| `promptic workspace list`        | List accessible workspaces           |
+| `promptic workspace select <id>` | Select a workspace                   |
+| `promptic workspace show`        | Show workspace info                  |
+| `promptic traces list`           | List recent traces                   |
+| `promptic traces get <id>`       | Get a trace with spans               |
+| `promptic traces stats`          | Show aggregated tracing stats        |
+| `promptic components list`       | List AI components                   |
+| `promptic components create`     | Create a component                   |
+| `promptic components get <id>`   | Get component details                |
+| `promptic components delete <id>`| Delete a component                   |
+| `promptic experiments list`      | List experiments                     |
+| `promptic experiments create`    | Create an experiment (interactive)   |
+| `promptic experiments get <id>`  | Get experiment details               |
+| `promptic experiments start <id>`| Start an experiment                  |
+| `promptic observations list`     | List observations for an experiment  |
+| `promptic evaluators list`       | List evaluators for an experiment    |
+| `promptic iterations list`       | List iterations for an experiment    |
+| `promptic deployments show`      | Show deployment for a component      |
+| `promptic deployments deploy`    | Deploy an experiment                 |
+| `promptic deployments undeploy`  | Remove a deployment                  |
+
+All list commands support `--json` for machine-readable output.
+
+## Configuration
+
+The SDK and CLI resolve configuration in this order:
+
+1. Explicit arguments (`api_key=`, `endpoint=`)
+2. Environment variables (`PROMPTIC_API_KEY`, `PROMPTIC_ENDPOINT`)
+3. Config file (`~/.promptic/config.toml`, written by `promptic login` or `promptic configure`)
+
+| Variable            | Description                  | Default                   |
+| ------------------- | ---------------------------- | ------------------------- |
+| `PROMPTIC_API_KEY`  | API key (for tracing & CI/CD)| —                         |
+| `PROMPTIC_ENDPOINT` | Platform URL                 | `https://promptic.eu`     |
+
+## Development
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check .
+uv run ruff format .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

promptic_sdk-0.2.0/README.md

@@ -0,0 +1,231 @@
+# Promptic Python SDK
+
+Python SDK and CLI for the [Promptic](https://promptic.eu) platform — tracing, prompt optimization, and experiment management.
+
+## Installation
+
+```bash
+pip install promptic-sdk
+```
+
+### Optional LLM instrumentation
+
+Install extras to auto-instrument specific LLM providers:
+
+```bash
+pip install promptic-sdk[openai]       # OpenAI
+pip install promptic-sdk[anthropic]    # Anthropic
+pip install promptic-sdk[langchain]    # LangChain
+pip install promptic-sdk[all]          # All providers
+```
+
+## Quick start
+
+### 1. Authenticate
+
+Log in via browser (recommended for local development):
+
+```bash
+promptic login
+```
+
+This opens your browser for authentication, then auto-selects your workspace. Credentials are saved to `~/.promptic/config.toml`.
+
+For CI/CD or headless environments, use an API key instead:
+
+```bash
+promptic configure
+# or set the environment variable:
+export PROMPTIC_API_KEY="pk_..."
+```
+
+### 2. Send traces
+
+```python
+import promptic_sdk
+from openai import OpenAI
+
+# Initialize tracing (auto-instruments installed LLM libraries)
+promptic_sdk.init()
+
+client = OpenAI()
+
+# Tag traces with an AI Component name
+with promptic_sdk.ai_component("customer-support-agent"):
+    response = client.chat.completions.create(
+        model="gpt-4.1-nano",
+        messages=[{"role": "user", "content": "Hello!"}],
+    )
+```
+
+### 3. Use the API client
+
+```python
+from promptic_sdk import PrompticClient
+
+with PrompticClient() as client:
+    # List traces
+    traces = client.list_traces(limit=10)
+
+    # Get workspace info
+    workspace = client.get_workspace()
+
+    # Manage experiments
+    experiment = client.create_experiment(
+        ai_component_id="comp_...",
+        target_model="gpt-4.1-nano",
+        task_type="classification",
+        initial_prompt="Classify the following text.",
+    )
+
+    # Deploy the best prompt
+    client.deploy(component_id="comp_...", experiment_id="exp_...")
+
+    # Fetch a deployed prompt at runtime
+    prompt = client.get_deployed_prompt("comp_...")
+```
+
+## Tracing
+
+`promptic_sdk.init()` sets up OpenTelemetry to export spans to the Promptic platform.
+
+| Parameter          | Description                                         | Default                      |
+| ------------------ | --------------------------------------------------- | ---------------------------- |
+| `api_key`          | Promptic API key (falls back to `PROMPTIC_API_KEY`) | —                            |
+| `endpoint`         | Platform URL (falls back to `PROMPTIC_ENDPOINT`)    | `https://promptic.eu`    |
+| `auto_instrument`  | Auto-detect and instrument LLM client libraries     | `True`                       |
+| `service_name`     | OpenTelemetry `service.name` resource attribute      | —                            |
+
+Auto-detected instrumentors: OpenAI, Anthropic, Google Generative AI, LangChain, Cohere.
+
+### Using other OpenTelemetry instrumentors
+
+Since Promptic uses standard OpenTelemetry under the hood, you can add any OTel-compatible instrumentor alongside the auto-detected ones. Just call `promptic_sdk.init()` first, then instrument manually:
+
+```python
+import promptic_sdk
+from opentelemetry.instrumentation.requests import RequestsInstrumentor
+from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
+
+promptic_sdk.init()
+
+# Add any OpenTelemetry instrumentor — spans will be exported to Promptic
+RequestsInstrumentor().instrument()
+SQLAlchemyInstrumentor().instrument(engine=engine)
+```
+
+This works with any package from the [opentelemetry-python-contrib](https://github.com/open-telemetry/opentelemetry-python-contrib) ecosystem (HTTP clients, databases, web frameworks, etc.). All spans are exported to the Promptic platform as long as `init()` has been called.
+
+### AI Components
+
+Use `ai_component()` to tag spans with a component name. The platform links traces to the matching AI Component in your workspace:
+
+```python
+with promptic_sdk.ai_component("my-component"):
+    # All LLM calls here are tagged
+    ...
+```
+
+## API client
+
+Both a sync (`PrompticClient`) and async (`AsyncPrompticClient`) client are available. They share the same method signatures and return types.
+
+```python
+from promptic_sdk import PrompticClient
+
+with PrompticClient() as client:
+    traces = client.list_traces(limit=10)
+```
+
+```python
+from promptic_sdk import AsyncPrompticClient
+
+async with AsyncPrompticClient() as client:
+    traces = await client.list_traces(limit=10)
+```
+
+Both clients provide typed methods for the full Promptic REST API:
+
+| Resource       | Methods                                                                 |
+| -------------- | ----------------------------------------------------------------------- |
+| Workspace      | `get_workspace`                                                         |
+| Traces         | `list_traces`, `get_trace`, `get_stats`                                 |
+| Components     | `list_components`, `get_component`, `create_component`, `delete_component` |
+| Experiments    | `list_experiments`, `get_experiment`, `create_experiment`, `update_experiment`, `delete_experiment`, `start_experiment` |
+| Observations   | `list_observations`, `create_observations`, `update_observation`, `delete_observation` |
+| Evaluators     | `list_evaluators`, `create_evaluators`, `update_evaluator`, `delete_evaluator` |
+| Iterations     | `list_iterations`, `get_iteration`, `get_best_iteration`                |
+| Deployments    | `get_deployment`, `deploy`, `undeploy`, `get_deployed_prompt`           |
+
+The client reads `PROMPTIC_API_KEY` and `PROMPTIC_ENDPOINT` from the environment, or accepts them as constructor arguments.
+
+## CLI
+
+The `promptic` CLI mirrors the API client and supports both human-readable tables and `--json` output.
+
+```
+promptic [command] [subcommand] [options]
+```
+
+### Commands
+
+| Command                          | Description                          |
+| -------------------------------- | ------------------------------------ |
+| `promptic login`                 | Authenticate via browser (device flow) |
+| `promptic logout`                | Clear saved credentials              |
+| `promptic configure`             | Save API key and endpoint (CI/CD)    |
+| `promptic workspace list`        | List accessible workspaces           |
+| `promptic workspace select <id>` | Select a workspace                   |
+| `promptic workspace show`        | Show workspace info                  |
+| `promptic traces list`           | List recent traces                   |
+| `promptic traces get <id>`       | Get a trace with spans               |
+| `promptic traces stats`          | Show aggregated tracing stats        |
+| `promptic components list`       | List AI components                   |
+| `promptic components create`     | Create a component                   |
+| `promptic components get <id>`   | Get component details                |
+| `promptic components delete <id>`| Delete a component                   |
+| `promptic experiments list`      | List experiments                     |
+| `promptic experiments create`    | Create an experiment (interactive)   |
+| `promptic experiments get <id>`  | Get experiment details               |
+| `promptic experiments start <id>`| Start an experiment                  |
+| `promptic observations list`     | List observations for an experiment  |
+| `promptic evaluators list`       | List evaluators for an experiment    |
+| `promptic iterations list`       | List iterations for an experiment    |
+| `promptic deployments show`      | Show deployment for a component      |
+| `promptic deployments deploy`    | Deploy an experiment                 |
+| `promptic deployments undeploy`  | Remove a deployment                  |
+
+All list commands support `--json` for machine-readable output.
+
+## Configuration
+
+The SDK and CLI resolve configuration in this order:
+
+1. Explicit arguments (`api_key=`, `endpoint=`)
+2. Environment variables (`PROMPTIC_API_KEY`, `PROMPTIC_ENDPOINT`)
+3. Config file (`~/.promptic/config.toml`, written by `promptic login` or `promptic configure`)
+
+| Variable            | Description                  | Default                   |
+| ------------------- | ---------------------------- | ------------------------- |
+| `PROMPTIC_API_KEY`  | API key (for tracing & CI/CD)| —                         |
+| `PROMPTIC_ENDPOINT` | Platform URL                 | `https://promptic.eu`     |
+
+## Development
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check .
+uv run ruff format .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

promptic_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,137 @@
+[project]
+requires-python = ">=3.11"
+name = "promptic-sdk"
+version = "0.2.0"
+description = "Python SDK for the Promptic platform — tracing, API client, and CLI."
+readme = "README.md"
+authors = [
+    { name = "Promptic GmbH" },
+]
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "opentelemetry-sdk>=1.20.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.20.0",
+    "httpx>=0.27.0",
+    "typer>=0.15.0",
+    "rich>=13.0.0",
+    "tomli>=2.0.0;python_version<'3.11'",
+]
+
+[project.optional-dependencies]
+openai = ["opentelemetry-instrumentation-openai>=0.30b0"]
+anthropic = ["opentelemetry-instrumentation-anthropic>=0.30b0"]
+langchain = [
+    "opentelemetry-instrumentation-langchain>=0.30b0,!=0.53.0",
+]
+all = ["promptic-sdk[openai,anthropic,langchain]"]
+
+[project.scripts]
+promptic = "promptic_sdk.cli.main:main"
+
+[dependency-groups]
+dev = []
+test = [
+    "pytest>=7.1.0",
+    "pytest-asyncio>=0.26.0",
+    "pytest-cov>=4.0",
+]
+lint = [
+    "commitizen>=2.39.1",
+    "ruff>=0.6.0",
+    "ty>=0.0.1a1",
+]
+
+[tool.uv]
+default-groups = ["dev", "test", "lint"]
+required-version = ">=0.5.23"
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "pep621"
+version_files = ["src/promptic_sdk/__init__.py", "pyproject.toml:version"]
+update_changelog_on_bump = true
+changelog_file = "CHANGELOG.md"
+tag_format = "v$version"
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+fix = true
+
+[tool.ruff.lint]
+select = [
+    "E",     # pycodestyle errors
+    "W",     # pycodestyle warnings
+    "F",     # pyflake
+    "I",     # isort
+    "D",     # pydocstyle
+    "C901",  # complexity
+    "N",     # pep8 naming convention
+    "UP",    # pyupgrade
+    "NPY",   # NumPy-specific rules
+    "ASYNC", # flake8-async
+    "S105",  # flake8-bandit: hardcoded-password-string
+    "S106",  # flake8-bandit: hardcoded-password-func-arg
+    "S107",  # flake8-bandit: hardcoded-password-default
+    "C4",    # flake8-comprehensions
+    "ICN",   # flake8-import-conventions
+    "PIE",   # flake8-pie
+    "RET",   # flake8-return
+    "SIM",   # flake8-simplify
+]
+ignore = [
+    "D100",   # ignore missing docstring on module level
+    "D104",   # ignore missing docstring on package level
+    "D206",   # indent with spaces, may get conflicts with ruff formatter
+    "D417",   # On top of the Google convention, disable `D417`, which requires documentation for every function parameter.
+    "E501",   # line too long, handled by ruff formatter if possible
+    "RET504", # unnecessary-assign to maintain debuggability
+    "RET505", # unnecessary-branch no autofix
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"] # ignore unused imports in __init__ file
+"tests/*" = ["D101", "D102", "D103", "D107"] # ignore missing docstring in tests
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.mccabe]
+max-complexity = 18
+
+[tool.ty.environment]
+python-version = "3.11"
+
+[tool.ty.rules]
+unresolved-import = "ignore"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = """
+--cov-report html \
+--cov src/promptic_sdk -ra"""
+asyncio_default_fixture_loop_scope = "function"
+asyncio_mode = "auto"
+
+[tool.coverage.paths]
+source = ["src/promptic_sdk"]
+
+[tool.coverage.run]
+branch = true
+source = ["src/promptic_sdk"]
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+    # Have to re-enable the standard pragma
+    "pragma: no cover",
+    # Don't complain if tests don't hit defensive assertion code:
+    "raise NotImplementedError",
+    "raise AssertionError",
+    # Don't complain about abstract methods, they aren't run:
+    "@(abc\\.)?abstractmethod",
+]