Skip to content
Merged
7 changes: 7 additions & 0 deletions .github/assets/integration-coverage.json
Original file line number Diff line number Diff line change
Expand Up @@ -453,6 +453,13 @@
"name": "IBM watsonx",
"category": "model-providers",
"languages": {
"Python": [
{
"manifest": "python/frameworks/watsonx/pyproject.toml",
"package": "traceAI-watsonx",
"source": "python/frameworks/watsonx/"
}
],
"Java": [
{
"manifest": "java/traceai-java-watsonx/pom.xml",
Expand Down
4 changes: 3 additions & 1 deletion .github/release/config.json
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,9 @@
"traceAI-transformers",
"traceAI-openrouter",
"traceAI-sagemaker",
"traceAI-marqo"
"traceAI-marqo",
"traceAI-watsonx",
"traceAI-writer"
],
"_hold_artifacts_comment": "Reactor modules that the Java release builds and tests but does not deploy, with the reason. A held module's release profile sets skipPublishing, and the release plan leaves it out of the Central check, so the rest of the reactor still releases. To publish one, remove its entry here and its skipPublishing setting.",
"hold_artifacts": {}
Expand Down
65 changes: 65 additions & 0 deletions .github/workflows/watsonx-python-tests.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
name: IBM watsonx.ai Python SDK contracts

on:
pull_request:
branches: [main, dev]
paths:
- 'python/frameworks/watsonx/**'
- 'python/fi_instrumentation/**'
- '.github/workflows/watsonx-python-tests.yml'
push:
branches: [dev]
paths:
- 'python/frameworks/watsonx/**'
- 'python/fi_instrumentation/**'
- '.github/workflows/watsonx-python-tests.yml'

permissions:
contents: read

jobs:
sdk-contract:
runs-on: ubuntu-24.04
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
include:
- python: '3.10'
watsonx: '1.3.0'
artifact: wheel
- python: '3.13'
watsonx: '1.9.1'
artifact: sdist
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
persist-credentials: false
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
with:
python-version: ${{ matrix.python }}
- name: Build and install packages
shell: bash
env:
ARTIFACT: ${{ matrix.artifact }}
WATSONX_VERSION: ${{ matrix.watsonx }}
run: |
python -m venv .watsonx-test-venv
.watsonx-test-venv/bin/pip install build
.watsonx-test-venv/bin/python -m build "--$ARTIFACT" python/frameworks/watsonx
if [ "$ARTIFACT" = wheel ]; then
packages=(python/frameworks/watsonx/dist/*.whl)
else
packages=(python/frameworks/watsonx/dist/*.tar.gz)
fi
.watsonx-test-venv/bin/pip install "${packages[@]}" \
"ibm-watsonx-ai==$WATSONX_VERSION" pytest pytest-asyncio
- name: Run SDK tests without external traffic
shell: bash
run: |
sudo unshare --net bash -c '
set -e
ip link set lo up
"$1" -I -m pytest python/frameworks/watsonx/tests \
-q -p no:cacheprovider
' _ "$PWD/.watsonx-test-venv/bin/python"
60 changes: 60 additions & 0 deletions .github/workflows/writer-python-tests.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
name: Writer Python SDK tests

on:
pull_request:
branches: [main, dev]
paths:
- 'python/frameworks/writer/**'
- 'python/fi_instrumentation/**'
- '.github/workflows/writer-python-tests.yml'
push:
branches: [dev]
paths:
- 'python/frameworks/writer/**'
- 'python/fi_instrumentation/**'
- '.github/workflows/writer-python-tests.yml'

permissions:
contents: read

jobs:
sdk-range:
runs-on: ubuntu-24.04
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
include:
- python: '3.10'
writer: '2.0.0'
artifact: wheel
- python: '3.13'
writer: 'latest'
artifact: sdist
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
persist-credentials: false
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
with:
python-version: ${{ matrix.python }}
- name: Build and install the package
shell: bash
env:
ARTIFACT: ${{ matrix.artifact }}
WRITER_VERSION: ${{ matrix.writer }}
run: |
python -m venv .writer-test-venv
.writer-test-venv/bin/pip install build
.writer-test-venv/bin/python -m build "--$ARTIFACT" python/frameworks/writer
if [ "$ARTIFACT" = wheel ]; then ext='*.whl'; else ext='*.tar.gz'; fi
if [ "$WRITER_VERSION" = latest ]; then sdk='writer-sdk'; else sdk="writer-sdk==$WRITER_VERSION"; fi
.writer-test-venv/bin/pip install python/frameworks/writer/dist/$ext "$sdk" pytest pytest-asyncio
- name: Run offline tests without external traffic
shell: bash
run: |
sudo unshare --net bash -c '
set -e
ip link set lo up
"$1" -I -m pytest python/frameworks/writer/tests -q -p no:cacheprovider
' _ "$PWD/.writer-test-venv/bin/python"
2 changes: 2 additions & 0 deletions .release-please-manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,8 @@
"python/frameworks/openrouter": "0.1.0",
"python/frameworks/sagemaker": "0.1.0",
"python/frameworks/marqo": "0.1.0",
"python/frameworks/watsonx": "0.1.0",
"python/frameworks/writer": "0.1.0",
"go/langchaingo": "0.1.0",
"ruby": "0.1.0",
"ruby/roast": "0.1.0",
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -340,7 +340,7 @@ Hosted and local model inference, embeddings, and reranking.
| <img src=".github/assets/integrations/google-tile.svg" width="24" height="24" alt=""> Google GenAI (Gemini) | [SDK](python/frameworks/google-genai/ "traceAI-google-genai") · [Live](python/frameworks/google-genai-live/ "traceAI-google-genai-live") | [Legacy SDK only](typescript/packages/traceai_google_genai/ "@google/generative-ai compatibility; not @google/genai") | [SDK](java/traceai-java-google-genai/ "traceai-java-google-genai") | [SDK](go/genai/ "github.com/future-agi/traceAI/go/genai") | — |
| <img src=".github/assets/integrations/groq-tile.svg" width="24" height="24" alt=""> Groq | [SDK](python/frameworks/groq/ "traceAI-groq") | [SDK](typescript/packages/traceai_groq/ "@traceai/groq") | — | — | — |
| <img src=".github/assets/integrations/package-tile.svg" width="24" height="24" alt=""> Hugging Face | [SDK](python/frameworks/huggingface/ "traceAI-huggingface") | [SDK](typescript/packages/traceai_huggingface/ "@traceai/huggingface") | — | — | — |
| <img src=".github/assets/integrations/package-tile.svg" width="24" height="24" alt=""> IBM watsonx | — | — | [SDK](java/traceai-java-watsonx/ "traceai-java-watsonx") | — | — |
| <img src=".github/assets/integrations/package-tile.svg" width="24" height="24" alt=""> IBM watsonx | [SDK](python/frameworks/watsonx/ "traceAI-watsonx") | — | [SDK](java/traceai-java-watsonx/ "traceai-java-watsonx") | — | — |
| <img src=".github/assets/integrations/package-tile.svg" width="24" height="24" alt=""> MiniMax | [SDK](python/frameworks/minimax/ "traceAI-minimax") | — | — | — | — |
| <img src=".github/assets/integrations/mistral-tile.svg" width="24" height="24" alt=""> Mistral AI | [SDK](python/frameworks/mistralai/ "traceAI-mistralai") | [SDK](typescript/packages/traceai_mistral/ "@traceai/mistral") | — | — | — |
| <img src=".github/assets/integrations/ollama-tile.svg" width="24" height="24" alt=""> Ollama | [SDK](python/frameworks/ollama/ "traceAI-ollama") | [SDK](typescript/packages/traceai_ollama/ "@traceai/ollama") | [SDK](java/traceai-java-ollama/ "traceai-java-ollama") | — | — |
Expand Down
2 changes: 2 additions & 0 deletions docs/python/auto-instrumentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,9 @@ Each integration reports one of these statuses:
| `transformers` | `transformers` | `traceAI-transformers` | Automatic |
| `litellm` | `litellm` | `traceAI-litellm` | Automatic |
| `openrouter` | `openrouter` | `traceAI-openrouter` | Automatic |
| `writer` | `writerai` | `traceAI-writer` | Automatic |
| `portkey` | `portkey-ai` | `traceAI-portkey` | Automatic |
| `watsonx` | `ibm_watsonx_ai` | `traceAI-watsonx` | Automatic |
| `replicate` | `replicate` | `traceAI-replicate` | Automatic |
| `voyage` | `voyageai` | `traceAI-voyage` | Automatic |
| `discoveryengine` | `google-cloud-discoveryengine` | `traceAI-discoveryengine` | Automatic |
Expand Down
2 changes: 2 additions & 0 deletions python/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -212,6 +212,7 @@ Each package below links to its own installation instructions, supported SDK ver
| `traceAI-redis` | [redis-vector](frameworks/redis-vector/) |
| `traceAI-replicate` | [replicate](frameworks/replicate/) |
| `traceAI-sagemaker` | [sagemaker](frameworks/sagemaker/) |
| `traceAI-watsonx` | [watsonx](frameworks/watsonx/) |
| `traceAI-semantic-kernel` | [semantic-kernel](frameworks/semantic-kernel/) |
| `traceAI-smolagents` | [smolagents](frameworks/smolagents/) |
| `traceai-strands` | [strands](frameworks/strands/) |
Expand All @@ -222,6 +223,7 @@ Each package below links to its own installation instructions, supported SDK ver
| `traceAI-vllm` | [vllm](frameworks/vllm/) |
| `traceAI-voyage` | [voyage](frameworks/voyage/) |
| `traceAI-weaviate` | [weaviate](frameworks/weaviate/) |
| `traceAI-writer` | [writer](frameworks/writer/) |
| `traceAI-xai` | [xai](frameworks/xai/) |

</details>
Expand Down
2 changes: 2 additions & 0 deletions python/fi_instrumentation/auto/_registry.py
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,9 @@ def _covered_by_openai(provider: str) -> str:
Integration("transformers", ("transformers",), "traceAI-transformers", "traceai_transformers", "TransformersInstrumentor"),
Integration("litellm", ("litellm",), "traceAI-litellm", "traceai_litellm", "LiteLLMInstrumentor", category="gateway"),
Integration("openrouter", ("openrouter",), "traceAI-openrouter", "traceai_openrouter", "OpenRouterInstrumentor", category="gateway"),
Integration("writer", ("writerai",), "traceAI-writer", "traceai_writer", "WriterInstrumentor"),
Integration("portkey", ("portkey_ai",), "traceAI-portkey", "traceai_portkey", "PortkeyInstrumentor", category="gateway"),
Integration("watsonx", ("ibm_watsonx_ai",), "traceAI-watsonx", "traceai_watsonx", "WatsonxInstrumentor"),
Integration("replicate", ("replicate",), "traceAI-replicate", "traceai_replicate", "ReplicateInstrumentor"),
Integration("voyage", ("voyageai",), "traceAI-voyage", "traceai_voyage", "VoyageInstrumentor"),
Integration("discoveryengine", ("google.cloud.discoveryengine",), "traceAI-discoveryengine", "traceai_discoveryengine", "DiscoveryEngineInstrumentor", category="retrieval"),
Expand Down
5 changes: 5 additions & 0 deletions python/frameworks/watsonx/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Changelog

## 0.1.0

- Instrument the IBM watsonx.ai Python SDK (`ibm-watsonx-ai`): `ModelInference` text generation, chat and their streaming and asynchronous variants, and `Embeddings`.
46 changes: 46 additions & 0 deletions python/frameworks/watsonx/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# IBM watsonx.ai Python SDK tracing

Trace calls made through the [`ibm-watsonx-ai` Python SDK](https://pypi.org/project/ibm-watsonx-ai/) with the maintained `traceAI-watsonx` package. It supports `ibm-watsonx-ai` 1.3.0 up to, but not including, 2.0.

```bash
pip install traceAI-watsonx
```

Set `FI_API_KEY`, `FI_SECRET_KEY`, and your watsonx.ai credentials (`WATSONX_APIKEY`, `WATSONX_URL`, `WATSONX_PROJECT_ID`) in your environment. Then:

```python
import os

from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from ibm_watsonx_ai import Credentials
from ibm_watsonx_ai.foundation_models import ModelInference
from traceai_watsonx import WatsonxInstrumentor

provider = register(project_type=ProjectType.OBSERVE, project_name="watsonx-demo")
WatsonxInstrumentor().instrument(tracer_provider=provider)
model = ModelInference(
model_id="ibm/granite-3-8b-instruct",
credentials=Credentials(api_key=os.environ["WATSONX_APIKEY"], url=os.environ["WATSONX_URL"]),
project_id=os.environ["WATSONX_PROJECT_ID"],
)
answer = model.chat(messages=[{"role": "user", "content": "What is the capital of Japan?"}])
print(answer["choices"][0]["message"]["content"])
provider.force_flush()
```

With the `fi-instrument` launcher or `FI_INSTRUMENTATIONS`, no code is needed: importing `ibm_watsonx_ai` turns this integration on.

Find the `watsonx.chat` span in your Future AGI project. Covered calls:

| Span | SDK methods |
| --- | --- |
| `watsonx.text_completion` | `ModelInference.generate`, `generate_text`, `generate_text_stream`, `agenerate`, `agenerate_stream` |
| `watsonx.chat` | `ModelInference.chat`, `chat_stream`, `achat`, `achat_stream` |
| `watsonx.embeddings` | `Embeddings.generate`, `embed_documents`, `embed_query`, `agenerate`, `aembed_documents`, `aembed_query` |

Each span records `gen_ai.provider.name` (`ibm.watsonx.ai`), the request model or deployment id, request parameters (those given to the call, over those the `ModelInference` or `Embeddings` object was created with), input and output messages with `input.value` / `output.value`, token usage (from `input_token_count` / `generated_token_count`, the embeddings `input_token_count`, or the chat `usage`), and finish reasons. One SDK call is one span: methods that call each other inside the SDK (`generate_text` calls `generate`, `embed_query` calls `generate`) are not traced twice, and the outer span takes its usage, finish reason and response model from the inner response. Only a plain-text `generate_text_stream` has no token counts, because it yields text only; use `raw_response=True` to get them. Prompt-template values (`prompt_variables`) are recorded as `gen_ai.prompt.template.variables`, not as a request parameter, and are removed by the input-hiding settings. For `generate(prompt=[...])` each answer is recorded under its own prompt's message index and usage is summed.

Streams finish when fully consumed or closed; a stream abandoned without closing it is marked `watsonx.stream.incomplete` and carries no partial output. Errors set the span status to ERROR and `error.type`, and the exception is re-raised unchanged. Exception messages, stacks, credentials and embedding vectors are never exported. Non-text parts of chat messages (images) are not captured.

Pass `TraceConfig(hide_inputs=True, hide_outputs=True)` to `instrument(config=...)` to remove prompt and response content. Do not instrument HTTPX for the same requests, or you will get duplicate spans. The package does not send requests to IBM on its own.
26 changes: 26 additions & 0 deletions python/frameworks/watsonx/pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
[tool.poetry]
name = "traceAI-watsonx"
version = "0.1.0"
description = "OpenTelemetry instrumentation for IBM watsonx.ai (ibm-watsonx-ai) Python SDK"
authors = ["Future AGI <no-reply@futureagi.com>"]
readme = "README.md"
license = "Apache-2.0"
packages = [{ include = "traceai_watsonx" }]
classifiers = ["Intended Audience :: Developers", "License :: OSI Approved :: Apache Software License", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Framework :: OpenTelemetry :: Instrumentations"]

[tool.poetry.dependencies]
python = ">=3.10,<3.14"
fi-instrumentation-otel = ">=1.1.0"
ibm-watsonx-ai = ">=1.3.0,<2"
wrapt = ">=1.15.0"

[tool.poetry.group.dev.dependencies]
pytest = ">=7"
pytest-asyncio = ">=0.23"

[tool.poetry.urls]
Repository = "https://github.com/future-agi/traceAI/tree/dev/python/frameworks/watsonx"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
Loading
Loading