e-track 0.1.0__tar.gz

e_track-0.1.0/.gitignore

@@ -0,0 +1,226 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# e-track
+.sandbox/
+.plans/
+.serena/
+.ty_cache/

e_track-0.1.0/LICENSE

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

e_track-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: e-track
+Version: 0.1.0
+Summary: Run tracking for agent systems: one event model carried by a structlog channel, many parallel sinks (OTLP, live).
+Project-URL: Homepage, https://github.com/edamlabs/e-track
+Project-URL: Documentation, https://edamlabs.github.io/e-track/
+Project-URL: Source, https://github.com/edamlabs/e-track
+Project-URL: Issues, https://github.com/edamlabs/e-track/issues
+Project-URL: Changelog, https://github.com/edamlabs/e-track/blob/main/CHANGELOG.md
+Author: EDamLabs
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,e-stack,langgraph,opentelemetry,structlog,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: anyio>=4.6
+Requires-Dist: msgspec>=0.21
+Requires-Dist: pydantic-settings>=2.6
+Requires-Dist: structlog>=26.1
+Provides-Extra: all
+Requires-Dist: e-serde>=0.6.2; extra == 'all'
+Requires-Dist: langchain-core>=1.5.2; extra == 'all'
+Requires-Dist: langgraph>=1.2.7; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.44; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.44; extra == 'all'
+Requires-Dist: rustworkx>=0.17; extra == 'all'
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=1.5.2; extra == 'langgraph'
+Requires-Dist: langgraph>=1.2.7; extra == 'langgraph'
+Provides-Extra: otel
+Requires-Dist: e-serde>=0.6.2; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.44; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.44; extra == 'otel'
+Provides-Extra: topology
+Requires-Dist: rustworkx>=0.17; extra == 'topology'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://github.com/edamlabs/e-track/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/edamlabs/e-track/ci.yml?label=test" alt="CI"></a>
+  <a href="https://pypi.org/project/e-track/"><img src="https://img.shields.io/pypi/v/e-track?color=166b7e" alt="PyPI"></a>
+  <a href="https://pypi.org/project/e-track/"><img src="https://img.shields.io/pypi/pyversions/e-track" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/edamlabs/e-track?color=166b7e" alt="License"></a>
+</p>
+
+<p align="center">
+  <img src="assets/logo.svg" alt="e-track" height="110" />
+</p>
+
+Run tracking for agent systems. A source turns a framework's run into **one event model**; the model travels on a
+**structlog channel** of its own; a bus fans it out to **parallel sinks**, each reading the partial view it declares.
+
+```
+framework hooks ─► source ─► fold ─► channel (validate → publish → forward to host logger)
+                                                 │
+                                                 └─► bus ─┬─► otlp   spans + logs → Langfuse · LangSmith · Tempo · Phoenix
+                                                          ├─► live   per-thread replay + push → a canvas, a chat
+                                                          └─► yours  any SinkPort, any EventView
+```
+
+Part of the **EDamLabs eager series**: EDamLabs' own e- products ([EDamLabs families](https://github.com/edamlabs/e-workbench#identity)).
+
+## Install
+
+```bash
+uv add "e-track[langgraph,otel]"    # or: pip install "e-track[langgraph,otel]"
+```
+
+Extras: `langgraph` (LangGraph/deepagents source and topology), `otel` (OTLP driver), `topology` (layout), `all`.
+Python 3.14+, typed (`py.typed`).
+
+## Usage
+
+```python
+from contextlib import AsyncExitStack
+
+from etrack.logic.api import Tracker
+from etrack.logic.channel import EventChannel
+from etrack.models.event import EventKind
+from etrack.providers.adapters.bus.anyio import AnyioAdapter
+from etrack.providers.adapters.sink.live import LiveAdapter
+from etrack.providers.adapters.source.langgraph import LanggraphSourceAdapter
+from etrack.providers.drivers.sink.otlp import OtlpDriver
+
+async with AsyncExitStack() as stack:                       # the host's composition root
+    live = await stack.enter_async_context(LiveAdapter())
+    otlp = await stack.enter_async_context(OtlpDriver())
+    bus = AnyioAdapter()
+    bus.subscribe(live)
+    bus.subscribe(otlp, select=lambda event: event if event.part is None else None)  # policy per sink
+    await stack.enter_async_context(bus)                   # opened last: closed first, drains into the sinks
+    tracker = Tracker(EventChannel(bus), LanggraphSourceAdapter(mcp=frozenset({"onto_query"})))
+
+    with tracker.track(thread="t1", config={"configurable": {"thread_id": "t1"}}) as run:
+        await graph.ainvoke({"messages": [("user", "hola")]}, run.config)
+        with run.fold.span("gate", kind=EventKind.EVALUATION):
+            ...                                             # the project's own code, same tree
+```
+
+With the house renderer (`ELogger`) on the host:
+
+```
+2026-11-03T12:00:00Z | INFO | run.event || run_id: 019a… || kind: node || phase: start || name: agent || step: 1
+```
+
+Every frame is also a line on the host's `etrack` logger, rendered by the host's own structlog setup; e-track never
+configures logging.
+
+## The record
+
+| Field | What |
+|---|---|
+| `run_id`, `thread_id` | the run (32 hex, also the W3C trace id) and the conversation |
+| `seq`, `id`, `parent` | order within the run; the span and its visible parent |
+| `kind` | `run agent subagent node llm embedding retrieval tool mcp interrupt state evaluation custom` |
+| `phase` | `start delta end error instant` |
+| `part` | on deltas: `text reasoning tool_call image audio video file custom` |
+| `node`, `ns`, `step`, `visit` | graph coordinates: node, subgraph path, superstep, times the run entered the node |
+| `message_id`, `call_id` | the chat message and the tool call a client renders |
+| `model`, `usage`, `error` | typed sections: provider/name/params, tokens/cost, failure |
+| `payload`, `attributes` | what the span carried (redacted); the open, namespaced extension bag |
+
+Grow it by subclassing `RunEvent` and passing the subclass to `EventChannel(model=…)`; read it through an `EventView`.
+
+The full guide lives at [edamlabs.github.io/e-track](https://edamlabs.github.io/e-track/).
+
+## Development
+
+```bash
+make install        # sync deps + prek hooks
+make check          # lint + type + arch + validate + test
+make cov            # coverage gate: 100 % lines and branches, every outbound service faked in process
+make integration    # real services: the session fixtures bring sandbox/compose.yml up and down (collector + Phoenix)
+make ci             # every gate CI runs, in one command
+```
+
+Stack: uv · ruff · ty · tach · pytest (xdist, randomly, pytest-docker) · prek · zizmor · Zensical · Renovate.
+Released from a `v*` tag through PyPI trusted publishing; maintained by the [EDamLabs fleet](https://github.com/edamlabs/e-workbench).

e_track-0.1.0/README.md

@@ -0,0 +1,100 @@
+<p align="center">
+  <a href="https://github.com/edamlabs/e-track/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/edamlabs/e-track/ci.yml?label=test" alt="CI"></a>
+  <a href="https://pypi.org/project/e-track/"><img src="https://img.shields.io/pypi/v/e-track?color=166b7e" alt="PyPI"></a>
+  <a href="https://pypi.org/project/e-track/"><img src="https://img.shields.io/pypi/pyversions/e-track" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/edamlabs/e-track?color=166b7e" alt="License"></a>
+</p>
+
+<p align="center">
+  <img src="assets/logo.svg" alt="e-track" height="110" />
+</p>
+
+Run tracking for agent systems. A source turns a framework's run into **one event model**; the model travels on a
+**structlog channel** of its own; a bus fans it out to **parallel sinks**, each reading the partial view it declares.
+
+```
+framework hooks ─► source ─► fold ─► channel (validate → publish → forward to host logger)
+                                                 │
+                                                 └─► bus ─┬─► otlp   spans + logs → Langfuse · LangSmith · Tempo · Phoenix
+                                                          ├─► live   per-thread replay + push → a canvas, a chat
+                                                          └─► yours  any SinkPort, any EventView
+```
+
+Part of the **EDamLabs eager series**: EDamLabs' own e- products ([EDamLabs families](https://github.com/edamlabs/e-workbench#identity)).
+
+## Install
+
+```bash
+uv add "e-track[langgraph,otel]"    # or: pip install "e-track[langgraph,otel]"
+```
+
+Extras: `langgraph` (LangGraph/deepagents source and topology), `otel` (OTLP driver), `topology` (layout), `all`.
+Python 3.14+, typed (`py.typed`).
+
+## Usage
+
+```python
+from contextlib import AsyncExitStack
+
+from etrack.logic.api import Tracker
+from etrack.logic.channel import EventChannel
+from etrack.models.event import EventKind
+from etrack.providers.adapters.bus.anyio import AnyioAdapter
+from etrack.providers.adapters.sink.live import LiveAdapter
+from etrack.providers.adapters.source.langgraph import LanggraphSourceAdapter
+from etrack.providers.drivers.sink.otlp import OtlpDriver
+
+async with AsyncExitStack() as stack:                       # the host's composition root
+    live = await stack.enter_async_context(LiveAdapter())
+    otlp = await stack.enter_async_context(OtlpDriver())
+    bus = AnyioAdapter()
+    bus.subscribe(live)
+    bus.subscribe(otlp, select=lambda event: event if event.part is None else None)  # policy per sink
+    await stack.enter_async_context(bus)                   # opened last: closed first, drains into the sinks
+    tracker = Tracker(EventChannel(bus), LanggraphSourceAdapter(mcp=frozenset({"onto_query"})))
+
+    with tracker.track(thread="t1", config={"configurable": {"thread_id": "t1"}}) as run:
+        await graph.ainvoke({"messages": [("user", "hola")]}, run.config)
+        with run.fold.span("gate", kind=EventKind.EVALUATION):
+            ...                                             # the project's own code, same tree
+```
+
+With the house renderer (`ELogger`) on the host:
+
+```
+2026-11-03T12:00:00Z | INFO | run.event || run_id: 019a… || kind: node || phase: start || name: agent || step: 1
+```
+
+Every frame is also a line on the host's `etrack` logger, rendered by the host's own structlog setup; e-track never
+configures logging.
+
+## The record
+
+| Field | What |
+|---|---|
+| `run_id`, `thread_id` | the run (32 hex, also the W3C trace id) and the conversation |
+| `seq`, `id`, `parent` | order within the run; the span and its visible parent |
+| `kind` | `run agent subagent node llm embedding retrieval tool mcp interrupt state evaluation custom` |
+| `phase` | `start delta end error instant` |
+| `part` | on deltas: `text reasoning tool_call image audio video file custom` |
+| `node`, `ns`, `step`, `visit` | graph coordinates: node, subgraph path, superstep, times the run entered the node |
+| `message_id`, `call_id` | the chat message and the tool call a client renders |
+| `model`, `usage`, `error` | typed sections: provider/name/params, tokens/cost, failure |
+| `payload`, `attributes` | what the span carried (redacted); the open, namespaced extension bag |
+
+Grow it by subclassing `RunEvent` and passing the subclass to `EventChannel(model=…)`; read it through an `EventView`.
+
+The full guide lives at [edamlabs.github.io/e-track](https://edamlabs.github.io/e-track/).
+
+## Development
+
+```bash
+make install        # sync deps + prek hooks
+make check          # lint + type + arch + validate + test
+make cov            # coverage gate: 100 % lines and branches, every outbound service faked in process
+make integration    # real services: the session fixtures bring sandbox/compose.yml up and down (collector + Phoenix)
+make ci             # every gate CI runs, in one command
+```
+
+Stack: uv · ruff · ty · tach · pytest (xdist, randomly, pytest-docker) · prek · zizmor · Zensical · Renovate.
+Released from a `v*` tag through PyPI trusted publishing; maintained by the [EDamLabs fleet](https://github.com/edamlabs/e-workbench).