flowlines 0.1.0__tar.gz

flowlines-0.1.0/.claude/settings.local.json

@@ -0,0 +1,31 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv sync:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(uv run:*)",
+      "Bash(uv pip index versions:*)",
+      "WebSearch",
+      "WebFetch(domain:pypi.org)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "WebFetch(domain:github.com)",
+      "Bash(uv pip list:*)",
+      "Bash(pip index:*)",
+      "Bash(uv add:*)",
+      "Bash(ANTHROPIC_API_KEY=dummy GEMINI_API_KEY=dummy uv run pytest:*)",
+      "Bash(OPENAI_API_KEY=dummy ANTHROPIC_API_KEY=dummy GEMINI_API_KEY=dummy uv run pytest:*)",
+      "WebFetch(domain:platform.openai.com)",
+      "WebFetch(domain:cookbook.openai.com)",
+      "WebFetch(domain:community.openai.com)",
+      "WebFetch(domain:developers.openai.com)",
+      "WebFetch(domain:docs.windsurf.com)",
+      "WebFetch(domain:docs.cline.bot)",
+      "WebFetch(domain:aider.chat)",
+      "WebFetch(domain:docs.github.com)",
+      "WebFetch(domain:antigravity.google)",
+      "WebFetch(domain:codelabs.developers.google.com)",
+      "Bash(GEMINI_API_KEY=AIzaSyD-cuHx5wvLOEhOrJbLJLJx4xNLJbg1DyM uv run:*)"
+    ]
+  }
+}

flowlines-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Check formatting
+        run: uv run ruff format --check flowlines/ tests/ integration_tests/
+
+      - name: Lint
+        run: uv run ruff check flowlines/ tests/ integration_tests/
+
+      - name: Type check (mypy)
+        run: uv run mypy flowlines/
+
+      - name: Type check (pyright)
+        run: uv run pyright
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest tests/
+
+  integration-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --group integration
+
+      - name: Run integration tests
+        env:
+          OPENAI_API_KEY: ${{ secrets.IT_OPENAI_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.IT_ANTHROPIC_API_KEY }}
+          GEMINI_API_KEY: ${{ secrets.IT_GEMINI_API_KEY }}
+        run: uv run pytest integration_tests/

flowlines-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.env
+*.jsonl

flowlines-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.1
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: uv run pyright
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: mypy
+        name: mypy
+        entry: uv run mypy
+        language: system
+        types: [python]
+        pass_filenames: false

flowlines-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

flowlines-0.1.0/CLAUDE.md

@@ -0,0 +1,71 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+Flowlines SDK for Python — an observability SDK that instruments LLM provider APIs using OpenTelemetry. It captures requests, responses, timing, and errors, filtering to only LLM-related spans and exporting them via OTLP/HTTP to the Flowlines backend.
+
+## Commands
+
+```bash
+# Install dependencies
+uv sync
+
+# Run unit tests
+uv run pytest tests/
+
+# Run a single test
+uv run pytest tests/test_init.py::TestClassName::test_method_name
+
+# Run integration tests (requires OPENAI_API_KEY env var)
+uv run pytest integration_tests/
+
+# Lint
+uv run ruff check flowlines/ tests/ integration_tests/
+
+# Format
+uv run ruff format flowlines/ tests/ integration_tests/
+
+# Type checking
+uv run mypy flowlines/
+uv run pyright
+```
+
+## Architecture
+
+All source is in `flowlines/`. The public API exports `Flowlines` and `FlowlinesExporter` from `__init__.py`.
+
+### Core modules
+
+- **`_init.py`** — `Flowlines` singleton with three initialization modes:
+  - **Mode A** (default): Creates its own `TracerProvider`, registers all available instrumentors automatically
+  - **Mode B1** (`has_external_otel=True`): User manages their own `TracerProvider`; Flowlines provides `create_span_processor()` and `get_instrumentors()` for manual integration
+  - **Mode B2** (`has_traceloop=True`): Traceloop already initialized; Flowlines adds its span processor to the existing provider
+- **`_context.py`** — `FlowlinesSpanProcessor` (decorator over `BatchSpanProcessor`) that injects `user_id`/`session_id`/`agent_id` from `ContextVar` into spans at start time. Context is set via `flowlines.context()` context manager or `Flowlines.set_context()`/`clear_context()` imperative API.
+- **`_exporter.py`** — `FlowlinesExporter` wraps `OTLPSpanExporter`, filtering exported spans to only those with `gen_ai.*` or `ai.*` attributes (via `_filter.py`)
+- **`_filter.py`** — `is_llm_span()` function that identifies LLM-related spans by attribute prefixes
+
+### Key patterns
+
+- **Singleton**: `Flowlines` enforces single instance; `_reset()` classmethod exists for test teardown
+- **Decorator pattern**: Both `FlowlinesSpanProcessor` and `FlowlinesExporter` wrap inner OpenTelemetry objects
+- **Dynamic instrumentor discovery**: Registry of `(library_name, module_path, class_name)` tuples; each instrumentor is loaded only if its library is importable
+
+## Code Conventions
+
+- Private modules prefixed with underscore (`_init.py`, `_context.py`, etc.)
+- `from __future__ import annotations` in all modules
+- Strict type checking enabled (mypy strict + pyright strict)
+- All function signatures have type annotations including return types
+- Google-style docstrings with Args/Returns/Raises sections
+- Ruff lint rules: `E`, `F`, `W`, `I`, `UP`, `B`, `SIM`, `TCH`
+
+## Test Conventions
+
+- Unit tests in `tests/` use `unittest.mock.patch` and `MagicMock` extensively
+- `autouse` fixtures reset the `Flowlines` singleton before each test
+- Tests organized in classes by feature/mode
+- All test functions have type annotations (`-> None`) and docstrings
+- Integration tests in `integration_tests/` use an in-process OTLP capture server
+- `pytest-asyncio` with `asyncio_mode = "auto"`

