e-track 0.1.0__py3-none-any.whl

e_track-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,30 @@
+etrack/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+etrack/infra/errors.py,sha256=5y8598Gjr7QJRjE30D3nfPU99mtaGLnIPf6EnrbJbfo,2268
+etrack/infra/logger.py,sha256=-kq4KOrgUf29v_IoDBe15pP4mJTmu1QVEMUGd-spar4,501
+etrack/infra/proxy.py,sha256=pTtbMwNzAveoMcqOP7bRlR3ZUyPOG9ePjgBAZdBM0DQ,873
+etrack/infra/settings.py,sha256=sdpNnX-mMBWFuCig3cBS6bQxuIB2haRNTyKh4QqW3Mc,3310
+etrack/infra/config/base.py,sha256=9TDgJvFKICPVkAqjDFxEJ0mup9U-opYBVHrXliHqeTU,2752
+etrack/infra/config/providers/adapters/bus/anyio.py,sha256=53-FWEBVlS9pbAEH1B8rua-Pu6xFEN0H3cjyQiD3ab0,514
+etrack/infra/config/providers/adapters/sink/live.py,sha256=ucniO9_NuWwI9jrHTpy8gni635xeGtEYefAR7bVCvRQ,723
+etrack/infra/config/providers/drivers/sink/otlp.py,sha256=BAqyYhsboqnAXcqp8YHVTvhXcJFnh8gbOtbV2cmIXXA,1409
+etrack/logic/api.py,sha256=GcYq4gc6K2AIrVWsd7yookrfS4-5BEK_J7dSoJkS-Eg,2151
+etrack/logic/channel.py,sha256=zZupoTi4fkKOAIH27cM3tmFBNkQSu7izTbAzIpjMG5c,4667
+etrack/models/event.py,sha256=l_QbCQSh-_yeClykeSNbTgK1UX7FHBHCxqfJidVZyNA,5689
+etrack/ops/file.py,sha256=1-u3J2ZFcp4bmecEZZF-frr23p_-neTnalVala4gbTM,6357
+etrack/ops/w3c.py,sha256=mirEjgqnEqeGJm8FdV3dQ9x0ieCcKFyfHiNu1hL_j68,974
+etrack/ports/bus.py,sha256=C8-ZYTPQfbVkjyr4KvwYqhA3VCAK7tnzuhdG9XDeNrw,1098
+etrack/ports/provider.py,sha256=mLhLvvo8w2kPkJV1sVN6XwM4fQz15K5hMgCvjEFu9o8,1585
+etrack/ports/sink.py,sha256=vyliF9wSukcvSP4yWG76KGE_799H_truBAaCB8jKoek,843
+etrack/ports/source.py,sha256=kRwu6AommvEsitz7UYMXHzrndg1jUdYqi2aAK75vdgc,2106
+etrack/ports/topology.py,sha256=Bgup0N5qlpVVVX0WmQjR_rKvuGWDiox_11mEAEps3GQ,1486
+etrack/processors/fold.py,sha256=zwK2kRDdXXL0YVBCYJ15TNV3E4shd3F-9D1JnKGC9uo,6772
+etrack/processors/layout.py,sha256=os_kFac4dlpn2y1vvPFRTjhdGFD5OrJb8Um6_MaPYPs,4189
+etrack/providers/adapters/bus/anyio.py,sha256=0StV8PTYXzFslRRp9Kwh4idlpAaBTvTp-hk6EV4HaQ8,7015
+etrack/providers/adapters/sink/live.py,sha256=zu_BfS8jfmV3439Gq_caLTS1Hkyb5Um5RbXuLC4ST0k,5853
+etrack/providers/adapters/source/langgraph.py,sha256=Ya3Jwbx8vkOtYqqSkRTQBWtnae5eG7VObMyDZccACTc,18430
+etrack/providers/adapters/topology/langgraph.py,sha256=5CRW4pjLPvpjTfvm5_RRKrIb8Dr6-uRUKgWkkNPrS34,2653
+etrack/providers/drivers/sink/otlp.py,sha256=DT3NrlDhDYeBD9HbVQhhJcn90U7Ux2ROMyiwNZa9CvE,19480
+e_track-0.1.0.dist-info/METADATA,sha256=qw-tPWTyb4XkRxokW6KSh7PdaLnjfdmo8iEs8sQq3gA,7218
+e_track-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+e_track-0.1.0.dist-info/licenses/LICENSE,sha256=5qq3BchfBcDiZc2C600p0BtrFHNr_TD9JsmYyltgd0U,1065
+e_track-0.1.0.dist-info/RECORD,,

