prime-traces 0.0.1__tar.gz

prime_traces-0.0.1/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.env
+venv/
+.venv/
+ENV/
+test_env/
+.DS_Store
+.claude/worktrees/

prime_traces-0.0.1/LICENSE

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

prime_traces-0.0.1/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: prime-traces
+Version: 0.0.1
+Summary: Prime Intellect Traces SDK - Upload, query and export traces
+Project-URL: Homepage, https://github.com/PrimeIntellect-ai/prime
+Project-URL: Documentation, https://github.com/PrimeIntellect-ai/prime/tree/main/packages/prime-traces
+Project-URL: Repository, https://github.com/PrimeIntellect-ai/prime.git
+Author-email: Prime Intellect <contact@primeintellect.ai>
+License: MIT
+License-File: LICENSE
+Keywords: evals,observability,rollouts,traces
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.13.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Prime Traces SDK
+
+Upload and query training, evaluation and inference traces through the Prime
+Traces service.
+
+## Features
+
+- **Content-addressed uploads** - Batches are identified by the SHA-256 of
+  their exact bytes, so interrupted uploads are safe to rerun and never store
+  twice
+- **Deterministic batching** - JSONL files are split at byte thresholds without
+  rewriting a single line
+- **Typed reads** - Cursor-paginated summaries over extracted columns and raw
+  document retrieval
+- **Type-safe** - Full type hints and Pydantic models
+- **No CLI dependencies** - Pure SDK, usable in producers and services
+
+## Installation
+
+```bash
+uv add prime-traces
+```
+
+or with pip:
+
+```bash
+pip install prime-traces
+```
+
+## Quick Start
+
+### Upload from memory
+
+`upload_records` accepts JSON-compatible mappings as well as objects exposing
+`to_record()`. Verifiers `Trace` / `Episode` and prime-rl `Rollout` objects
+provide that method, so producers can upload completed records without writing
+an intermediate JSONL file:
+
+```python
+from prime_traces import LineFormat, TracesClient
+
+client = TracesClient()  # PRIME_API_KEY / ~/.prime/config.json
+
+# Iterable[vf.Trace] or Iterable[prime_rl.orchestrator.types.Rollout]
+receipts = client.upload_records(
+    traces,
+    context={"source": "prime-rl", "run_id": "run_9f3k2m"},
+)
+
+# Iterable[vf.Episode] for multi-agent runs
+receipts = client.upload_records(
+    episodes,
+    line_format=LineFormat.EPISODE,
+    context={"source": "verifiers"},
+)
+```
+
+Records are serialized lazily and fed into bounded batches, so this neither
+buffers the complete iterable nor round-trips through the filesystem. Callers
+that already have encoded JSONL bytes can use `upload_lines` directly.
+
+### Upload a completed JSONL file
+
+```python
+from prime_traces import TracesClient, LineFormat
+
+client = TracesClient()  # PRIME_API_KEY / ~/.prime/config.json
+
+# One bare Verifiers trace per line:
+receipts = client.upload_file("traces.jsonl", context={"source": "hosted_eval"})
+
+# One complete episode per line (multi-agent runs):
+receipts = client.upload_file(
+    "episodes.jsonl",
+    line_format=LineFormat.EPISODE,
+    context={"source": "hosted_eval", "suite_commit": "a1f39c2"},
+)
+```
+
+Uploads are content-addressed: each request is identified by the SHA-256 of its
+exact uncompressed JSONL bytes and sent with an `Idempotency-Key`. Rerunning an
+interrupted upload re-reads the file, reproduces the same bytes and keys, and
+the service replays committed receipts without storing anything twice. A 400
+rejection stops the upload with a bounded error code (`ErrorCode`); 429/503 and
+gateway 502/504 are retried with the same bytes, honoring `Retry-After`.
+
+## Query
+
+```python
+page = client.list(run_id="run_9f3k2m", reward_min=0.9, has_error=False)
+for summary in page.items:
+    print(summary.trace_id, summary.score)
+
+for summary in client.iter(task_id="tb2-0187"):  # paginates for you
+    ...
+
+summary = client.get("8d3f1a2b...")
+raw = client.get_raw("8d3f1a2b...")          # exact stored trace document
+client.download_raw("8d3f1a2b...", "t.json")  # streamed, for large traces
+
+client.delete("8d3f1a2b...")        # NotFoundError if the owner has no such trace
+client.delete_run("run_9f3k2m")     # one mutation, synchronous, no job handle
+```
+
+Deletion is not a no-op on absent rows: the service checks existence first and
+answers 404, so repeating a delete that already succeeded raises
+`NotFoundError`. (The design docs specify it as idempotent; this tracks the
+service as built.) Failures known to occur before delivery, 429 responses, and
+service-coded 503 refusals are retried. Ambiguous response-path failures and
+gateway 502/503/504 responses are surfaced as `AmbiguousDeleteError` without
+replaying the deletion, because a retry could delete a trace written after the
+first request.
+
+Trace point reads/deletes and episode point/member reads currently reject IDs
+containing `/`. ASGI decodes an encoded slash before matching the service's
+`/{resource_id}` routes, so those IDs cannot be addressed until the service
+accepts path-valued route parameters.
+
+Episodes are read-only resources:
+
+```python
+page = client.list_episodes(
+    run_id="run_9f3k2m",
+    environment_id="terminal-bench-2",
+)
+for episode in page.items:
+    print(episode.episode_id, episode.outcome)
+
+if page.items:
+    episode_id = page.items[0].episode_id
+    detail = client.get_episode(episode_id)  # + member aggregate under .traces
+    print(detail.error.type, detail.traces.trace_count)
+
+    # Member trace summaries use the trace filters (except sort) and pagination.
+    client.list_episode_traces(episode_id, has_error=True)
+```
+
+Response shapes mirror the service's pinned models: pages are
+`{items, next_cursor}`, a trace summary nests `model` / `score` / `execution`,
+an episode nests `error` and (on point lookup) the member-trace aggregate
+under `traces`, and unrecorded fields come back as `null`.
+
+## Configuration
+
+| Source                 | Meaning                                                                                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PRIME_API_KEY`        | Platform API token (needs `traces:read` / `traces:write` scopes)                                                                            |
+| `PRIME_TEAM_ID`        | Optional team context, sent as `X-Prime-Team-ID`                                                                                            |
+| `PRIME_TRACES_URL`     | Base URL of the Prime Traces service; defaults to the platform API base URL. For the service's local compose stack: `http://localhost:8083` |
+| `~/.prime/config.json` | Shared prime CLI config (`api_key`, `team_id`, `traces_url`)                                                                                |
+
+## Not implemented yet (open v0 contract decisions)
+
+- Exports, in any form. The service publishes `GET /traces/export` and the two
+  job routes, but all three handlers raise `NotImplementedError` — answered as
+  500, not the 501 they document — and the streaming route declares no query
+  parameters, so there is no filter vocabulary to bind to. Wrapping it now
+  would ship a method that cannot succeed.
+- `/search` and free-text queries — deferred with the `trace_components`
+  projection.
+- Typed dot-path predicates (`traces.query`) — needs the server-side field
+  registry.
+- An async client — the other prime SDKs ship sync/async pairs, and the main
+  producers (verifiers, prime-rl) are async; add once the sync surface
+  settles rather than freezing a duplicated API now.
+
+## Documentation
+
+For detailed documentation, visit the
+[Prime Traces SDK documentation](https://github.com/PrimeIntellect-ai/prime/tree/main/packages/prime-traces).
+
+## Related Packages
+
+- [prime](https://github.com/PrimeIntellect-ai/prime/tree/main/packages/prime) - Prime CLI (`prime traces ...` commands)
+- [prime-sandboxes](https://github.com/PrimeIntellect-ai/prime/tree/main/packages/prime-sandboxes) - Sandboxes SDK
+- [prime-evals](https://github.com/PrimeIntellect-ai/prime/tree/main/packages/prime-evals) - Evals SDK

prime_traces-0.0.1/README.md

@@ -0,0 +1,176 @@
+# Prime Traces SDK
+
+Upload and query training, evaluation and inference traces through the Prime
+Traces service.
+
+## Features
+
+- **Content-addressed uploads** - Batches are identified by the SHA-256 of
+  their exact bytes, so interrupted uploads are safe to rerun and never store
+  twice
+- **Deterministic batching** - JSONL files are split at byte thresholds without
+  rewriting a single line
+- **Typed reads** - Cursor-paginated summaries over extracted columns and raw
+  document retrieval
+- **Type-safe** - Full type hints and Pydantic models
+- **No CLI dependencies** - Pure SDK, usable in producers and services
+
+## Installation
+
+```bash
+uv add prime-traces
+```
+
+or with pip:
+
+```bash
+pip install prime-traces
+```
+
+## Quick Start
+
+### Upload from memory
+
+`upload_records` accepts JSON-compatible mappings as well as objects exposing
+`to_record()`. Verifiers `Trace` / `Episode` and prime-rl `Rollout` objects
+provide that method, so producers can upload completed records without writing
+an intermediate JSONL file:
+
+```python
+from prime_traces import LineFormat, TracesClient
+
+client = TracesClient()  # PRIME_API_KEY / ~/.prime/config.json
+
+# Iterable[vf.Trace] or Iterable[prime_rl.orchestrator.types.Rollout]
+receipts = client.upload_records(
+    traces,
+    context={"source": "prime-rl", "run_id": "run_9f3k2m"},
+)
+
+# Iterable[vf.Episode] for multi-agent runs
+receipts = client.upload_records(
+    episodes,
+    line_format=LineFormat.EPISODE,
+    context={"source": "verifiers"},
+)
+```
+
+Records are serialized lazily and fed into bounded batches, so this neither
+buffers the complete iterable nor round-trips through the filesystem. Callers
+that already have encoded JSONL bytes can use `upload_lines` directly.
+
+### Upload a completed JSONL file
+
+```python
+from prime_traces import TracesClient, LineFormat
+
+client = TracesClient()  # PRIME_API_KEY / ~/.prime/config.json
+
+# One bare Verifiers trace per line:
+receipts = client.upload_file("traces.jsonl", context={"source": "hosted_eval"})
+
+# One complete episode per line (multi-agent runs):
+receipts = client.upload_file(
+    "episodes.jsonl",
+    line_format=LineFormat.EPISODE,
+    context={"source": "hosted_eval", "suite_commit": "a1f39c2"},
+)
+```
+
+Uploads are content-addressed: each request is identified by the SHA-256 of its
+exact uncompressed JSONL bytes and sent with an `Idempotency-Key`. Rerunning an
+interrupted upload re-reads the file, reproduces the same bytes and keys, and
+the service replays committed receipts without storing anything twice. A 400
+rejection stops the upload with a bounded error code (`ErrorCode`); 429/503 and
+gateway 502/504 are retried with the same bytes, honoring `Retry-After`.
+
+## Query
+
+```python
+page = client.list(run_id="run_9f3k2m", reward_min=0.9, has_error=False)
+for summary in page.items:
+    print(summary.trace_id, summary.score)
+
+for summary in client.iter(task_id="tb2-0187"):  # paginates for you
+    ...
+
+summary = client.get("8d3f1a2b...")
+raw = client.get_raw("8d3f1a2b...")          # exact stored trace document
+client.download_raw("8d3f1a2b...", "t.json")  # streamed, for large traces
+
+client.delete("8d3f1a2b...")        # NotFoundError if the owner has no such trace
+client.delete_run("run_9f3k2m")     # one mutation, synchronous, no job handle
+```
+
+Deletion is not a no-op on absent rows: the service checks existence first and
+answers 404, so repeating a delete that already succeeded raises
+`NotFoundError`. (The design docs specify it as idempotent; this tracks the
+service as built.) Failures known to occur before delivery, 429 responses, and
+service-coded 503 refusals are retried. Ambiguous response-path failures and
+gateway 502/503/504 responses are surfaced as `AmbiguousDeleteError` without
+replaying the deletion, because a retry could delete a trace written after the
+first request.
+
+Trace point reads/deletes and episode point/member reads currently reject IDs
+containing `/`. ASGI decodes an encoded slash before matching the service's
+`/{resource_id}` routes, so those IDs cannot be addressed until the service
+accepts path-valued route parameters.
+
+Episodes are read-only resources:
+
+```python
+page = client.list_episodes(
+    run_id="run_9f3k2m",
+    environment_id="terminal-bench-2",
+)
+for episode in page.items:
+    print(episode.episode_id, episode.outcome)
+
+if page.items:
+    episode_id = page.items[0].episode_id
+    detail = client.get_episode(episode_id)  # + member aggregate under .traces
+    print(detail.error.type, detail.traces.trace_count)
+
+    # Member trace summaries use the trace filters (except sort) and pagination.
+    client.list_episode_traces(episode_id, has_error=True)
+```
+
+Response shapes mirror the service's pinned models: pages are
+`{items, next_cursor}`, a trace summary nests `model` / `score` / `execution`,
+an episode nests `error` and (on point lookup) the member-trace aggregate
+under `traces`, and unrecorded fields come back as `null`.
+
+## Configuration
+
+| Source                 | Meaning                                                                                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PRIME_API_KEY`        | Platform API token (needs `traces:read` / `traces:write` scopes)                                                                            |
+| `PRIME_TEAM_ID`        | Optional team context, sent as `X-Prime-Team-ID`                                                                                            |
+| `PRIME_TRACES_URL`     | Base URL of the Prime Traces service; defaults to the platform API base URL. For the service's local compose stack: `http://localhost:8083` |
+| `~/.prime/config.json` | Shared prime CLI config (`api_key`, `team_id`, `traces_url`)                                                                                |
+
+## Not implemented yet (open v0 contract decisions)
+
+- Exports, in any form. The service publishes `GET /traces/export` and the two
+  job routes, but all three handlers raise `NotImplementedError` — answered as
+  500, not the 501 they document — and the streaming route declares no query
+  parameters, so there is no filter vocabulary to bind to. Wrapping it now
+  would ship a method that cannot succeed.
+- `/search` and free-text queries — deferred with the `trace_components`
+  projection.
+- Typed dot-path predicates (`traces.query`) — needs the server-side field
+  registry.
+- An async client — the other prime SDKs ship sync/async pairs, and the main
+  producers (verifiers, prime-rl) are async; add once the sync surface
+  settles rather than freezing a duplicated API now.
+
+## Documentation
+
+For detailed documentation, visit the
+[Prime Traces SDK documentation](https://github.com/PrimeIntellect-ai/prime/tree/main/packages/prime-traces).
+
+## Related Packages
+
+- [prime](https://github.com/PrimeIntellect-ai/prime/tree/main/packages/prime) - Prime CLI (`prime traces ...` commands)
+- [prime-sandboxes](https://github.com/PrimeIntellect-ai/prime/tree/main/packages/prime-sandboxes) - Sandboxes SDK
+- [prime-evals](https://github.com/PrimeIntellect-ai/prime/tree/main/packages/prime-evals) - Evals SDK

prime_traces-0.0.1/examples/basic_usage.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""
+Basic usage example for the prime-traces SDK.
+
+This demonstrates the standalone SDK without any CLI dependencies.
+
+Credentials come from PRIME_API_KEY / ~/.prime/config.json. Point
+PRIME_TRACES_URL at the Prime Traces service — e.g. the service's local
+compose stack: PRIME_TRACES_URL=http://localhost:8083
+"""
+
+import tempfile
+import time
+from pathlib import Path
+
+from prime_traces import APIError, ForbiddenError, TracesClient, ValidationRejectedError
+
+
+def sample_trace(trace_id: str, reward: float, started_at: float) -> dict:
+    """One in-memory Verifiers-compatible trace record.
+
+    Trimmed to the fields the service's extractor reads, which is a small
+    subset of a real v1 record — the serialized record is stored verbatim,
+    and every summary column is a projection of it. Two of these are not
+    optional: a non-empty string ``id``, and a numeric ``timing.start`` inside
+    the accepted window (generous lookback, tight lookahead — producers upload
+    completed files, so an old run is ordinary and a future one never is).
+    A line missing either is rejected with ``invalid_trace`` /
+    ``created_at_out_of_window`` and the whole request stores nothing.
+    """
+    return {
+        "version": 4,
+        "id": trace_id,
+        "run": {"id": "run_example"},
+        "task": {"type": "ExampleTask", "data": {"name": "example-0001"}},
+        "agent": {
+            "name": "solver",
+            "config": {
+                "model": "deepseek-v4-flash",
+                "client": {"base_url": "https://api.pinference.ai/api/v1"},
+            },
+        },
+        "calls": [{"model": "deepseek-v4-flash", "usage": {"total_tokens": 1834}}],
+        "rewards": {"correctness": {"score": reward, "weight": 1.0}},
+        "metrics": {},
+        "stop_condition": "done",
+        "ok": True,
+        "errors": [],
+        # `timing.start` is the producer's wall clock and becomes `created_at`;
+        # `timing.scoring.end` is the last phase, so duration_ms comes from the
+        # two together.
+        "timing": {"start": started_at, "scoring": {"end": started_at + 12.5}},
+        "info": {},
+    }
+
+
+def main():
+    # Verifiers Trace objects and prime-rl Rollouts can be passed directly;
+    # both expose the same to_record() protocol accepted by upload_records.
+    started_at = time.time()
+    traces = [
+        sample_trace("3f2a9c1e", reward=0.85, started_at=started_at),
+        sample_trace("b81d4e77", reward=0.40, started_at=started_at + 1.0),
+    ]
+    output_dir = Path(tempfile.mkdtemp())
+
+    with TracesClient() as client:
+        try:
+            print("Uploading...")
+            # Content-addressed: rerunning this replays committed receipts
+            # without storing anything twice.
+            receipts = client.upload_records(
+                traces,
+                context={"source": "example", "suite_commit": "a1f39c2"},
+            )
+            for receipt in receipts:
+                print(f"✓ upload {receipt.upload_id[:12]}… {receipt.status}")
+
+            print("\nListing this run's traces...")
+            page = client.list(run_id="run_example", limit=10)
+            for summary in page.items:
+                # `score` is a nested object, and a null `reward` inside it
+                # means unscored — distinct from a scored 0.0.
+                score = summary.score
+                reward = score.reward if score else None
+                print(f"  {summary.trace_id}  reward={reward}")
+
+            if page.items:
+                trace_id = page.items[0].trace_id
+                print(f"\nFetching raw document for {trace_id}...")
+                dest = output_dir / "trace.json"
+                written = client.download_raw(trace_id, dest)
+                print(f"✓ wrote {written} bytes to {dest}")
+
+        except ValidationRejectedError as error:
+            # A 400 rejects the whole request and stores nothing; branch on
+            # error.code (see prime_traces.ErrorCode), fix the file, rerun.
+            print(f"✗ rejected: {error.code}: {error}")
+        except ForbiddenError as error:
+            # `service_not_enabled` means the account is not in the private
+            # beta; `forbidden` means the token lacks traces:read/traces:write.
+            print(f"✗ not permitted: {error.code}: {error}")
+        except APIError as error:
+            print(f"✗ API error: {error}")
+
+
+if __name__ == "__main__":
+    main()

prime_traces-0.0.1/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "prime-traces"
+# Version is single-sourced from src/prime_traces/__init__.py via Hatch
+dynamic = ["version"]
+description = "Prime Intellect Traces SDK - Upload, query and export traces"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    { name = "Prime Intellect", email = "contact@primeintellect.ai" }
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0",
+]
+keywords = ["traces", "observability", "evals", "rollouts"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence"
+]
+
+[project.urls]
+Homepage = "https://github.com/PrimeIntellect-ai/prime"
+Documentation = "https://github.com/PrimeIntellect-ai/prime/tree/main/packages/prime-traces"
+Repository = "https://github.com/PrimeIntellect-ai/prime.git"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "ruff>=0.13.1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/prime_traces/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/prime_traces"]
+
+[tool.pytest.ini_options]
+addopts = "-v"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+extend-select = ["E", "F", "I"]