python-neva 4.1.0__tar.gz → 5.0.0__tar.gz

{python_neva-4.1.0 → python_neva-5.0.0}/.gitlab-ci.yml

@@ -48,6 +48,15 @@ pyrefly:
   script:
     - uv run --frozen pyrefly check
 
+# The fragments shipped in the wheel cite the tests that prove their claims.
+# Every cited path must still resolve, so a behaviour change that leaves the
+# guidance behind fails here rather than reaching an agent as a wrong answer.
+guidelines:
+  extends: [.uv_base, .default_rules]
+  stage: code_qa
+  script:
+    - uv run --frozen neva-boost check neva/guidelines/fragments
+
 ##### Test #####
 pytest:
   extends: [.uv_base, .default_rules]

{python_neva-4.1.0 → python_neva-5.0.0}/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 5.0.0 (2026-09-01)
+
+### 💥 Boom
+
+- **obs**: drop OpenTelemetry and pyinstrument from the core
+
+### ✨ Features
+
+- **obs**: resolve logging through named channels
+- **deps**: offer neva-boost through the boost extra
+
+### 💚👷 CI & Build
+
+- **guidelines**: fail when a fragment cites a test that is gone
+
+### 📝💡 Documentation
+
+- **guidelines**: rule out resolving from the container in register()
+- **guidelines**: cover logging channels, and where OTel now lives
+
 ## 4.1.0 (2026-08-31)
 
 ### ✅🤡🧪 Tests

{python_neva-4.1.0 → python_neva-5.0.0}/PKG-INFO

@@ -1,21 +1,21 @@
 Metadata-Version: 2.5
 Name: python-neva
-Version: 4.1.0
+Version: 5.0.0
 Summary: Add your description here
 Requires-Python: >=3.12
 Requires-Dist: aiosqlite>=0.20.0
 Requires-Dist: asyncpg>=0.30.0
 Requires-Dist: cryptography>=46.0.3
 Requires-Dist: dishka>=1.10.0
-Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.62b0
 Requires-Dist: pwdlib[argon2,bcrypt]>=0.3.0
 Requires-Dist: pydantic>=2.7
-Requires-Dist: pyinstrument>=5.1.1
 Requires-Dist: sqlalchemy[asyncio]>=2.0.0
 Requires-Dist: structlog>=25.5.0
 Requires-Dist: typing-extensions>=4.13
 Provides-Extra: asgi
 Requires-Dist: neva-asgi>=0.1.1; extra == 'asgi'
+Provides-Extra: boost
+Requires-Dist: neva-boost>=0.2.1; extra == 'boost'
 Provides-Extra: fastapi
 Requires-Dist: neva-fastapi>=1.1.1; extra == 'fastapi'
 Provides-Extra: faststream
@@ -47,17 +47,59 @@ independent repo, independently versioned and published.
 
 | Package           | Repo / directory   | Role                                                                                  | Status                          |
 | ----------------- | ------------------ | ------------------------------------------------------------------------------------- | ------------------------------- |