e_track-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

e_track-0.1.0.dist-info/licenses/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.

etrack/infra/config/base.py

@@ -0,0 +1,69 @@
+"""infra/config/base: pydantic-settings — frozen, typed, layered config.
+
+This module wires the five layers every scope shares: config file < secrets < .env < environment <
+kwargs. `Secret` is pydantic's `SecretStr`: masked through repr, str and f-strings, readable only
+via `.get_secret_value()`. All sub-settings inherit from here."""
+
+from typing import Final
+
+from pydantic import SecretStr
+from pydantic_settings import (
+    BaseSettings as SettingsBase,
+)
+from pydantic_settings import (
+    JsonConfigSettingsSource,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    TomlConfigSettingsSource,
+    YamlConfigSettingsSource,
+)
+
+Secret = SecretStr
+
+FILE_SOURCES: Final = (
+    ("toml_file", TomlConfigSettingsSource),
+    ("yaml_file", YamlConfigSettingsSource),
+    ("json_file", JsonConfigSettingsSource),
+)
+
+
+class BaseSettings(SettingsBase):
+    """Subclass and declare typed fields; the constructor merges every layer in one pass.
+
+    A scope narrows its own sources through ``model_config``: ``env_prefix``, ``env_file``,
+    ``toml_file`` / ``yaml_file`` / ``json_file``, ``secrets_dir`` (set ``/run/secrets`` there when
+    it is containerized — an absent default directory warns). Complex values in env or .env are
+    JSON-decoded; enums, paths and timedeltas validate on load, never at runtime."""
+
+    model_config = SettingsConfigDict(
+        frozen=True,
+        ### every scope reads the one shared .env: each takes its own keys and ignores the others' — forbidding
+        ### extras would make any foreign key (REDIS_URL, SECRET...) abort every other scope at load.
+        extra="ignore",
+        env_file=".env",
+        env_nested_delimiter="__",
+        nested_model_default_partial_update=True,
+    )
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[SettingsBase],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        ### pydantic-settings reads these first-to-highest: kwargs beat env, the config file is the floor.
+        return (
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            file_secret_settings,
+            *cls._settings_customise_files(settings_cls),
+        )
+
+    @staticmethod
+    def _settings_customise_files(settings_cls: type[SettingsBase]) -> tuple[PydanticBaseSettingsSource, ...]:
+        """The configured config-file sources only: absent format, absent source."""
+        return tuple(source(settings_cls) for key, source in FILE_SOURCES if settings_cls.model_config.get(key))

etrack/infra/config/providers/adapters/bus/anyio.py

@@ -0,0 +1,14 @@
+"""infra/config/providers/adapters/bus/anyio: how many events may wait for each sink before the next is dropped."""
+
+from pydantic import Field
+from pydantic_settings import SettingsConfigDict
+
+from etrack.infra.config.base import BaseSettings
+
+
+class AnyioSettings(BaseSettings):
+    """ETRACK_BUS_CAPACITY — events queued per sink; past it, a slow sink loses the newest and the drop is counted."""
+
+    model_config = SettingsConfigDict(env_prefix="ETRACK_BUS_")
+
+    capacity: int = Field(default=1000, ge=1)

etrack/infra/config/providers/adapters/sink/live.py

