openflux 0.1.0__tar.gz

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

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --group dev
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+      - run: uv run pyright src/
+      - run: uv run pytest tests/ -v

openflux-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.pyc
+*.pyo
+*.so
+*.egg
+*.egg-info/
+.DS_Store
+dist/
+build/
+.venv/
+.env
+.env.*
+!.env.example
+.claude/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.pyright/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.db

openflux-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.1.0 (2026-03-27)
+
+Initial release.
+
+### Features
+- 22-field Trace schema for normalized AI agent telemetry
+- 9 framework adapters: Claude Code, OpenAI Agents SDK, LangChain, Claude Agent SDK, AutoGen, CrewAI, Google ADK, MCP, Amazon Bedrock
+- 3 sinks: SQLite with FTS5 (default), OTLP/HTTP, NDJSON stdout
+- CLI: `openflux recent`, `search`, `trace`, `export`, `status`, `install`
+- Zero runtime dependencies for core (stdlib only)
+- Content hashing with SHA-256 and fidelity modes (full/redacted)
+- Thread-safe collector with per-session event buffering
+- Path exclusion for sensitive files (*.env, *credentials*, etc.)
+- `openflux install claude-code` auto-configures lifecycle hooks
+
+### Adapters tested E2E
+- MCP (22/22 fields, 100%)
+- Bedrock (21/22, simulated events)
+- Claude Code (hooks + transcript parsing)
+- LangChain (real Gemini API)
+- Google ADK (real Gemini API)
+- Claude Agent SDK (local, Docker needs CLI auth)
+
+### Known limitations
+- OpenAI Agents, AutoGen, CrewAI adapters built but not yet E2E tested (API quota)
+- No web UI (CLI only)
+- SQLite storage only for local use; OTLP for export to external systems

openflux-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to OpenFlux
+
+## Setup
+
+```bash
+git clone https://github.com/advitrocks9/openflux.git
+cd openflux
+uv sync --group dev
+```
+
+## Development
+
+Run tests:
+
+```bash
+uv run pytest tests/ -v
+```
+
+Lint and format:
+
+```bash
+uv run ruff check src/ tests/
+uv run ruff format src/ tests/
+```
+
+Type check:
+
+```bash
+uv run pyright src/
+```
+
+## Pull Requests
+
+Before opening a PR, make sure:
+
+- `uv run pytest tests/ -v` passes
+- `uv run ruff check src/ tests/` is clean
+- `uv run ruff format --check src/ tests/` is clean
+- `uv run pyright src/` reports no errors
+
+## Writing Adapters
+
+Each adapter lives in its own file under `src/openflux/adapters/`. Follow the pattern in existing adapters:
+
+1. Guard framework imports with `try/except ImportError` so the core package stays zero-dep.
+2. Hook into the framework's callback or event system.
+3. Emit raw event dicts to the normalizer -- don't do classification or hashing yourself.
+4. Add the framework as an optional dependency in `pyproject.toml` under `[project.optional-dependencies]`.
+5. Add tests in `tests/` that mock the framework dependency.

openflux-0.1.0/LICENSE

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