-| `python-neva`     | `neva/`            | **Core, framework-agnostic.** DI, service providers, facades, Result/Option, events, security, observability, SQLAlchemy database layer. | published ([PyPI](https://pypi.org/project/python-neva/)) |
+| `python-neva`     | `neva/`            | **Core, framework-agnostic.** DI, service providers, facades, Result/Option, events, security, structured logging, SQLAlchemy database layer. | published ([PyPI](https://pypi.org/project/python-neva/)) |
 | `neva-fastapi`    | `neva-fastapi/`    | FastAPI integration — `App` extends `FastAPI` and wires dishka into routes. Pulled in via the `python-neva[fastapi]` extra. | published ([PyPI](https://pypi.org/project/neva-fastapi/)) |
 | `neva-asgi`       | `neva-asgi/`       | **ASGI middleware** — correlation IDs and per-request profiling. Pure ASGI, so both the HTTP and messaging integrations can consume it. Pulled in via the `python-neva[asgi]` extra. | published ([PyPI](https://pypi.org/project/neva-asgi/)) |
 | `neva-faststream` | `neva-faststream/` | FastStream (messaging) integration.                                                   | scaffolded, early placeholder   |
 | `neva-auth`       | `neva-auth/`       | Authentication & identity toolkit — token-issuance engine, OAuth2 grants, guards, pluggable formats/backends. | core complete, OAuth-server slice in progress |
+| `neva-otel`       | `neva-otel/`       | **OpenTelemetry** — SDK wiring, tracer and meter providers, exporters, samplers and instrumentors. Kept out of the core so nothing is committed to an observability backend. | planned |
+| `neva-boost`      | `neva-boost/`      | **Agent guidelines** — composes each installed package's versioned guideline fragments into a project's agent configuration (Claude Code skills or `AGENTS.md`). Dev-time tooling; pulled in via the `python-neva[boost]` extra. | published ([PyPI](https://pypi.org/project/neva-boost/)) |
 | `neva-example`    | `neva-example/`    | Reference application consuming `python-neva[fastapi]`. Not published; demonstration + integration test bed. | unpublished                     |
 
 > When working across packages locally, each repo can be cloned as a sibling
 > directory; integration packages depend on `python-neva` from PyPI (or an
 > editable local path during development).
 
+## Logging
+
+Logging is a set of named channels, each with its own driver, level and output —
+Laravel's `Log`, configured from one `config/obs.py` namespace.
+
+```python
+config = {
+    "logging": {
+        "default": "stdout",
+        "channels": {
+            "stdout": {"driver": "console", "level": "DEBUG"},
+            "json":   {"driver": "json", "stream": "stderr", "level": "INFO"},
+            "audit":  {"driver": "file", "path": "var/audit.log"},
+            "both":   {"driver": "stack", "channels": ["json", "audit"]},
+        },
+    },
+}
+```
+
+```python
+from neva.support.facade import Log
+
+Log.info("order placed", order_id=42)                    # default channel
+Log.channel("audit").warning("role granted", actor="root")
+Log.bind(tenant="acme")                                  # every channel, this context
+```
+
+Drivers are `console`, `json`, `file`, `stack` and `null`. With no `config/obs.py`
+at all, logging still works: a console channel on stdout at `DEBUG`.
+
+Each channel carries its own structlog processor chain rather than going through
+the process-global `structlog.configure()`, so one application's renderer cannot
+leak into another in the same interpreter. `LogManager.processor(fn)` lets a
+plugin add a processor to every chain — the seam `neva-otel` uses to put the
+current span's ids on every record.
+
+**Tracing and metrics are deliberately not here.** They live in `neva-otel`, so
+the core carries no OpenTelemetry dependency and commits no application to an
+observability backend.
+
 ## Develop
 
 ```bash
@@ -103,10 +145,9 @@ rewrite the new tag with the rendered changelog as its annotation.
 ## Feature ideas
 
 - Feature-parity FastStream integration (now scaffolded as `neva-faststream`)
-- Finish cleaning up the core package (moving any remaining ASGI-dependent code into the appropriate integration packages)
 - Improved router registration (auto-discovery OR provider-based? both?)
 - Improved security tooling (performance improvements, better defaults, etc.)
-- Better OpenTelemetry integration
+- OpenTelemetry as a plugin (`neva-otel`) — the core keeps logging and takes no OTel dependency
 - Improved factory module (based on Polyfactory)
 - Queue/Jobs system
 - CLI integration

{python_neva-4.1.0 → python_neva-5.0.0}/README.md

@@ -18,17 +18,59 @@ independent repo, independently versioned and published.
 
 | Package           | Repo / directory   | Role                                                                                  | Status                          |
 | ----------------- | ------------------ | ------------------------------------------------------------------------------------- | ------------------------------- |
-| `python-neva`     | `neva/`            | **Core, framework-agnostic.** DI, service providers, facades, Result/Option, events, security, observability, SQLAlchemy database layer. | published ([PyPI](https://pypi.org/project/python-neva/)) |
+| `python-neva`     | `neva/`            | **Core, framework-agnostic.** DI, service providers, facades, Result/Option, events, security, structured logging, SQLAlchemy database layer. | published ([PyPI](https://pypi.org/project/python-neva/)) |
 | `neva-fastapi`    | `neva-fastapi/`    | FastAPI integration — `App` extends `FastAPI` and wires dishka into routes. Pulled in via the `python-neva[fastapi]` extra. | published ([PyPI](https://pypi.org/project/neva-fastapi/)) |
 | `neva-asgi`       | `neva-asgi/`       | **ASGI middleware** — correlation IDs and per-request profiling. Pure ASGI, so both the HTTP and messaging integrations can consume it. Pulled in via the `python-neva[asgi]` extra. | published ([PyPI](https://pypi.org/project/neva-asgi/)) |
 | `neva-faststream` | `neva-faststream/` | FastStream (messaging) integration.                                                   | scaffolded, early placeholder   |
 | `neva-auth`       | `neva-auth/`       | Authentication & identity toolkit — token-issuance engine, OAuth2 grants, guards, pluggable formats/backends. | core complete, OAuth-server slice in progress |
+| `neva-otel`       | `neva-otel/`       | **OpenTelemetry** — SDK wiring, tracer and meter providers, exporters, samplers and instrumentors. Kept out of the core so nothing is committed to an observability backend. | planned |
+| `neva-boost`      | `neva-boost/`      | **Agent guidelines** — composes each installed package's versioned guideline fragments into a project's agent configuration (Claude Code skills or `AGENTS.md`). Dev-time tooling; pulled in via the `python-neva[boost]` extra. | published ([PyPI](https://pypi.org/project/neva-boost/)) |
 | `neva-example`    | `neva-example/`    | Reference application consuming `python-neva[fastapi]`. Not published; demonstration + integration test bed. | unpublished                     |
 
 > When working across packages locally, each repo can be cloned as a sibling
 > directory; integration packages depend on `python-neva` from PyPI (or an
 > editable local path during development).
 
+## Logging
+
+Logging is a set of named channels, each with its own driver, level and output —
+Laravel's `Log`, configured from one `config/obs.py` namespace.
+
+```python
+config = {
+    "logging": {
+        "default": "stdout",
+        "channels": {
+            "stdout": {"driver": "console", "level": "DEBUG"},
+            "json":   {"driver": "json", "stream": "stderr", "level": "INFO"},
+            "audit":  {"driver": "file", "path": "var/audit.log"},
+            "both":   {"driver": "stack", "channels": ["json", "audit"]},
+        },
+    },
+}
+```
+
+```python
+from neva.support.facade import Log
+
+Log.info("order placed", order_id=42)                    # default channel
+Log.channel("audit").warning("role granted", actor="root")
+Log.bind(tenant="acme")                                  # every channel, this context
+```
+
+Drivers are `console`, `json`, `file`, `stack` and `null`. With no `config/obs.py`
+at all, logging still works: a console channel on stdout at `DEBUG`.
+
+Each channel carries its own structlog processor chain rather than going through
+the process-global `structlog.configure()`, so one application's renderer cannot
+leak into another in the same interpreter. `LogManager.processor(fn)` lets a
+plugin add a processor to every chain — the seam `neva-otel` uses to put the
+current span's ids on every record.
+
+**Tracing and metrics are deliberately not here.** They live in `neva-otel`, so
+the core carries no OpenTelemetry dependency and commits no application to an
+observability backend.
+
 ## Develop
 
 ```bash
@@ -74,10 +116,9 @@ rewrite the new tag with the rendered changelog as its annotation.
 ## Feature ideas
 
 - Feature-parity FastStream integration (now scaffolded as `neva-faststream`)
-- Finish cleaning up the core package (moving any remaining ASGI-dependent code into the appropriate integration packages)
 - Improved router registration (auto-discovery OR provider-based? both?)
 - Improved security tooling (performance improvements, better defaults, etc.)
-- Better OpenTelemetry integration
+- OpenTelemetry as a plugin (`neva-otel`) — the core keeps logging and takes no OTel dependency
 - Improved factory module (based on Polyfactory)
 - Queue/Jobs system
 - CLI integration

{python_neva-4.1.0 → python_neva-5.0.0}/neva/database/manager.py

@@ -10,7 +10,6 @@ from neva.database.config import ConnectionConfig
 from neva.database.connection import ConnectionManager, TransactionContext
 from neva.database.transaction import BoundTransaction
 from neva.obs import LogManager
-from neva.obs.instrumentation.sqlalchemy import instrument
 from neva.support import Nothing, Option, Some, from_optional
 
 
@@ -36,7 +35,6 @@ class DatabaseManager:
             name: The connection name.
             engine: The async engine.
         """
-        instrument(engine)
         self._connections[name] = ConnectionManager(
             name,
             self._tx_context,

python_neva-5.0.0/neva/guidelines/fragments/observability.md

@@ -0,0 +1,116 @@
+---
+id: observability
+title: Observability
+requires: python-neva>=5.0
+triggers: [logging, Log facade, log channel, structured logging, log level, JSON logs, audit log, obs config, tracing, OpenTelemetry, metrics, correlation id]
+priority: 55
+verified_by: [tests/obs/test_channels.py, tests/obs/test_resolver.py, tests/obs/test_manager.py, tests/obs/test_facade.py, tests/obs/test_provider_hook.py]
+---
+
+# Observability
+
+The core ships **logging only**. Tracing, metrics, exporters and instrumentors live in a
+separate plugin, so installing the core commits an application to no observability backend.
+There is no `Trace` facade, no tracer, and no OpenTelemetry dependency here — do not add one.
+
+## Channels
+
+Logging is a set of named channels, each with its own driver, level and output. One
+`config/obs.py` namespace configures them.
+
+```python
+config = {
+    "logging": {
+        "default": "stdout",
+        "channels": {
+            "stdout": {"driver": "console", "level": "DEBUG"},
+            "json":   {"driver": "json", "stream": "stderr", "level": "INFO"},
+            "audit":  {"driver": "file", "path": "var/audit.log"},
+            "both":   {"driver": "stack", "channels": ["json", "audit"]},
+            "quiet":  {"driver": "null"},
+        },
+    },
+}
+```
+
+| Driver | Writes | Driver-specific keys |
+| --- | --- | --- |
+| `console` | human-readable, to a stream | `stream` |
+| `json` | one JSON object per line, to a stream | `stream` |
+| `file` | JSON lines appended to a path | `path` (required) |
+| `stack` | fans one record out to other channels | `channels` (required) |
+| `null` | nothing | — |
+
+`level` is one of `DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL`, default `DEBUG`. `stream` is
+`stdout` (default) or `stderr`. A `file` channel creates parent directories and holds its
+handle open for the process's life.
+
+**With no `config/obs.py` at all**, logging still works: a `console` channel named `stdout` on
+stdout at `DEBUG`.
+
+## Writing
+
+```python
+from neva.support.facade import Log
+
+Log.info("order placed", order_id=42)      # default channel
+Log.channel("audit").warning("role granted", actor="root")
+```
+
+Level methods go to the default channel. Everything after the message is structured context,
+not format arguments — never build the message with an f-string when the value belongs in a
+field.
+
+`Log.channel(name)` **raises** on a name no channel is configured for, carrying the reason.
+A typo is a configuration mistake, and serving the default instead would hide it behind
+working output. Where the failure has to be a value, `Log.channels` gives the resolver and
+`use(name)` returns `Result`.
+
+## Ambient context
+
+```python
+Log.bind(tenant="acme")     # every subsequent record in this context, every channel
+Log.unbind("tenant")
+```
+
+Backed by structlog's contextvars, so a binding follows the async task rather than the
+channel. This is how a request's correlation ID reaches log lines without being passed
+around — `neva-asgi`'s middleware binds it the same way.
+
+## Enriching records from a plugin
+
+`LogManager.processor(fn)` appends a structlog processor to **every** channel's chain. This is
+the seam a plugin adds derived fields through — the OpenTelemetry plugin injects the current
+span's ids this way.
+
+```python
+class MyProvider(ServiceProvider):
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        manager = (await self.app.make_async(LogManager)).unwrap()
+        _ = manager.processor(add_my_field)
+        yield
+```
+
+**Call it from `lifespan()`, never from `register()`.** Resolving anything during
+registration hands back an instance the booted application does not use, so a processor
+registered there silently never runs. See the service-providers fragment.
+
+Records emitted by base providers' own startup are not enriched — their lifespans run before
+a plugin's. Everything after is. Already-built channels are discarded on registration, so the
+next resolution picks the processor up.
+
+Custom drivers register the same way, through `resolver.driver(name, builder)`.
+
+## Rules
+
+- **Never call `structlog.configure()`.** It is process-global; channels carry their own
+  chains precisely so one application's renderer cannot leak into another in the same
+  interpreter. Configuring it globally breaks that isolation and every channel's level.
+- **`merge_contextvars` must lead every chain.** A custom driver that omits it silently drops
+  the correlation ID from every line it renders.
+- **A broken default channel fails at boot**, not at the first log call — the framework logs
+  during provider startup, so a `file` channel with no `path` surfaces there. The error names
+  the channel and the reason.
+- `LogManager()` with no application is legitimate and serves one console channel; it is what
+  a test needing somewhere for records to go should use.

{python_neva-4.1.0 → python_neva-5.0.0}/neva/guidelines/fragments/service-providers.md

@@ -4,7 +4,7 @@ title: Service providers and bindings
 requires: python-neva>=4.0
 triggers: [registering a service, binding a dependency, provider.py, wiring a component, DI container, resolving a type]
 priority: 20
-verified_by: [tests/arch/test_lifetimes.py, tests/arch/test_registration.py, tests/arch/test_cache.py, tests/arch/test_scope.py, tests/arch/test_extends.py]
+verified_by: [tests/arch/test_lifetimes.py, tests/arch/test_registration.py, tests/arch/test_cache.py, tests/arch/test_scope.py, tests/arch/test_extends.py, tests/arch/test_register_resolution.py]
 ---
 
 # Service providers and bindings
@@ -28,6 +28,36 @@ class ActorServiceProvider(ServiceProvider):
 `register()` returns `Ok(self)`, or `Err("...")` to abort boot with a message. Bind only — no
 I/O, no connections. Startup work goes in `lifespan()`.
 
+## Never resolve in register()
+
+`register()` **declares**; `lifespan()` **uses**. Calling `make()` or `make_async()` during
+registration cannot work, and fails in one of two ways depending on who bound the type:
+
+| Resolving | Outcome |
+| --- | --- |
+| A type **this provider** binds | `Err` — a provider joins the graph only once `register()` has returned, so its own bindings are not there yet. |
+| A type **another provider** bound | Succeeds, then is **orphaned**. Resolving builds the container early; a successful registration discards it, so the booted application serves a *different* instance. |
+
+The second is the dangerous one: nothing raises, nothing logs, and the object looks right. A
+provider that configures a manager this way — adding a log processor, registering a driver —
+silently configures a throwaway.
+
+```python
+def register(self) -> Result[Self, str]:
+    manager = self.app.make(SomeManager).unwrap()   # WRONG: discarded instance
+    manager.configure(...)                          # silently affects nothing
+    return Ok(self)
+
+@asynccontextmanager
+async def lifespan(self) -> AsyncIterator[None]:
+    manager = (await self.app.make_async(SomeManager)).unwrap()   # the real one
+    manager.configure(...)
+    yield
+```
+
+Needing another service in order to *bind* is a sign the binding wants a factory function
+taking it as a parameter — let the container inject it, rather than reaching for it.
+
 ## A lifetime is mandatory
 
 Bare `bind()` with neither `scope` nor `cache` **raises `TypeError`** since 4.0. Use the named
@@ -111,4 +141,6 @@ catches typos before boot. Each package declares the shape for the keys it reads
 - A provider absent from the `providers` config never boots, and nothing says so.
 - Resolution is by **type**. There are no string keys; for two implementations of one interface
   use distinct types or markers.
-- `register()` must be pure binding. Connections belong in `lifespan()`.
+- `register()` must be pure binding. Connections **and any `make()` call** belong in
+  `lifespan()` — see above; resolving during registration silently yields a discarded
+  instance.

python_neva-5.0.0/neva/obs/__init__.py

@@ -0,0 +1,19 @@
+"""Observability tooling.
+
+Logging only: tracing, metrics and their exporters live in the `neva-otel`
+plugin, so the core commits no application to an observability backend.
+"""
+
+from neva.obs.config import ChannelConfig, LoggingConfig, ObsConfig
+from neva.obs.logging import Channel, ChannelResolver, LogManager, LogServiceProvider
+
+
+__all__ = [
+    "Channel",
+    "ChannelConfig",
+    "ChannelResolver",
+    "LogManager",
+    "LogServiceProvider",
+    "LoggingConfig",
+    "ObsConfig",
+]

python_neva-5.0.0/neva/obs/config.py

@@ -0,0 +1,37 @@
+"""Observability configs."""
+
+from typing import Literal, NotRequired, TypedDict
+
+
+LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+ChannelDriver = Literal["console", "json", "file", "stack", "null"]
+Stream = Literal["stdout", "stderr"]
+
+
+class ChannelConfig(TypedDict):
+    """Configuration for a single log channel.
+
+    Three keys are driver-specific and carry no meaning elsewhere: `stream`
+    belongs to `console` and `json`, `path` to `file`, and `channels` to
+    `stack`. A `file` channel without `path`, or a `stack` without `channels`,
+    fails to resolve rather than logging nowhere.
+    """
+
+    driver: ChannelDriver
+    level: NotRequired[LogLevel]
+    stream: NotRequired[Stream]
+    path: NotRequired[str]
+    channels: NotRequired[list[str]]
+
+
+class LoggingConfig(TypedDict):
+    """Logging config."""
+
+    default: NotRequired[str]
+    channels: NotRequired[dict[str, ChannelConfig]]
+
+
+class ObsConfig(TypedDict):
+    """Observability config."""
+
+    logging: NotRequired[LoggingConfig]

python_neva-5.0.0/neva/obs/logging/__init__.py

@@ -0,0 +1,22 @@
+"""Logging module.
+
+Structured logging over structlog, shaped as named channels resolved from
+configuration, reached through the `Log` facade.
+"""
+
+from neva.obs.logging.channels import NullChannel, StackChannel
+from neva.obs.logging.contracts import Channel, Processor
+from neva.obs.logging.manager import LogManager
+from neva.obs.logging.provider import LogServiceProvider
+from neva.obs.logging.resolver import ChannelResolver
+
+
+__all__ = [
+    "Channel",
+    "ChannelResolver",
+    "LogManager",
+    "LogServiceProvider",
+    "NullChannel",
+    "Processor",
+    "StackChannel",
+]