Metadata-Version: 2.4
Name: ollama-telemetry
Version: 0.1.2
Summary: Privacy-first, SQLite-first observability for local Ollama agents.
Project-URL: Homepage, https://github.com/sanchitsinghal7/ollama-telemetry
Project-URL: Repository, https://github.com/sanchitsinghal7/ollama-telemetry
Project-URL: Issues, https://github.com/sanchitsinghal7/ollama-telemetry/issues
Author: Ollama Telemetry Contributors
License: Apache-2.0
License-File: LICENSE
Keywords: llm,local-ai,observability,ollama,sqlite,telemetry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == 'langchain'
Requires-Dist: langchain-ollama>=0.2; extra == 'langchain'
Provides-Extra: ollama
Requires-Dist: ollama>=0.3; extra == 'ollama'
Description-Content-Type: text/markdown

# ollama-telemetry

**Privacy-first, SQLite-first observability for local Ollama agents.**

- Stores telemetry locally in SQLite by default.
- Never stores prompts, completions, message bodies, or raw response payloads.
- No cloud account, API key, network service, or proprietary agent integration required.
- Captures Ollama token counts and latency fields when available.
- Supports explicit tracing and optional `ChatOllama` auto-instrumentation.

> Package name availability on PyPI must be checked before publishing.

## Install

```bash
pip install ollama-telemetry
```

For LangChain / `ChatOllama`:

```bash
pip install "ollama-telemetry[langchain]"
```

## Zero-code-ish LangChain setup

```python
from ollama_telemetry import enable

enable(auto_instrument_langchain=True)

# Existing ChatOllama code can run after this point.
```

Auto instrumentation is opt-in and intentionally marked as a convenience mode. The explicit API below is the recommended production approach.

## Explicit tracing

`telemetry.agent(...)` works as either a decorator or a context manager. Both forms create one root trace.

```python
from ollama_telemetry import telemetry
from ollama_telemetry.integrations.langchain import OllamaTelemetryCallback
from langchain_ollama import ChatOllama

telemetry.init()

@telemetry.agent(name="research_agent", workflow="summarization")
def run(document_id: str, messages):
    llm = ChatOllama(
        model="qwen3:8b",
        callbacks=[OllamaTelemetryCallback()],
    )
    with telemetry.context(entity_type="document", entity_id=document_id):
        return llm.invoke(messages)
```

## Direct Ollama response capture

```python
from ollama_telemetry import telemetry
from ollama import chat

telemetry.init()

with telemetry.agent("local_research_agent"):
    response = chat(
        model="qwen3:8b",
        messages=[{"role": "user", "content": "Summarize this."}],
    )
    telemetry.capture_ollama_response(response, model="qwen3:8b")
```

## Database

Default location:

```text
~/.ollama-telemetry/telemetry.db
```

Override it:

```bash
export OLLAMA_TELEMETRY_DB=/path/to/telemetry.db
```

The SQLite table is `telemetry_events`. It stores identifiers, timing, model, status, safe usage counters, and JSON metadata. It does **not** store content fields.

## CLI

```bash
ollama-telemetry status
ollama-telemetry stats --last 7d
ollama-telemetry models --last 30d
ollama-telemetry agents --last 30d
ollama-telemetry traces --failed
ollama-telemetry prune --older-than 30d
ollama-telemetry vacuum
```

## Privacy guarantees

The package rejects sensitive metadata keys such as `prompt`, `completion`, `messages`, `response`, `content`, and `raw_response`. Safe metadata is limited to scalar values and small lists/dictionaries after recursive filtering.

## Development

```bash
python -m pip install -e ".[dev]"
pytest
python -m build
```

## License

Apache-2.0.
