freesolo 0.1.0__tar.gz

freesolo-0.1.0/.env.example

@@ -0,0 +1,2 @@
+FREESOLO_BASE_URL=http://localhost:3000
+FREESOLO_API_KEY=

freesolo-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+node_modules/
+__pycache__/
+.pytest_cache/
+*.pyc
+.env
+.env.local
+examples/.env
+examples/.env.local

freesolo-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: freesolo
+Version: 0.1.0
+Summary: Decorator-based LLM tracing package with OpenAI and Anthropic client instrumentation.
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.11.0; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: anthropic>=0.40.0; extra == 'examples'
+Requires-Dist: openai>=1.0.0; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# freesolo
+
+`freesolo` is a Python tracing package for the Reinforcement Labs app.
+
+It is designed for the lowest-friction integration possible:
+
+1. Install the package
+2. Configure one endpoint + API key
+3. Start a trace once
+4. Add `@trace()` to your functions
+5. Optionally wrap your OpenAI, Anthropic, or Google client for automatic provider spans
+
+## Install
+
+```bash
+cd tracing
+uv sync
+```
+
+To run the bundled example apps:
+
+```bash
+cd tracing
+uv sync --extra examples
+```
+
+## Environment
+
+The package reads these environment variables by default:
+
+- `FREESOLO_BASE_URL`
+- `FREESOLO_API_KEY`
+
+The frontend app must also have:
+
+- `FREESOLO_API_KEY`
+- `SUPABASE_SECRET_KEY`
+
+The canonical database schema lives in `frontend/supabase/migrations/`.
+There is no separate tracing-side migration folder because both the ingest API
+and the Supabase project are owned by the frontend app in this repo.
+
+Runnable examples live in [`examples/`](./examples/README.md). They will
+autoload env vars from `frontend/.env`, `tracing/.env`, or `tracing/examples/.env`.
+
+## Quickstart
+
+```python
+from openai import OpenAI
+from freesolo import configure, instrument_openai, start_trace, trace
+
+configure(
+    base_url="https://your-app.com",
+    api_key="freesolo_api_key",
+)
+
+client = instrument_openai(OpenAI())
+
+@trace()
+def run_agent(question: str) -> str:
+    result = client.chat.completions.create(
+        model="gpt-4.1",
+        messages=[
+            {"role": "user", "content": question},
+        ],
+    )
+    return result.choices[0].message.content or ""
+
+
+with start_trace("support-agent-run"):
+    print(run_agent("How do I reset my password?"))
+```
+
+## What Gets Stored
+
+- Trace metadata if you explicitly pass it to `start_trace(..., metadata=...)`
+- Spans from decorators
+- OpenAI / Anthropic / Google request + response payloads
+- Token usage when available
+- Image inputs summarized safely instead of storing full base64 blobs
+
+## Notes
+
+- If you do nothing except add `@trace()`, you still get useful spans.
+- Use `start_trace(trace_id=...)` when you want several decorated functions to land in one trace.
+- If you also wrap the LLM client, you get dedicated provider/model spans.
+- Delivery is best-effort by default. Trace ingestion failures do not break your app.

freesolo-0.1.0/README.md

@@ -0,0 +1,87 @@
+# freesolo
+
+`freesolo` is a Python tracing package for the Reinforcement Labs app.
+
+It is designed for the lowest-friction integration possible:
+
+1. Install the package
+2. Configure one endpoint + API key
+3. Start a trace once
+4. Add `@trace()` to your functions
+5. Optionally wrap your OpenAI, Anthropic, or Google client for automatic provider spans
+
+## Install
+
+```bash
+cd tracing
+uv sync
+```
+
+To run the bundled example apps:
+
+```bash
+cd tracing
+uv sync --extra examples
+```
+
+## Environment
+
+The package reads these environment variables by default:
+
+- `FREESOLO_BASE_URL`
+- `FREESOLO_API_KEY`
+
+The frontend app must also have:
+
+- `FREESOLO_API_KEY`
+- `SUPABASE_SECRET_KEY`
+
+The canonical database schema lives in `frontend/supabase/migrations/`.
+There is no separate tracing-side migration folder because both the ingest API
+and the Supabase project are owned by the frontend app in this repo.
+
+Runnable examples live in [`examples/`](./examples/README.md). They will
+autoload env vars from `frontend/.env`, `tracing/.env`, or `tracing/examples/.env`.
+
+## Quickstart
+
+```python
+from openai import OpenAI
+from freesolo import configure, instrument_openai, start_trace, trace
+
+configure(
+    base_url="https://your-app.com",
+    api_key="freesolo_api_key",
+)
+
+client = instrument_openai(OpenAI())
+
+@trace()
+def run_agent(question: str) -> str:
+    result = client.chat.completions.create(
+        model="gpt-4.1",
+        messages=[
+            {"role": "user", "content": question},
+        ],
+    )
+    return result.choices[0].message.content or ""
+
+
+with start_trace("support-agent-run"):
+    print(run_agent("How do I reset my password?"))
+```
+
+## What Gets Stored
+
+- Trace metadata if you explicitly pass it to `start_trace(..., metadata=...)`
+- Spans from decorators
+- OpenAI / Anthropic / Google request + response payloads
+- Token usage when available
+- Image inputs summarized safely instead of storing full base64 blobs
+
+## Notes
+
+- If you do nothing except add `@trace()`, you still get useful spans.
+- Use `start_trace(trace_id=...)` when you want several decorated functions to land in one trace.
+- If you also wrap the LLM client, you get dedicated provider/model spans.
+- Delivery is best-effort by default. Trace ingestion failures do not break your app.