flowlines-0.1.0/LICENSE

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

flowlines-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: flowlines
+Version: 0.1.0
+Summary: Automatic instrumentation for LLM provider APIs — capture requests, responses, timing, and errors with minimal code changes.
+Project-URL: Homepage, https://github.com/flowlines/flowlines-sdk
+Project-URL: Repository, https://github.com/flowlines/flowlines-sdk
+Author: Flowlines
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: opentelemetry-api>=1.20
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20
+Requires-Dist: opentelemetry-sdk>=1.20
+Provides-Extra: all
+Requires-Dist: opentelemetry-instrumentation-anthropic>=0.40; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-bedrock>=0.40; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-chromadb>=0.40; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-cohere>=0.40; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-google-generativeai>=0.40; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-langchain>=0.40; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-llamaindex>=0.40; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-mcp>=0.40; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-openai>=0.40; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-pinecone>=0.40; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-qdrant>=0.40; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-together>=0.40; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-vertexai>=0.40; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: opentelemetry-instrumentation-anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: bedrock
+Requires-Dist: opentelemetry-instrumentation-bedrock>=0.40; extra == 'bedrock'
+Provides-Extra: chromadb
+Requires-Dist: opentelemetry-instrumentation-chromadb>=0.40; extra == 'chromadb'
+Provides-Extra: cohere
+Requires-Dist: opentelemetry-instrumentation-cohere>=0.40; extra == 'cohere'
+Provides-Extra: google-generativeai
+Requires-Dist: opentelemetry-instrumentation-google-generativeai>=0.40; extra == 'google-generativeai'
+Provides-Extra: langchain
+Requires-Dist: opentelemetry-instrumentation-langchain>=0.40; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: opentelemetry-instrumentation-llamaindex>=0.40; extra == 'llamaindex'
+Provides-Extra: mcp
+Requires-Dist: opentelemetry-instrumentation-mcp>=0.40; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: opentelemetry-instrumentation-openai>=0.40; extra == 'openai'
+Provides-Extra: pinecone
+Requires-Dist: opentelemetry-instrumentation-pinecone>=0.40; extra == 'pinecone'
+Provides-Extra: qdrant
+Requires-Dist: opentelemetry-instrumentation-qdrant>=0.40; extra == 'qdrant'
+Provides-Extra: together
+Requires-Dist: opentelemetry-instrumentation-together>=0.40; extra == 'together'
+Provides-Extra: vertexai
+Requires-Dist: opentelemetry-instrumentation-vertexai>=0.40; extra == 'vertexai'
+Description-Content-Type: text/markdown
+
+# Flowlines SDK for Python
+
+Observability for LLM-powered applications. The Flowlines SDK instruments LLM provider APIs using OpenTelemetry — it captures requests, responses, timing, and errors, and exports them to the Flowlines backend via OTLP/HTTP.
+
+Supported providers: **OpenAI**, **Anthropic**, **AWS Bedrock**, **Cohere**, **Vertex AI**, **Together AI**. Also instruments **LangChain**, **LlamaIndex**, **MCP**, **Pinecone**, **ChromaDB**, and **Qdrant**.
+
+## Requirements
+
+- Python 3.11+
+
+## Installation
+
+```bash
+pip install flowlines
+```
+
+Then install instrumentation extras for the providers you use:
+
+```bash
+# Single provider
+pip install flowlines[openai]
+
+# Multiple providers
+pip install flowlines[openai,anthropic]
+
+# All supported providers
+pip install flowlines[all]
+```
+
+Available extras: `openai`, `anthropic`, `bedrock`, `cohere`, `vertexai`, `together`, `pinecone`, `chromadb`, `qdrant`, `langchain`, `llamaindex`, `mcp`.
+
+## AI coding agent integration
+
+If you use an AI coding agent, you can install the Flowlines skill so your agent knows how to integrate the SDK into your project:
+
+```bash
+npx skills add flowlines-ai/skills
+```
+
+Then, just ask your agent to integrate Flowlines into your project.
+
+## Quick start
+
+If you don't have an existing OpenTelemetry setup, this is all you need:
+
+```python
+from flowlines import Flowlines
+
+flowlines = Flowlines(api_key="your-flowlines-api-key")
+```
+
+That's it. Every LLM call made through an installed provider is now automatically captured and exported to Flowlines. The SDK:
+
+1. Creates an OpenTelemetry `TracerProvider`
+2. Detects which LLM libraries are installed and instruments them
+3. Filters spans to only export LLM-related telemetry
+4. Sends data to the Flowlines backend via OTLP/HTTP
+
+### User, session, and agent tracking
+
+Tag LLM calls with a user ID, session ID, and/or agent ID using the `context()` context manager:
+
+```python
+with flowlines.context(user_id="user-42", session_id="sess-abc"):
+    client.chat.completions.create(...)  # this span gets user_id and session_id
+    client.chat.completions.create(...)  # same
+```
+
+You can also attach an `agent_id` to identify which agent produced the spans:
+
+```python
+with flowlines.context(user_id="user-42", session_id="sess-abc", agent_id="agent-1"):
+    client.chat.completions.create(...)
+```
+
+The `session_id` and `agent_id` are optional — you can track just the user:
+
+```python
+with flowlines.context(user_id="user-42"):
+    client.chat.completions.create(...)
+```
+
+For cases where a context manager doesn't fit (e.g. across request boundaries), use the imperative API. `set_context()` returns a token — pass it to `clear_context()` to restore the previous state:
+
+```python
+token = Flowlines.set_context(user_id="user-42", session_id="sess-abc", agent_id="agent-1")
+try:
+    client.chat.completions.create(...)
+finally:
+    Flowlines.clear_context(token)
+```
+
+Context tracking is thread-safe and async-safe.
+
+### Custom endpoint
+
+By default, data is sent to `https://ingest.flowlines.ai`. You can override this:
+
+```python
+flowlines = Flowlines(
+    api_key="your-flowlines-api-key",
+    endpoint="https://your-custom-endpoint.example.com",
+)
+```
+
+The endpoint must use HTTPS, unless it targets `localhost` / `127.0.0.1` / `::1` (useful for local development).
+
+## Usage with an existing OpenTelemetry setup
+
+If your application already has its own `TracerProvider`, pass `has_external_otel=True` to prevent the SDK from creating a second one:
+
+```python
+from flowlines import Flowlines
+
+flowlines = Flowlines(
+    api_key="your-flowlines-api-key",
+    has_external_otel=True,
+)
+```
+
+In this mode, the SDK does **not** create a `TracerProvider` or register instrumentors. You are responsible for wiring things up yourself:
+
+```python
+from opentelemetry.sdk.trace import TracerProvider
+
+provider = TracerProvider()
+
+# 1. Add the Flowlines span processor to your provider
+processor = flowlines.create_span_processor()
+provider.add_span_processor(processor)
+
+# 2. Instrument providers using the Flowlines instrumentor registry
+for instrumentor in flowlines.get_instrumentors():
+    instrumentor.instrument(tracer_provider=provider)
+```
+
+- `create_span_processor()` returns a span processor that filters and exports LLM spans to Flowlines. Call it exactly once.
+- `get_instrumentors()` returns instrumentor instances for every supported provider library that is currently installed. You can also skip this and register instrumentors yourself.
+
+## Troubleshooting
+
+### Verbose mode
+
+Pass `verbose=True` to enable debug logging. This prints detailed information about initialization, instrumentor discovery, span filtering, and export results to stderr:
+
+```python
+flowlines = Flowlines(api_key="your-flowlines-api-key", verbose=True)
+```
+
+Example output:
+
+```
+[flowlines] Initializing Flowlines SDK (endpoint=https://ingest.flowlines.ai)
+[flowlines] Mode A: creating TracerProvider and registering instrumentors
+[flowlines] Instrumentor loaded: OpenAIInstrumentor
+[flowlines] Instrumentor skipped: anthropic (library not installed)
+[flowlines] Total instrumentors loaded: 1
+[flowlines] Flowlines SDK initialized successfully
+[flowlines] Export: 2/5 span(s) are LLM-related — sending to backend
+[flowlines] Export: succeeded
+```
+
+### No spans appearing in Flowlines
+
+- **Enable verbose mode.** Pass `verbose=True` to see exactly what the SDK is doing — which instrumentors are loaded, how many spans are captured, and whether exports succeed.
+- **Missing instrumentation extras.** The SDK only instruments providers whose instrumentation package is installed. For example, if you use OpenAI, make sure you installed `flowlines[openai]`. Check your installed packages with `pip list | grep opentelemetry-instrumentation`.
+- **Flowlines initialized too late.** The `Flowlines()` constructor must run **before** any LLM calls. If the provider client is created before instrumentation is set up, those calls won't be captured.
+- **Wrong API key.** Verify that the `api_key` you pass is valid. The SDK will export spans, but the backend will reject them silently if the key is invalid.
+
+### `RuntimeError: Flowlines is a singleton`
+
+`Flowlines` enforces a single instance. You're calling `Flowlines(...)` more than once. Store the instance and reuse it, or initialize it once at application startup.
+
+### `ValueError: Endpoint must use HTTPS`
+
+The SDK requires HTTPS for all endpoints except loopback addresses (`localhost`, `127.0.0.1`, `::1`). If you're testing locally, use `http://localhost:<port>`.
+
+### Spans are missing `user_id` / `session_id`
+
+Make sure the LLM call happens **inside** the `flowlines.context()` block or between `set_context()` and `clear_context()`. If you're using threads or async tasks, note that context does not propagate automatically to child threads — set it in each task.
+
+### Duplicate spans or conflicting `TracerProvider`
+
+If you already have an OpenTelemetry setup, you **must** pass `has_external_otel=True`. Otherwise the SDK creates its own `TracerProvider`, which conflicts with yours. See [Usage with an existing OpenTelemetry setup](#usage-with-an-existing-opentelemetry-setup).
+
+## Examples
+
+See the [`examples/`](examples/) directory for working sample applications:
+
+- **[OpenAI conversational agent](examples/openai/)** — Interactive agent with tool calling, demonstrating Mode A auto-instrumentation and context propagation.
+
+## License
+
+MIT

flowlines-0.1.0/PUBLISH.md

@@ -0,0 +1,60 @@
+# Publishing to PyPI
+
+## Prerequisites
+
+1. Install the build tools:
+
+   ```bash
+   uv tool install twine
+   ```
+
+2. Create accounts and API tokens:
+   - **TestPyPI**: https://test.pypi.org/account/register/ — create an API token at https://test.pypi.org/manage/account/
+   - **PyPI**: https://pypi.org/account/register/ — create an API token at https://pypi.org/manage/account/
+
+## Bump the version
+
+Edit `version` in `pyproject.toml`:
+
+```toml
+version = "0.2.0"
+```
+
+## Build
+
+```bash
+rm -rf dist/
+uv build
+```
+
+This produces `dist/flowlines-<version>.tar.gz` and `dist/flowlines-<version>-py3-none-any.whl`.
+
+## Publish to TestPyPI
+
+```bash
+uvx twine upload --repository testpypi dist/*
+```
+
+You will be prompted for credentials. Use `__token__` as the username and your TestPyPI API token as the password.
+
+Verify the result at `https://test.pypi.org/project/flowlines/`.
+
+To install from TestPyPI and check it works:
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ flowlines
+```
+
+(`--extra-index-url` is needed so that dependencies are still fetched from the real PyPI.)
+
+## Publish to PyPI
+
+Once you're satisfied with the TestPyPI release:
+
+```bash
+uvx twine upload dist/*
+```
+
+Use `__token__` as the username and your PyPI API token as the password.
+
+Verify the result at `https://pypi.org/project/flowlines/`.