@@ -0,0 +1,17 @@
+"""infra/config/providers/adapters/sink/live: how much of each thread the live buffer keeps, for how many threads."""
+
+from pydantic import Field
+from pydantic_settings import SettingsConfigDict
+
+from etrack.infra.config.base import BaseSettings
+
+
+class LiveSettings(BaseSettings):
+    """ETRACK_LIVE_BUFFER — frames kept per thread for a reconnect to replay; ETRACK_LIVE_THREADS — threads kept, the
+    least recently written evicted first; ETRACK_LIVE_BACKLOG — frames a subscriber may lag before it is cut off."""
+
+    model_config = SettingsConfigDict(env_prefix="ETRACK_LIVE_")
+
+    buffer: int = Field(default=2000, ge=1)
+    threads: int = Field(default=256, ge=1)
+    backlog: int = Field(default=1000, ge=1)

etrack/infra/config/providers/drivers/sink/otlp.py

@@ -0,0 +1,34 @@
+"""infra/config/providers/drivers/sink/otlp: where spans and logs go over OTLP/HTTP, how fast, under which service."""
+
+from datetime import timedelta
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic_settings import SettingsConfigDict
+
+from etrack.infra.config.base import BaseSettings, Secret
+
+
+class OtlpTarget(BaseModel):
+    """One collector: its OTLP/HTTP base URL (signals under `/v1/traces`, `/v1/logs`) and the headers it authenticates."""
+
+    model_config = ConfigDict(frozen=True)
+
+    endpoint: str
+    headers: dict[str, Secret] = Field(default_factory=dict)
+
+
+class OtlpSettings(BaseSettings):
+    """ETRACK_OTLP_TARGETS — collectors by name as JSON (`{"langfuse": {"endpoint": …, "headers": {…}}}`; none: spans
+    are minted, never exported); ETRACK_OTLP_TRACES / ETRACK_OTLP_LOGS — which signals leave; ETRACK_OTLP_TIMEOUT —
+    per-export deadline; ETRACK_OTLP_FLUSH — how often a batch leaves; ETRACK_OTLP_SERVICE — `service.name`;
+    ETRACK_OTLP_ATTRIBUTES — extra resource attributes as JSON."""
+
+    model_config = SettingsConfigDict(env_prefix="ETRACK_OTLP_")
+
+    targets: dict[str, OtlpTarget] = Field(default_factory=dict)
+    traces: bool = True
+    logs: bool = False
+    timeout: timedelta = timedelta(seconds=10)
+    flush: timedelta = timedelta(seconds=1)
+    service: str = "etrack"
+    attributes: dict[str, str] = Field(default_factory=dict)

etrack/infra/errors.py

@@ -0,0 +1,67 @@
+"""infra/errors: the one root of every error — each layer imports its exceptions from here, none defines its own.
+
+`CoreError` is the root. One branch per kind of module: `ProviderError` (a provider failed at its border), `ProcessorError`,
+`LogicError` and `OpsError`. A provider fails as a **driver** (`DriverError`: a system outside the process) or as an
+**adapter** (`AdapterError`: a library inside it). A sink is met on both natures — the OTLP exporter over the wire,
+the live buffer in memory — so `SinkError` is honestly both."""
+
+
+##### ROOT #####
+class CoreError(Exception):
+    """All etrack exceptions inherit from this root."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+##### PROVIDERS #####
+class ProviderError(CoreError):
+    """A provider failed at its border: what a third-party library raised, or a call on a provider that is not open."""
+
+
+class DriverError(ProviderError):
+    """A system outside the process failed: unreachable, refusing, slow, or answering outside its contract."""
+
+
+class AdapterError(ProviderError):
+    """A library inside the process failed: it refused its input, or the provider it wraps is not open."""
+
+
+class SinkError(DriverError, AdapterError):
+    """A sink that is not open, or refused what it was sent."""
+
+
+class BusError(AdapterError):
+    """The bus is not open, or was asked to deliver through a closed stream."""
+
+
+class SourceError(AdapterError):
+    """A source that cannot bind a run: the host's config is not of the shape its framework takes."""
+
+
+##### PROCESSORS #####
+class ProcessorError(CoreError):
+    """A transformation refused its input."""
+
+
+class LayoutError(ProcessorError, ValueError):
+    """A topology that cannot be placed: an edge to a node it does not declare."""
+
+
+##### LOGIC #####
+class LogicError(CoreError):
+    """The library's core refused a call."""
+
+
+class ChannelError(LogicError, ValueError):
+    """An event the channel cannot validate against its model: a reserved key missing or of the wrong type."""
+
+
+##### OPS #####
+class OpsError(CoreError):
+    """An agnostic tool refused its input."""
+
+
+class FileError(OpsError, TypeError):
+    """A discovery target of a kind the finder does not sweep."""