freesolo-0.1.0/examples/.env.example

@@ -0,0 +1,6 @@
+OPENAI_API_KEY=
+
+ANTHROPIC_API_KEY=
+
+FREESOLO_BASE_URL=http://localhost:3000
+FREESOLO_API_KEY=

freesolo-0.1.0/examples/README.md

@@ -0,0 +1,47 @@
+# Examples
+
+These examples show the intended integration shape:
+
+1. install `freesolo`
+2. wrap the provider client once
+3. start a trace once
+4. add `@trace()` to your own workflow functions
+5. let the package emit traces to the frontend ingest API
+
+## Setup
+
+```bash
+cd tracing
+uv sync --extra examples
+cp examples/.env.example examples/.env
+```
+
+The scripts load env vars in this order:
+
+1. `frontend/.env`
+2. `frontend/.env.local`
+3. `tracing/.env`
+4. `tracing/.env.local`
+5. `tracing/examples/.env`
+6. `tracing/examples/.env.local`
+
+That means if your provider keys already live in `rl/frontend/.env`, the
+examples can usually use them without any extra setup.
+
+## Run
+
+```bash
+cd tracing
+uv run python -m examples.openai.chat "Write a two-sentence launch blurb."
+uv run python -m examples.openai.vision https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg --prompt "Describe the image in three bullet points."
+uv run python -m examples.anthropic.chat "Summarize why tracing is useful."
+uv run python -m examples.anthropic.vision https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg --prompt "What is in this image?"
+```
+
+For the vision examples you can pass either:
+
+- an `https://...` image URL
+- a local `.png`, `.jpg`, `.jpeg`, `.gif`, or `.webp` path
+
+If `FREESOLO_BASE_URL` and `FREESOLO_API_KEY` are missing, the
+provider calls still run but trace delivery is disabled.

freesolo-0.1.0/examples/__init__.py

@@ -0,0 +1 @@
+"""Runnable examples for the freesolo package."""

freesolo-0.1.0/examples/anthropic/__init__.py

@@ -0,0 +1 @@
+"""Anthropic example scripts."""

freesolo-0.1.0/examples/anthropic/chat.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import argparse
+
+from anthropic import Anthropic
+
+from freesolo import instrument_anthropic, start_trace, trace
+
+from ..utils import (
+    configure_example,
+    extract_anthropic_text,
+    print_runtime_status,
+    require_env,
+)
+
+CHAT_MODEL = "claude-sonnet-4-20250514"
+
+client: Anthropic | None = None
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Anthropic chat example with tracing."
+    )
+    parser.add_argument(
+        "prompt",
+        nargs="?",
+        default="Summarize why tracing is useful for LLM applications.",
+    )
+    return parser.parse_args()
+
+
+def get_client() -> Anthropic:
+    if client is None:
+        raise RuntimeError("Anthropic client has not been initialized.")
+    return client
+
+
+@trace()
+def run_chat(prompt: str) -> str:
+    response = get_client().messages.create(
+        model=CHAT_MODEL,
+        max_tokens=300,
+        system="You are a concise assistant. Reply in plain text.",
+        messages=[
+            {
+                "role": "user",
+                "content": prompt,
+            }
+        ],
+    )
+    return extract_anthropic_text(response)
+
+
+def main() -> None:
+    global client
+
+    args = parse_args()
+    configure_example()
+
+    client = instrument_anthropic(
+        Anthropic(api_key=require_env("ANTHROPIC_API_KEY"))
+    )
+
+    print_runtime_status(provider="anthropic", model=CHAT_MODEL)
+    print()
+    with start_trace("example_anthropic_chat"):
+        print(run_chat(args.prompt))
+
+
+if __name__ == "__main__":
+    main()