openflux-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: openflux
+Version: 0.1.0
+Summary: Open standard for AI agent telemetry. One schema across every framework.
+Project-URL: Homepage, https://github.com/advitrocks9/openflux
+Project-URL: Documentation, https://github.com/advitrocks9/openflux/tree/main/docs
+Project-URL: Repository, https://github.com/advitrocks9/openflux
+Author: Advit Arora
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.12
+Provides-Extra: all
+Requires-Dist: autogen-agentchat>=0.4; extra == 'all'
+Requires-Dist: autogen-ext[openai]>=0.4; extra == 'all'
+Requires-Dist: boto3>=1.28; extra == 'all'
+Requires-Dist: claude-agent-sdk>=0.1; extra == 'all'
+Requires-Dist: crewai[tools]>=0.80; extra == 'all'
+Requires-Dist: google-adk>=0.1; extra == 'all'
+Requires-Dist: langchain-core>=0.1; extra == 'all'
+Requires-Dist: mcp>=1.0; extra == 'all'
+Requires-Dist: openai-agents>=0.1; extra == 'all'
+Provides-Extra: autogen
+Requires-Dist: autogen-agentchat>=0.4; extra == 'autogen'
+Requires-Dist: autogen-ext[openai]>=0.4; extra == 'autogen'
+Provides-Extra: bedrock
+Requires-Dist: boto3>=1.28; extra == 'bedrock'
+Provides-Extra: claude-agent-sdk
+Requires-Dist: claude-agent-sdk>=0.1; extra == 'claude-agent-sdk'
+Provides-Extra: crewai
+Requires-Dist: crewai[tools]>=0.80; extra == 'crewai'
+Provides-Extra: google-adk
+Requires-Dist: google-adk>=0.1; extra == 'google-adk'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == 'langchain'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: openai-agents>=0.1; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# OpenFlux
+
+[![PyPI](https://img.shields.io/pypi/v/openflux)](https://pypi.org/project/openflux/)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/openflux)](https://pypi.org/project/openflux/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+Open standard for AI agent telemetry. One schema across every framework.
+
+## Why
+
+Every agent framework emits telemetry differently. Claude Code uses lifecycle hooks. OpenAI Agents SDK has TracingProcessor. LangChain has callbacks. If you want to build analytics, compliance, or cost tooling on top, you need N integrations from scratch.
+
+OpenFlux normalizes everything into a single schema called a **Trace**: one traced unit of agent work, end to end. Context in, searches run, sources read, tools called, decision made.
+
+Same idea as OpenTelemetry for observability. OTel didn't build dashboards. It built the standard that let them exist. OpenFlux does that for agent telemetry.
+
+## How it works
+
+```
+Adapter (framework-specific) -> Normalizer -> Trace -> Sink(s)
+```
+
+- **Adapters** hook into framework callbacks and emit raw events
+- **Normalizer** classifies events, hashes content, applies fidelity controls
+- **Trace** is the universal schema (22 fields + 4 nested record types)
+- **Sinks** write the Trace somewhere: SQLite (default), OTLP, or JSON stdout
+
+Zero dependencies beyond Python stdlib for the core. Each adapter adds one optional dep.
+
+## Install
+
+```bash
+pip install openflux
+
+# With a specific adapter
+pip install openflux[openai]
+pip install openflux[langchain]
+
+# Everything
+pip install openflux[all]
+```
+
+## Quick start
+
+### Claude Code
+
+Auto-configures lifecycle hooks:
+
+```bash
+openflux install claude-code
+```
+
+### OpenAI Agents SDK
+
+```python
+from agents.tracing import add_trace_processor
+from openflux.adapters.openai_agents import OpenFluxProcessor
+
+add_trace_processor(OpenFluxProcessor(agent="my-agent"))
+```
+
+### LangChain
+
+```python
+import openflux
+
+handler = openflux.langchain_handler(agent="my-rag-app")
+result = chain.invoke({"input": "..."}, config={"callbacks": [handler]})
+```
+
+### Any framework
+
+```python
+import openflux
+
+collector = openflux.init(agent="my-agent")
+
+# Event types: meta, tool, search, source, context
+collector.record_event("session-1", {"type": "meta", "task": "fix auth bug", "model": "gpt-4o"})
+collector.record_event("session-1", {"type": "tool", "tool_name": "Bash", "tool_input": "pytest", "tool_output": "3 passed"})
+collector.record_event("session-1", {"type": "search", "query": "oauth best practices", "engine": "web"})
+
+trace = collector.flush("session-1")  # persisted to ~/.openflux/traces.db
+print(f"Traced: {trace.task} -> {trace.status} ({len(trace.tools_used)} tools)")
+# Then query later: openflux recent
+```
+
+## CLI
+
+```bash
+openflux recent                          # last 10 traces
+openflux recent --agent claude-code      # filter by agent
+openflux search "staging deploy"         # full-text search
+openflux trace trc-a1b2c3d4e5f6          # full detail for one trace
+openflux export > traces.json            # dump as NDJSON
+openflux status                          # db path, counts, breakdown
+openflux install claude-code             # auto-configure hooks
+openflux install --list                  # show available adapters
+```
+
+## What you see
+
+```
+$ openflux recent
+ID              WHEN     AGENT        TASK                                      STATUS
+trc-a1b2c3d4e5  2m ago   claude-code  Fix authentication bug in auth.py         completed
+trc-f6e7d8c9b0  15m ago  my-rag-app   Analyze Q3 revenue data                  completed
+trc-1a2b3c4d5e  1h ago   claude-code  Refactor database connection pooling      completed
+
+3 trace(s) shown.
+```
+
+## Adapter Status
+
+Tested end-to-end with real API calls (Gemini, Claude) and simulated event streams (Bedrock). Coverage = percentage of the 22 Trace fields that are populated in a real test.
+
+| Adapter | Coverage | What's N/A | Install |
+|---------|----------|------------|---------|
+| MCP | 22/22 (100%) | — | `openflux[mcp]` |
+| Amazon Bedrock | 21/22 (100%) | files_modified (cloud agents) | `openflux[bedrock]` |
+| Claude Code | 20/22 (91%) | parent_id, context (not in transcripts) | `(stdlib)` |
+| LangChain | 20/22 (100%) | parent_id, correction | `openflux[langchain]` |
+| Claude Agent SDK | 19/22 (100%) | parent_id, correction, files_modified | `openflux[claude-agent-sdk]` |
+| Google ADK | 18/22 (100%) | parent_id, correction, files_modified, searches | `openflux[google-adk]` |
+| OpenAI Agents SDK | Working | Untested (API quota) | `openflux[openai]` |
+| AutoGen v0.4 | Working | Untested (API quota) | `openflux[autogen]` |
+| CrewAI | Working | Untested (API quota) | `openflux[crewai]` |
+
+Coverage means "of the fields that are structurally possible for this adapter, how many are populated." 100% means every testable field works. See `.claude/findings.md` for details on what's N/A and why.
+
+## Configuration
+
+All env vars, no config files.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `OPENFLUX_DB_PATH` | `~/.openflux/traces.db` | SQLite database location |
+| `OPENFLUX_OTLP_ENDPOINT` | `http://localhost:4318` | OTLP/HTTP endpoint for export |
+| `OPENFLUX_FIDELITY` | `full` | `full` (raw content) or `redacted` (hash-only) |
+| `OPENFLUX_EXCLUDE_PATHS` | `*.env,*credentials*,...` | Glob patterns to exclude from content storage |
+
+## Schema
+
+A Trace captures one complete unit of agent work:
+
+- **Identity**: id, timestamp, agent, session_id, parent_id
+- **What happened**: task, decision, status, correction
+- **Provenance**: context given, searches run, sources read, tools called
+- **Metrics**: token usage, duration, turn count, files modified
+- **Extensibility**: tags, scope, metadata dict
+
+Full schema definition in [docs/PRD.md](docs/PRD.md).
+
+## Development
+
+```bash
+uv run pytest tests/ -v          # tests
+uv run ruff check src/ tests/    # lint
+uv run ruff format src/ tests/   # format
+uv run pyright src/              # type check
+```
+
+## License
+
+[MIT](LICENSE)

openflux-0.1.0/README.md

@@ -0,0 +1,166 @@
+# OpenFlux
+
+[![PyPI](https://img.shields.io/pypi/v/openflux)](https://pypi.org/project/openflux/)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/openflux)](https://pypi.org/project/openflux/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+Open standard for AI agent telemetry. One schema across every framework.
+
+## Why
+
+Every agent framework emits telemetry differently. Claude Code uses lifecycle hooks. OpenAI Agents SDK has TracingProcessor. LangChain has callbacks. If you want to build analytics, compliance, or cost tooling on top, you need N integrations from scratch.
+
+OpenFlux normalizes everything into a single schema called a **Trace**: one traced unit of agent work, end to end. Context in, searches run, sources read, tools called, decision made.
+
+Same idea as OpenTelemetry for observability. OTel didn't build dashboards. It built the standard that let them exist. OpenFlux does that for agent telemetry.
+
+## How it works
+
+```
+Adapter (framework-specific) -> Normalizer -> Trace -> Sink(s)
+```
+
+- **Adapters** hook into framework callbacks and emit raw events
+- **Normalizer** classifies events, hashes content, applies fidelity controls
+- **Trace** is the universal schema (22 fields + 4 nested record types)
+- **Sinks** write the Trace somewhere: SQLite (default), OTLP, or JSON stdout
+
+Zero dependencies beyond Python stdlib for the core. Each adapter adds one optional dep.
+
+## Install
+
+```bash
+pip install openflux
+
+# With a specific adapter
+pip install openflux[openai]
+pip install openflux[langchain]
+
+# Everything
+pip install openflux[all]
+```
+
+## Quick start
+
+### Claude Code
+
+Auto-configures lifecycle hooks:
+
+```bash
+openflux install claude-code
+```
+
+### OpenAI Agents SDK
+
+```python
+from agents.tracing import add_trace_processor
+from openflux.adapters.openai_agents import OpenFluxProcessor
+
+add_trace_processor(OpenFluxProcessor(agent="my-agent"))
+```
+
+### LangChain
+
+```python
+import openflux
+
+handler = openflux.langchain_handler(agent="my-rag-app")
+result = chain.invoke({"input": "..."}, config={"callbacks": [handler]})
+```
+
+### Any framework
+
+```python
+import openflux
+
+collector = openflux.init(agent="my-agent")
+
+# Event types: meta, tool, search, source, context
+collector.record_event("session-1", {"type": "meta", "task": "fix auth bug", "model": "gpt-4o"})
+collector.record_event("session-1", {"type": "tool", "tool_name": "Bash", "tool_input": "pytest", "tool_output": "3 passed"})
+collector.record_event("session-1", {"type": "search", "query": "oauth best practices", "engine": "web"})
+
+trace = collector.flush("session-1")  # persisted to ~/.openflux/traces.db
+print(f"Traced: {trace.task} -> {trace.status} ({len(trace.tools_used)} tools)")
+# Then query later: openflux recent
+```
+
+## CLI
+
+```bash
+openflux recent                          # last 10 traces
+openflux recent --agent claude-code      # filter by agent
+openflux search "staging deploy"         # full-text search
+openflux trace trc-a1b2c3d4e5f6          # full detail for one trace
+openflux export > traces.json            # dump as NDJSON
+openflux status                          # db path, counts, breakdown
+openflux install claude-code             # auto-configure hooks
+openflux install --list                  # show available adapters
+```
+
+## What you see
+
+```
+$ openflux recent
+ID              WHEN     AGENT        TASK                                      STATUS
+trc-a1b2c3d4e5  2m ago   claude-code  Fix authentication bug in auth.py         completed
+trc-f6e7d8c9b0  15m ago  my-rag-app   Analyze Q3 revenue data                  completed
+trc-1a2b3c4d5e  1h ago   claude-code  Refactor database connection pooling      completed
+
+3 trace(s) shown.
+```
+
+## Adapter Status
+
+Tested end-to-end with real API calls (Gemini, Claude) and simulated event streams (Bedrock). Coverage = percentage of the 22 Trace fields that are populated in a real test.
+
+| Adapter | Coverage | What's N/A | Install |
+|---------|----------|------------|---------|
+| MCP | 22/22 (100%) | — | `openflux[mcp]` |
+| Amazon Bedrock | 21/22 (100%) | files_modified (cloud agents) | `openflux[bedrock]` |
+| Claude Code | 20/22 (91%) | parent_id, context (not in transcripts) | `(stdlib)` |
+| LangChain | 20/22 (100%) | parent_id, correction | `openflux[langchain]` |
+| Claude Agent SDK | 19/22 (100%) | parent_id, correction, files_modified | `openflux[claude-agent-sdk]` |
+| Google ADK | 18/22 (100%) | parent_id, correction, files_modified, searches | `openflux[google-adk]` |
+| OpenAI Agents SDK | Working | Untested (API quota) | `openflux[openai]` |
+| AutoGen v0.4 | Working | Untested (API quota) | `openflux[autogen]` |
+| CrewAI | Working | Untested (API quota) | `openflux[crewai]` |
+
+Coverage means "of the fields that are structurally possible for this adapter, how many are populated." 100% means every testable field works. See `.claude/findings.md` for details on what's N/A and why.
+
+## Configuration
+
+All env vars, no config files.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `OPENFLUX_DB_PATH` | `~/.openflux/traces.db` | SQLite database location |
+| `OPENFLUX_OTLP_ENDPOINT` | `http://localhost:4318` | OTLP/HTTP endpoint for export |
+| `OPENFLUX_FIDELITY` | `full` | `full` (raw content) or `redacted` (hash-only) |
+| `OPENFLUX_EXCLUDE_PATHS` | `*.env,*credentials*,...` | Glob patterns to exclude from content storage |
+
+## Schema
+
+A Trace captures one complete unit of agent work:
+
+- **Identity**: id, timestamp, agent, session_id, parent_id
+- **What happened**: task, decision, status, correction
+- **Provenance**: context given, searches run, sources read, tools called
+- **Metrics**: token usage, duration, turn count, files modified
+- **Extensibility**: tags, scope, metadata dict
+
+Full schema definition in [docs/PRD.md](docs/PRD.md).
+
+## Development
+
+```bash
+uv run pytest tests/ -v          # tests
+uv run ruff check src/ tests/    # lint
+uv run ruff format src/ tests/   # format
+uv run pyright src/              # type check
+```
+
+## License
+
+[MIT](LICENSE)