llmtrack-sdk 0.1.0__tar.gz

llmtrack_sdk-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+.venv/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+packages/node/src/generated/
+packages/python/src/llmtrack_sdk/_generated/

llmtrack_sdk-0.1.0/LICENSE

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

llmtrack_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: llmtrack-sdk
+Version: 0.1.0
+Summary: Server-side SDK for tracking LLM token usage, costs, and observability data in LLMtrack
+Project-URL: Homepage, https://llm-track.com
+Project-URL: Documentation, https://llm-track.com/docs
+Project-URL: Repository, https://github.com/othmanemer9-cloud/llmtrack-sdks
+Project-URL: Issues, https://github.com/othmanemer9-cloud/llmtrack-sdks/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,anthropic,cost,cost-tracking,llm,observability,openai,tokens
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# llmtrack-sdk (Python)
+
+LLMtrack records server-side LLM token usage, cost, and request context so teams can understand AI usage in one dashboard.
+
+> [!WARNING]
+> **Server-side only.** Never put an LLMtrack key in browser, mobile, desktop-client, or other public code. Load it from a server-side environment variable only.
+
+The PyPI distribution is named `llmtrack-sdk`, while Python imports use `llmtrack_sdk`: distribution names can contain hyphens, but import identifiers cannot, and the distinct name also avoids the unrelated `llmtrack` distribution.
+
+## Install
+
+```sh
+pip install llmtrack-sdk
+```
+
+## Quickstart
+
+Create an ingestion key in LLMtrack, save it at `~/.config/llmtrack/api-key`, and run:
+
+```sh
+export LLMTRACK_API_KEY="$(cat ~/.config/llmtrack/api-key)"
+```
+
+```python
+import os
+from llmtrack_sdk import LLMtrack
+tracker = LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"])
+tracker.track(provider="openai", model="gpt-5.6-sol", prompt_tokens=241,
+              completion_tokens=86, reasoning_tokens=32, feature="support-chat")
+```
+
+## Provider examples
+
+Both examples call `track()` immediately after the provider completion and read counts from the official response objects.
+
+### OpenAI
+
+```python
+import os
+from openai import OpenAI
+from llmtrack_sdk import LLMtrack
+openai, tracker = OpenAI(), LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"])
+response = openai.chat.completions.create(model="gpt-5.6-sol", messages=[{"role": "user", "content": "Explain why the sky is blue in two sentences."}])
+usage = response.usage
+tracker.track(provider="openai", model=response.model, prompt_tokens=usage.prompt_tokens, completion_tokens=usage.completion_tokens,
+              reasoning_tokens=usage.completion_tokens_details.reasoning_tokens if usage.completion_tokens_details else 0, feature="science-explainer")
+```
+
+### Anthropic
+
+Anthropic includes thinking tokens in `output_tokens` rather than exposing a separate reasoning-token count, so do not duplicate them in `reasoning_tokens`.
+
+```python
+import os
+from anthropic import Anthropic
+from llmtrack_sdk import LLMtrack
+anthropic, tracker = Anthropic(), LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"])
+response = anthropic.messages.create(model="claude-opus-5", max_tokens=1024, messages=[{"role": "user", "content": "Summarize the benefits of typed APIs."}])
+tracker.track(provider="anthropic", model=response.model, prompt_tokens=response.usage.input_tokens,
+              completion_tokens=response.usage.output_tokens, feature="document-summary")
+```
+
+## Fire-and-forget and awaited usage
+
+| Method | Behavior |
+|---|---|
+| `track(**event)` | Synchronous fire-and-forget entry point: starts a daemon delivery thread, returns `None` immediately, **never blocks and never raises**. Errors go to `on_error`. |
+| `await track_sync(**event)` | Async awaited entry point: returns the API dictionary and **raises `LLMtrackError`** on failure. Despite its compatibility name, it must be awaited. |
+
+```python
+result = await tracker.track_sync(provider="openai", model="gpt-5.6-sol", prompt_tokens=241,
+                                  completion_tokens=86, reasoning_tokens=32, feature="support-chat")
+```
+
+Set `enabled=False` in tests and local development to make both methods no-ops:
+
+```python
+tracker = LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"], enabled=False)
+```
+
+## Constructor options
+
+| Name | Type | Default | Description |
+|---|---|---|---|
+| `api_key` | `str` | required | Server-side LLMtrack ingestion key. |
+| `base_url` | `str` | `https://llm-track.com` | API origin; primarily useful with a test server. |
+| `environment` | `str` | `production` | Environment applied when an event does not override it. |
+| `on_error` | `Callable[[LLMtrackError], None] \| None` | logs one `[llmtrack]` warning | Receives `track()` background errors; callback exceptions are contained. |
+| `on_warning` | `Callable[[LLMtrackWarning], None] \| None` | logs one `[llmtrack]` warning | Receives visibility and pricing warnings, once per distinct warning per process. |
+| `enabled` | `bool` | `True` | When `False`, both tracking methods do nothing. |
+| `timeout_ms` | `int` | `5000` | Timeout in milliseconds for each request attempt. |
+| `max_retries` | `int` | `3` | Maximum attempts, including the first request. |
+
+## Event fields
+
+The wrapper intentionally accepts the following snake-case subset of the `IngestRequest` contract. `total_tokens`, `cached_input_tokens`, and `cache_write_tokens` exist in the wire contract but are not arguments in the current Python public API; do not pass them to this SDK.
+
+| Name | Type | Requirement | Description |
+|---|---|---|---|
+| `provider` | `str` | required | Provider name, such as `openai` or `anthropic`. |
+| `model` | `str` | required | Provider model name, such as `gpt-5.6-sol`. |
+| `prompt_tokens` | `int` | required | Non-negative integer input-token count. |
+| `completion_tokens` | `int` | required | Non-negative integer output-token count. |
+| `total_tokens` | `int \| None` | not exposed | Optional explicit total in `IngestRequest`; the current wrapper relies on the server-computed total. |
+| `reasoning_tokens` | `int \| None` | optional | Non-negative reasoning-token count when separately reported. |
+| `cached_input_tokens` | `int \| None` | not exposed | Optional cached-input count in `IngestRequest`; not an argument in the current Python public API. |
+| `cache_write_tokens` | `int \| None` | not exposed | Optional cache-write count in `IngestRequest`; not an argument in the current Python public API. |
+| `latency_ms` | `int \| None` | optional | End-to-end latency in milliseconds. |
+| `status` | `str \| None` | optional | One of `success`, `error`, `timeout`, or `cancelled`. |
+| `feature` | `str \| None` | optional | Product feature, such as `support-chat`; defaults server-side to `unknown`. |
+| `customer_id` | `str \| None` | optional | Your stable customer identifier. |
+| `customer_name` | `str \| None` | optional | Your customer display name. |
+| `environment` | `str \| None` | optional | Overrides the constructor environment for this event. |
+| `metadata` | `dict[str, Any] \| None` | optional | JSON object containing request context; maximum serialized size is 8 KiB (8192 bytes). |
+| `idempotency_key` | `str \| None` | optional | SDK-only header option used to deduplicate the call, not an event-body field. |
+
+The client validates `prompt_tokens`, `completion_tokens`, and `reasoning_tokens` as non-negative integers and rejects metadata whose compact UTF-8 JSON serialization exceeds 8192 bytes. The server validates the remaining contract constraints.
+
+## Delivery, retries, and idempotency
+
+Each call automatically receives a UUID v4 idempotency key. That key stays stable across retries, preventing double-counting when a stored response is lost. Supply your own stable key to deduplicate separate calls:
+
+```python
+tracker.track(provider="openai", model="gpt-5.6-sol", prompt_tokens=241, completion_tokens=86,
+              reasoning_tokens=32, feature="support-chat", idempotency_key="9ea0c2ec-7b98-4bc3-9802-20ae6a468a35")
+```
+
+The SDK retries only network failures, timeouts, and HTTP 5xx responses. It never retries HTTP 4xx responses.
+
+## Errors
+
+| Code | Meaning | Fix |
+|---|---|---|
+| `INVALID_API_KEY` | The key is missing, unknown, or belongs to a missing workspace. | Check `LLMTRACK_API_KEY` and create or copy a valid ingestion key. |
+| `REVOKED_API_KEY` | The key was revoked. | Replace it with an active key. |
+| `INACTIVE_API_KEY` | The key was deactivated. | Reactivate it or replace it. |
+| `INVALID_PAYLOAD` | A field failed local or server validation. | Correct the named field; check integer token counts and metadata size. |
+| `QUOTA_EXCEEDED` | The event allowance or pay-per-event credits are exhausted. | Wait for reset, add credits, or upgrade. |
+| `PLAN_INACTIVE` | Billing status prevents ingestion. | Restore billing and reactivate the plan. |
+| `NETWORK_ERROR` | Network/timeout retries were exhausted, or an unclassified HTTP/server failure occurred. | Check connectivity, `base_url`, timeout, and service availability. |
+
+`track_sync()` raises these errors. `track()` sends them to `on_error` and never raises.
+
+## Warnings and free-plan key binding
+
+| Response | Meaning |
+|---|---|
+| `dashboard_visible: false` | The event was accepted and billed/consumed quota, but is hidden because its source does not match the free-key binding. |
+| `pricing_status: unknown_model` | No active pricing matched the provider/model, so cost is `0`; token usage is still recorded. |
+
+**The most common reason events do not appear:** free-plan keys bind to one **provider/model/feature triple**. Mismatched events are accepted and billed (or consume quota) but hidden. Match all three values to the binding shown in LLMtrack. `NOT_DASHBOARD_VISIBLE` includes the bound and submitted triples.
+
+## Troubleshooting
+
+### Events are not appearing
+
+Check warnings for `NOT_DASHBOARD_VISIBLE` and compare provider, model, and feature with the key binding. A short-lived process can exit before the daemon thread finishes; use `await track_sync()` in scripts and jobs that must confirm delivery.
+
+### Cost shows 0
+
+Check for `UNKNOWN_MODEL` or `pricing_status: unknown_model`. Use the exact `response.model` returned by the provider so active pricing can match it.
+
+### The key is rejected
+
+Inspect `LLMtrackError.code`: replace invalid/revoked keys, reactivate inactive keys, and confirm the environment variable is available to the server process. Use `await track_sync()` to inspect the complete exception.
+
+## Contributing
+
+Async tests use `pytest-asyncio` (included in the `test` and `dev` extras):
+
+```sh
+pip install -e 'packages/python[test]'
+pytest packages/python/tests
+```
+
+## More information
+
+- [LLMtrack documentation](https://llm-track.com/docs)
+- [MIT License](./LICENSE)

llmtrack_sdk-0.1.0/README.md

@@ -0,0 +1,179 @@
+# llmtrack-sdk (Python)
+
+LLMtrack records server-side LLM token usage, cost, and request context so teams can understand AI usage in one dashboard.
+
+> [!WARNING]
+> **Server-side only.** Never put an LLMtrack key in browser, mobile, desktop-client, or other public code. Load it from a server-side environment variable only.
+
+The PyPI distribution is named `llmtrack-sdk`, while Python imports use `llmtrack_sdk`: distribution names can contain hyphens, but import identifiers cannot, and the distinct name also avoids the unrelated `llmtrack` distribution.
+
+## Install
+
+```sh
+pip install llmtrack-sdk
+```
+
+## Quickstart
+
+Create an ingestion key in LLMtrack, save it at `~/.config/llmtrack/api-key`, and run:
+
+```sh
+export LLMTRACK_API_KEY="$(cat ~/.config/llmtrack/api-key)"
+```
+
+```python
+import os
+from llmtrack_sdk import LLMtrack
+tracker = LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"])
+tracker.track(provider="openai", model="gpt-5.6-sol", prompt_tokens=241,
+              completion_tokens=86, reasoning_tokens=32, feature="support-chat")
+```
+
+## Provider examples
+
+Both examples call `track()` immediately after the provider completion and read counts from the official response objects.
+
+### OpenAI
+
+```python
+import os
+from openai import OpenAI
+from llmtrack_sdk import LLMtrack
+openai, tracker = OpenAI(), LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"])
+response = openai.chat.completions.create(model="gpt-5.6-sol", messages=[{"role": "user", "content": "Explain why the sky is blue in two sentences."}])
+usage = response.usage
+tracker.track(provider="openai", model=response.model, prompt_tokens=usage.prompt_tokens, completion_tokens=usage.completion_tokens,
+              reasoning_tokens=usage.completion_tokens_details.reasoning_tokens if usage.completion_tokens_details else 0, feature="science-explainer")
+```
+
+### Anthropic
+
+Anthropic includes thinking tokens in `output_tokens` rather than exposing a separate reasoning-token count, so do not duplicate them in `reasoning_tokens`.
+
+```python
+import os
+from anthropic import Anthropic
+from llmtrack_sdk import LLMtrack
+anthropic, tracker = Anthropic(), LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"])
+response = anthropic.messages.create(model="claude-opus-5", max_tokens=1024, messages=[{"role": "user", "content": "Summarize the benefits of typed APIs."}])
+tracker.track(provider="anthropic", model=response.model, prompt_tokens=response.usage.input_tokens,
+              completion_tokens=response.usage.output_tokens, feature="document-summary")
+```
+
+## Fire-and-forget and awaited usage
+
+| Method | Behavior |
+|---|---|
+| `track(**event)` | Synchronous fire-and-forget entry point: starts a daemon delivery thread, returns `None` immediately, **never blocks and never raises**. Errors go to `on_error`. |
+| `await track_sync(**event)` | Async awaited entry point: returns the API dictionary and **raises `LLMtrackError`** on failure. Despite its compatibility name, it must be awaited. |
+
+```python
+result = await tracker.track_sync(provider="openai", model="gpt-5.6-sol", prompt_tokens=241,
+                                  completion_tokens=86, reasoning_tokens=32, feature="support-chat")
+```
+
+Set `enabled=False` in tests and local development to make both methods no-ops:
+
+```python
+tracker = LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"], enabled=False)
+```
+
+## Constructor options
+
+| Name | Type | Default | Description |
+|---|---|---|---|
+| `api_key` | `str` | required | Server-side LLMtrack ingestion key. |
+| `base_url` | `str` | `https://llm-track.com` | API origin; primarily useful with a test server. |
+| `environment` | `str` | `production` | Environment applied when an event does not override it. |
+| `on_error` | `Callable[[LLMtrackError], None] \| None` | logs one `[llmtrack]` warning | Receives `track()` background errors; callback exceptions are contained. |
+| `on_warning` | `Callable[[LLMtrackWarning], None] \| None` | logs one `[llmtrack]` warning | Receives visibility and pricing warnings, once per distinct warning per process. |
+| `enabled` | `bool` | `True` | When `False`, both tracking methods do nothing. |
+| `timeout_ms` | `int` | `5000` | Timeout in milliseconds for each request attempt. |
+| `max_retries` | `int` | `3` | Maximum attempts, including the first request. |
+
+## Event fields
+
+The wrapper intentionally accepts the following snake-case subset of the `IngestRequest` contract. `total_tokens`, `cached_input_tokens`, and `cache_write_tokens` exist in the wire contract but are not arguments in the current Python public API; do not pass them to this SDK.
+
+| Name | Type | Requirement | Description |
+|---|---|---|---|
+| `provider` | `str` | required | Provider name, such as `openai` or `anthropic`. |
+| `model` | `str` | required | Provider model name, such as `gpt-5.6-sol`. |
+| `prompt_tokens` | `int` | required | Non-negative integer input-token count. |
+| `completion_tokens` | `int` | required | Non-negative integer output-token count. |
+| `total_tokens` | `int \| None` | not exposed | Optional explicit total in `IngestRequest`; the current wrapper relies on the server-computed total. |
+| `reasoning_tokens` | `int \| None` | optional | Non-negative reasoning-token count when separately reported. |
+| `cached_input_tokens` | `int \| None` | not exposed | Optional cached-input count in `IngestRequest`; not an argument in the current Python public API. |
+| `cache_write_tokens` | `int \| None` | not exposed | Optional cache-write count in `IngestRequest`; not an argument in the current Python public API. |
+| `latency_ms` | `int \| None` | optional | End-to-end latency in milliseconds. |
+| `status` | `str \| None` | optional | One of `success`, `error`, `timeout`, or `cancelled`. |
+| `feature` | `str \| None` | optional | Product feature, such as `support-chat`; defaults server-side to `unknown`. |
+| `customer_id` | `str \| None` | optional | Your stable customer identifier. |
+| `customer_name` | `str \| None` | optional | Your customer display name. |
+| `environment` | `str \| None` | optional | Overrides the constructor environment for this event. |
+| `metadata` | `dict[str, Any] \| None` | optional | JSON object containing request context; maximum serialized size is 8 KiB (8192 bytes). |
+| `idempotency_key` | `str \| None` | optional | SDK-only header option used to deduplicate the call, not an event-body field. |
+
+The client validates `prompt_tokens`, `completion_tokens`, and `reasoning_tokens` as non-negative integers and rejects metadata whose compact UTF-8 JSON serialization exceeds 8192 bytes. The server validates the remaining contract constraints.
+
+## Delivery, retries, and idempotency
+
+Each call automatically receives a UUID v4 idempotency key. That key stays stable across retries, preventing double-counting when a stored response is lost. Supply your own stable key to deduplicate separate calls:
+
+```python
+tracker.track(provider="openai", model="gpt-5.6-sol", prompt_tokens=241, completion_tokens=86,
+              reasoning_tokens=32, feature="support-chat", idempotency_key="9ea0c2ec-7b98-4bc3-9802-20ae6a468a35")
+```
+
+The SDK retries only network failures, timeouts, and HTTP 5xx responses. It never retries HTTP 4xx responses.
+
+## Errors
+
+| Code | Meaning | Fix |
+|---|---|---|
+| `INVALID_API_KEY` | The key is missing, unknown, or belongs to a missing workspace. | Check `LLMTRACK_API_KEY` and create or copy a valid ingestion key. |
+| `REVOKED_API_KEY` | The key was revoked. | Replace it with an active key. |
+| `INACTIVE_API_KEY` | The key was deactivated. | Reactivate it or replace it. |
+| `INVALID_PAYLOAD` | A field failed local or server validation. | Correct the named field; check integer token counts and metadata size. |
+| `QUOTA_EXCEEDED` | The event allowance or pay-per-event credits are exhausted. | Wait for reset, add credits, or upgrade. |
+| `PLAN_INACTIVE` | Billing status prevents ingestion. | Restore billing and reactivate the plan. |
+| `NETWORK_ERROR` | Network/timeout retries were exhausted, or an unclassified HTTP/server failure occurred. | Check connectivity, `base_url`, timeout, and service availability. |
+
+`track_sync()` raises these errors. `track()` sends them to `on_error` and never raises.
+
+## Warnings and free-plan key binding
+
+| Response | Meaning |
+|---|---|
+| `dashboard_visible: false` | The event was accepted and billed/consumed quota, but is hidden because its source does not match the free-key binding. |
+| `pricing_status: unknown_model` | No active pricing matched the provider/model, so cost is `0`; token usage is still recorded. |
+
+**The most common reason events do not appear:** free-plan keys bind to one **provider/model/feature triple**. Mismatched events are accepted and billed (or consume quota) but hidden. Match all three values to the binding shown in LLMtrack. `NOT_DASHBOARD_VISIBLE` includes the bound and submitted triples.
+
+## Troubleshooting
+
+### Events are not appearing
+
+Check warnings for `NOT_DASHBOARD_VISIBLE` and compare provider, model, and feature with the key binding. A short-lived process can exit before the daemon thread finishes; use `await track_sync()` in scripts and jobs that must confirm delivery.
+
+### Cost shows 0
+
+Check for `UNKNOWN_MODEL` or `pricing_status: unknown_model`. Use the exact `response.model` returned by the provider so active pricing can match it.
+
+### The key is rejected
+
+Inspect `LLMtrackError.code`: replace invalid/revoked keys, reactivate inactive keys, and confirm the environment variable is available to the server process. Use `await track_sync()` to inspect the complete exception.
+
+## Contributing
+
+Async tests use `pytest-asyncio` (included in the `test` and `dev` extras):
+
+```sh
+pip install -e 'packages/python[test]'
+pytest packages/python/tests
+```
+
+## More information
+
+- [LLMtrack documentation](https://llm-track.com/docs)
+- [MIT License](./LICENSE)

llmtrack_sdk-0.1.0/integration.py

@@ -0,0 +1,67 @@
+"""Opt-in live checks. Requires a dedicated LLMTRACK_API_KEY."""
+import asyncio
+import os
+import uuid
+
+from llmtrack_sdk import LLMtrack, LLMtrackError
+
+API_KEY = os.environ.get("LLMTRACK_API_KEY")
+if not API_KEY:
+    raise SystemExit("FAIL setup: LLMTRACK_API_KEY is required")
+EVENT = dict(provider="openai", model="gpt-4o-mini", prompt_tokens=2, completion_tokens=1,
+             reasoning_tokens=1, feature="sdk-integration")
+failures = 0
+
+async def check(name, operation):
+    global failures
+    try:
+        await operation()
+        print(f"PASS {name}")
+    except Exception as exc:
+        failures += 1
+        print(f"FAIL {name}: {exc}")
+
+async def callback_error(client):
+    loop = asyncio.get_running_loop()
+    done = loop.create_future()
+    def receive(error):
+        loop.call_soon_threadsafe(lambda: None if done.done() else done.set_result(error))
+    client.on_error = receive
+    client.track(**EVENT)
+    return await asyncio.wait_for(done, 7)
+
+async def main():
+    client = LLMtrack(api_key=API_KEY)
+    await check("happy path with reasoning tokens", lambda: client.track_sync(**EVENT))
+    async def invalid():
+        error = await callback_error(LLMtrack(api_key="invalid-integration-key", max_retries=1))
+        assert error.code == "INVALID_API_KEY", error.code
+    await check("invalid key is reported and track never raises", invalid)
+    async def visibility():
+        warnings=[]; c=LLMtrack(api_key=API_KEY, environment=f"sdk-mismatch-{uuid.uuid4()}", on_warning=warnings.append)
+        await c.track_sync(**EVENT)
+        assert any(w.code == "NOT_DASHBOARD_VISIBLE" for w in warnings), "use a free-plan test key bound to another environment"
+    await check("free-plan visibility warning", visibility)
+    async def pricing():
+        warnings=[]; c=LLMtrack(api_key=API_KEY, on_warning=warnings.append)
+        await c.track_sync(**{**EVENT,"model":f"unknown-integration-{uuid.uuid4()}"})
+        assert any(w.code == "UNKNOWN_MODEL" for w in warnings), "missing UNKNOWN_MODEL warning"
+    await check("unknown-model pricing warning", pricing)
+    async def invalid_payload(**changes):
+        try: await client.track_sync(**{**EVENT,**changes})
+        except LLMtrackError as exc:
+            assert exc.code == "INVALID_PAYLOAD"; return
+        raise AssertionError("expected INVALID_PAYLOAD")
+    await check("oversized metadata is rejected client-side", lambda: invalid_payload(metadata={"value":"x"*8193}))
+    await check("negative tokens are rejected client-side", lambda: invalid_payload(prompt_tokens=-1))
+    async def duplicate():
+        key=str(uuid.uuid4()); await client.track_sync(**EVENT,idempotency_key=key)
+        second=await client.track_sync(**EVENT,idempotency_key=key); assert second["duplicate"] is True
+    await check("same idempotency key is a successful duplicate", duplicate)
+    async def network():
+        error=await callback_error(LLMtrack(api_key=API_KEY,base_url="http://127.0.0.1:1",timeout_ms=250,max_retries=1))
+        assert error.code == "NETWORK_ERROR", error.code
+    await check("unreachable network failure is reported without raising", network)
+
+asyncio.run(main())
+raise SystemExit(1 if failures else 0)

llmtrack_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "llmtrack-sdk"
+version = "0.1.0"
+description = "Server-side SDK for tracking LLM token usage, costs, and observability data in LLMtrack"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+dependencies = ["httpx>=0.27,<1"]
+keywords = ["llm", "openai", "anthropic", "cost", "cost-tracking", "observability", "tokens", "ai"]
+
+[project.urls]
+Homepage = "https://llm-track.com"
+Documentation = "https://llm-track.com/docs"
+Repository = "https://github.com/othmanemer9-cloud/llmtrack-sdks"
+Issues = "https://github.com/othmanemer9-cloud/llmtrack-sdks/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.24"]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "build>=1"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/llmtrack_sdk"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

llmtrack_sdk-0.1.0/src/llmtrack_sdk/__init__.py

@@ -0,0 +1,4 @@
+"""Public LLMtrack SDK API."""
+from .client import LLMtrack, LLMtrackError, LLMtrackWarning
+
+__all__ = ["LLMtrack", "LLMtrackError", "LLMtrackWarning"]

llmtrack_sdk-0.1.0/src/llmtrack_sdk/_generated/.github/workflows/python.yml

@@ -0,0 +1,34 @@
+# NOTE: This file is auto generated by OpenAPI Generator.
+# URL: https://openapi-generator.tech
+#
+# ref: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: llmtrack_generated Python package
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -r test-requirements.txt
+      - name: Test with pytest
+        run: |
+          pytest --cov=llmtrack_generated

llmtrack_sdk-0.1.0/src/llmtrack_sdk/_generated/.gitignore

@@ -0,0 +1,66 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+venv/
+.venv/
+.python-version
+.pytest_cache
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Ipython Notebook
+.ipynb_checkpoints

llmtrack_sdk-0.1.0/src/llmtrack_sdk/_generated/.gitlab-ci.yml

@@ -0,0 +1,31 @@
+# NOTE: This file is auto generated by OpenAPI Generator.
+# URL: https://openapi-generator.tech
+#
+# ref: https://docs.gitlab.com/ee/ci/README.html
+# ref: https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Python.gitlab-ci.yml
+
+stages:
+  - test
+
+.pytest:
+  stage: test
+  script:
+   - pip install -r requirements.txt
+   - pip install -r test-requirements.txt
+   - pytest --cov=llmtrack_generated
+
+pytest-3.10:
+  extends: .pytest
+  image: python:3.10-alpine
+pytest-3.11:
+  extends: .pytest
+  image: python:3.11-alpine
+pytest-3.12:
+  extends: .pytest
+  image: python:3.12-alpine
+pytest-3.13:
+  extends: .pytest
+  image: python:3.13-alpine
+pytest-3.14:
+  extends: .pytest
+  image: python:3.14-alpine