freesolo-0.1.0/examples/anthropic/vision.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import argparse
+
+from anthropic import Anthropic
+
+from freesolo import instrument_anthropic, start_trace, trace
+
+from ..utils import (
+    configure_example,
+    extract_anthropic_text,
+    load_image_input,
+    print_runtime_status,
+    require_env,
+)
+
+VISION_MODEL = "claude-sonnet-4-20250514"
+
+client: Anthropic | None = None
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Anthropic vision example with tracing."
+    )
+    parser.add_argument(
+        "image",
+        help="Local image path or https URL.",
+    )
+    parser.add_argument(
+        "--prompt",
+        default="What is in this image? Keep the answer concise.",
+    )
+    return parser.parse_args()
+
+
+def get_client() -> Anthropic:
+    if client is None:
+        raise RuntimeError("Anthropic client has not been initialized.")
+    return client
+
+
+@trace()
+def run_vision(prompt: str, image_reference: str) -> str:
+    image = load_image_input(image_reference)
+    if image["kind"] == "url":
+        image_block = {
+            "type": "image",
+            "source": {
+                "type": "url",
+                "url": image["url"],
+            },
+        }
+    else:
+        image_block = {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": image["media_type"],
+                "data": image["base64_data"],
+            },
+        }
+
+    response = get_client().messages.create(
+        model=VISION_MODEL,
+        max_tokens=400,
+        messages=[
+            {
+                "role": "user",
+                "content": [
+                    image_block,
+                    {"type": "text", "text": prompt},
+                ],
+            }
+        ],
+    )
+    return extract_anthropic_text(response)
+
+
+def main() -> None:
+    global client
+
+    args = parse_args()
+    configure_example()
+
+    client = instrument_anthropic(
+        Anthropic(api_key=require_env("ANTHROPIC_API_KEY"))
+    )
+
+    print_runtime_status(provider="anthropic", model=VISION_MODEL)
+    print()
+    with start_trace("example_anthropic_vision"):
+        print(run_vision(args.prompt, args.image))
+
+
+if __name__ == "__main__":
+    main()

freesolo-0.1.0/examples/openai/__init__.py

@@ -0,0 +1 @@
+"""OpenAI example scripts."""

freesolo-0.1.0/examples/openai/chat.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import argparse
+
+from openai import OpenAI
+
+from freesolo import instrument_openai, start_trace, trace
+
+from ..utils import (
+    configure_example,
+    extract_openai_text,
+    print_runtime_status,
+    require_env,
+)
+
+CHAT_MODEL = "gpt-4.1-mini"
+
+client: OpenAI | None = None
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="OpenAI chat example with tracing.")
+    parser.add_argument(
+        "prompt",
+        nargs="?",
+        default="Write a two-sentence launch blurb for Reinforcement Labs.",
+    )
+    return parser.parse_args()
+
+
+def get_client() -> OpenAI:
+    if client is None:
+        raise RuntimeError("OpenAI client has not been initialized.")
+    return client
+
+
+@trace()
+def run_chat(prompt: str) -> str:
+    response = get_client().chat.completions.create(
+        model=CHAT_MODEL,
+        messages=[
+            {
+                "role": "system",
+                "content": "You are a concise assistant. Reply in plain text.",
+            },
+            {"role": "user", "content": prompt},
+        ],
+        max_tokens=300,
+    )
+    return extract_openai_text(response)
+
+
+def main() -> None:
+    global client
+
+    args = parse_args()
+    configure_example()
+
+    client = instrument_openai(OpenAI(api_key=require_env("OPENAI_API_KEY")))
+
+    print_runtime_status(provider="openai", model=CHAT_MODEL)
+    print()
+    with start_trace("example_openai_chat"):
+        print(run_chat(args.prompt))
+
+
+if __name__ == "__main__":
+    main()

freesolo-0.1.0/examples/openai/vision.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import argparse
+
+from openai import OpenAI
+
+from freesolo import instrument_openai, start_trace, trace
+
+from ..utils import (
+    configure_example,
+    extract_openai_text,
+    load_image_input,
+    print_runtime_status,
+    require_env,
+)
+
+VISION_MODEL = "gpt-4.1-mini"
+
+client: OpenAI | None = None
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="OpenAI vision example with tracing."
+    )
+    parser.add_argument(
+        "image",
+        help="Local image path or https URL.",
+    )
+    parser.add_argument(
+        "--prompt",
+        default="Describe this image in three bullet points.",
+    )
+    return parser.parse_args()
+
+
+def get_client() -> OpenAI:
+    if client is None:
+        raise RuntimeError("OpenAI client has not been initialized.")
+    return client
+
+
+@trace()
+def run_vision(prompt: str, image_reference: str) -> str:
+    image = load_image_input(image_reference)
+    image_url = image["url"] if image["kind"] == "url" else image["data_url"]
+
+    response = get_client().chat.completions.create(
+        model=VISION_MODEL,
+        messages=[
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": prompt},
+                    {"type": "image_url", "image_url": {"url": image_url}},
+                ],
+            }
+        ],
+        max_tokens=400,
+    )
+    return extract_openai_text(response)
+
+
+def main() -> None:
+    global client
+
+    args = parse_args()
+    configure_example()
+
+    client = instrument_openai(OpenAI(api_key=require_env("OPENAI_API_KEY")))
+
+    print_runtime_status(provider="openai", model=VISION_MODEL)
+    print()
+    with start_trace("example_openai_vision"):
+        print(run_vision(args.prompt, args.image))
+
+
+if __name__ == "__main__":
+    main()