etrack/infra/logger.py

@@ -0,0 +1,13 @@
+"""infra/logger: the library's own diagnostics — structlog's lazy logger, configured by the host, never by etrack.
+
+A library never calls `structlog.configure`: the application owns rendering, level and destination. `logger` is the
+named, lazy logger every etrack module writes its lifecycle and degraded paths to; its lines land wherever the host's
+configuration sends them."""
+
+from typing import Any, Final
+
+import structlog
+
+NAME: Final[str] = "etrack"
+
+logger: Any = structlog.get_logger(NAME)

etrack/infra/proxy.py

@@ -0,0 +1,24 @@
+"""infra/proxy: import-safe lazy singletons — the object exists at module level, its load runs on first use."""
+
+import functools
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+##### TYPES #####
+class LazyProxy[T]:
+    """Attribute access delegated to a `T` built exactly once per process, on first access.
+
+    The module body only constructs the proxy — no env, no secrets, no `.env`, no structlog at
+    import. `functools.cache` pins the build so the second touch reuses the first instance."""
+
+    __slots__ = ("_get",)
+
+    def __init__(self, build: Callable[[], T]) -> None:
+        self._get = functools.cache(build)
+
+    def __getattr__(self, name: str) -> Any:
+        ### only reached for names absent on the proxy itself: `_get` is a slot, so no recursion here.
+        return getattr(self._get(), name)

etrack/infra/settings.py

