fix(docs): give the README a Context section and write the architecture doc - #7
Merged
Merged
Conversation
…re doc The single most surprising fact about this repo was nowhere in it: dfe-engine imports logreducer at runtime and declares NO dependency on it, deliberately, in three lazy import sites inside the gated sampler modes. That is now the whole of "Where this sits", with the sites named. Also recorded, because all four are true and none was written down: nothing is deselected by default, so tests/integration/ is collected and then SKIPS without an endpoint or Docker; the version in the tree is a release behind the tag and PyPI; min_coverage gates at 75 while its own comment says 80; and vulture warns rather than fails. Verified against origin/main this pass: the three import sites read out of dfe-engine at sampling/service.py:200 and :236 and sampling/kafka_reader.py:134, with the non-declaration recorded at its pyproject.toml:114. Tag v3.5.0 against pyproject version 3.4.0, and PyPI serving 3.5.0 with 3.4.0 published 2026-07-03. Every Don't/Do/Why row traces to a comment in core.py, to CONTRIBUTING.md, or to open issue #5. Dropped "right now" from the CLI bullet while the file was open -- it was a DOC-TIME-1 finding and the next sentence already says it. Not verified: no test run. uv sync was not run and pytest was not run, so the commands are quoted from CONTRIBUTING.md, .hyperi-ci.yaml and pyproject.toml rather than from a run.
catinspace-au
force-pushed
the
fix/readme-context-section
branch
from
September 21, 2026 00:11
6fa5d69 to
dd17234
Compare
|
Released in v3.5.1 — https://github.com/hyperi-io/logreducer/releases/tag/v3.5.1 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The most surprising fact about this repo was nowhere in it. dfe-engine imports logreducer at RUNTIME and declares no dependency on it, deliberately, at three lazy import sites inside the gated
smartandanomalysampler modes. AnImportErrorthere becomes a message telling the caller to usemode=recentormode=random. That is now the whole of "Where this sits", with the sites named, because there is no version range for anyone to test against -- you install a new version alongside dfe-engine and run the tests that touch those three lines.What landed:
## Contextsection in the five fixed subheadings, below## Licenseand last in the file.hyperi-ai docs contextpasses.docs/architecture.mdis new -- the problem a random sample does not solve, why theSource/Sinkprotocols are the whole integration surface, why re-iterability is the contract that shapes every adapter, what streams and what cannot, why every sample is seeded, and eight invariants.Four things that were true and unwritten, now in the Context section:
addoptsis only-ra -q --strict-markers --strict-config, sotests/integration/is collected and then SKIPS without an endpoint or Docker. CI sets no env vars and always takes the docker path, so a green local run may have proved nothing about the adapters.pyproject.tomlandVERSIONsay 3.4.0, the newest tag is v3.5.0, PyPI serves 3.5.0.min_coverage: 75gates while its own comment says actual is 80.vultureis set towarn, because a library's public API reads as unused to dead-code analysis.Every Don't/Do/Why row traces to a comment in
core.py, to CONTRIBUTING.md, or to open issue #5. #5 gets a row of its own, since a consumer readingLogPattern.templatetoday gets a first-seen snapshot rather than the final Drain3 template.One thing that will date: dfe-engine's stated reason for not declaring the dependency is to pin it "once it hits public PyPI", and 3.4.0 was published there on 2026-07-03. The Context section says to expect that edge to become an ordinary pinned dependency. The change belongs in dfe-engine, not here.
NOT verified: no test run.
uv syncandpytestwere not run, so the commands are quoted from CONTRIBUTING.md,.hyperi-ci.yamlandpyproject.toml. CI on this PR runs the real suite --pull_requesthas no path filter here, so a docs-only PR gets the full gate.Done when this is merged and the README's
## Contextis the one place the working guide lives.