@@ -0,0 +1,70 @@
+"""infra/settings: the dynamic composer — every ``*Settings`` of ``infra/config``, merged into one nested ``Settings``.
+
+The config tree mirrors the module tree: ``infra/config/providers/drivers/database/psqlpy.py`` configures
+``providers/drivers/database/psqlpy.py``, and its settings are read at ``st.providers.drivers.database.psqlpy`` — the
+module path, the attribute chain and the module configured are one hierarchy. Scopes that serve no provider, engine or
+processor sit at the top (``st.app.env``). Each scope keeps its own sources (``env_prefix``, ``env_file``,
+``toml_file``, ``secrets_dir``), so adding a scope is just dropping a file in ``infra/config`` — ``base`` is the only
+thing skipped. Consumers import the lazy singleton: ``from etrack.infra.settings import settings as st`` →
+``st.crypto.alg`` (env, secrets and config files are read on that first access, never at import)."""
+
+import re
+from typing import Any, cast
+
+from pydantic import BaseModel, ConfigDict, create_model
+
+from etrack.infra.config.base import BaseSettings, Secret
+from etrack.infra.proxy import LazyProxy
+from etrack.ops.file import FileFinder
+
+__all__ = ["BaseSettings", "Secret", "Settings", "settings"]
+
+type Paths = dict[tuple[str, ...], type[BaseSettings]]
+
+_SETTINGS_RE = re.compile(r"^([A-Z]\w*)Settings$")
+_CONFIG = f"{__package__}.config"
+### derived from the package, never spelled: materialization rewrites imports, not strings (`etrack.infra` → `infra`).
+_SCOPES: Paths = {
+    tuple(cls.__module__.removeprefix(f"{_CONFIG}.").split(".")): cls
+    for cls in FileFinder(_CONFIG, skip=frozenset({"base"}), recursive=True)
+    .discover(BaseSettings, pattern=_SETTINGS_RE)
+    .values()
+}
+
+
+def _grow(name: str, scopes: Paths) -> type[BaseModel]:
+    """The model of a branch: one field per first path segment, a scope itself where the path ends there."""
+    heads = sorted({path[0] for path in scopes})
+    below = {head: {path[1:]: cls for path, cls in scopes.items() if path[0] == head} for head in heads}
+    fields: dict[str, Any] = {
+        head: ((rest[()] if () in rest else _grow(f"{name}{head.title()}", rest)), ...) for head, rest in below.items()
+    }
+    return create_model(name, __config__=ConfigDict(frozen=True), **fields)
+
+
+Settings: Any = _grow("Settings", _SCOPES)
+
+
+def _build(model: type[BaseModel], overrides: dict[str, Any]) -> Any:
+    """A branch built from its children, a scope from its own layers; an override dict reaches the scope it names."""
+    return (
+        model(**overrides)
+        if issubclass(model, BaseSettings)
+        else model(
+            **{
+                name: _build(cast("type[BaseModel]", field.annotation), overrides.get(name, {}))
+                for name, field in model.model_fields.items()
+            }
+        )
+    )
+
+
+def _load(cls: Any, **overrides: Any) -> Any:
+    """Build the composite: every scope reads its own layers; an override dict nested like the tree beats them."""
+    return _build(cls, overrides)
+
+
+### the parent constructor cannot honour per-scope sources or per-scope overrides: each scope loads itself.
+Settings.load = classmethod(_load)
+### no I/O at import: env, secrets and config files are read on the first attribute access, once per process.
+settings: LazyProxy[Any] = LazyProxy(lambda: _load(Settings))

etrack/logic/api.py

@@ -0,0 +1,50 @@
+"""logic/api: Tracker — the public surface: one run tracked from a host's config, its frames on the channel.
+
+`track(thread, config)` opens a run: a fresh `RunScope` (uuid7, the trace id too), a fold whose frames go to the
+channel, the source's hook bound into the host's config, and `run_id`/`thread_id` bound in structlog's contextvars
+for every log line of the block. The host runs its framework with the config it gets back; the `Tracked` it holds also
+reaches the fold for spans and facts of its own code (`tracked.fold.span(…)`, `tracked.fold.instant(…)`)."""
+
+import uuid
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import structlog
+
+from etrack.models.event import RunScope
+from etrack.processors.fold import FoldProcessor, Redact
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from etrack.logic.channel import EventChannel
+    from etrack.ports.source import SourcePort
+
+
+@dataclass(frozen=True, slots=True)
+class Tracked[C]:
+    """A run in progress: its scope, the host's config with the source bound, and the fold behind it."""
+
+    scope: RunScope
+    config: C
+    fold: FoldProcessor
+
+
+class Tracker[C]:
+    """Runs of one framework, tracked onto one channel; `redact` is the project's mask over every payload."""
+
+    __slots__ = ("_channel", "_redact", "_source")
+
+    def __init__(self, channel: EventChannel, source: SourcePort[C], redact: Redact | None = None) -> None:
+        self._channel = channel
+        self._source = source
+        self._redact = redact
+
+    @contextmanager
+    def track(self, thread: str, config: C, run_id: str | None = None) -> Generator[Tracked[C]]:
+        """One run on `thread`: the scope, the bound config and the fold, with the run's ids bound for the block."""
+        scope = RunScope(run_id=run_id or uuid.uuid7().hex, thread_id=thread)
+        fold = FoldProcessor(scope, self._channel.emit, self._redact)
+        with structlog.contextvars.bound_contextvars(run_id=scope.run_id, thread_id=scope.thread_id):
+            yield Tracked(scope=scope, config=self._source.bind(fold, scope, config), fold=fold)