diff --git a/.claude/skills/add-feature/SKILL.md b/.claude/skills/add-feature/SKILL.md index e5ac66c..3771d5e 100644 --- a/.claude/skills/add-feature/SKILL.md +++ b/.claude/skills/add-feature/SKILL.md @@ -67,19 +67,23 @@ if data is None: # Can this actually be None here? ## InsightWeaver Patterns -### Async Operations +### Source adapters are async; everything after ingestion is not ```python -async def fetch_and_process(): - data = await collector.fetch() # Await external calls - return process(data) # Sync processing is fine +class MyAdapter: # src/sources/base.py describes the contract + async def fetch(self, since): # raise SourceUnavailable; never return [] for an error + ... ``` -### Claude API Integration +### The one model call (2026-09-22, backlog task 029) ```python -# Always handle markdown-wrapped JSON -response = await client.analyze(prompt) -# Parser handles: ```json {...} ``` and raw JSON -data = parse_claude_response(response) +from src.llm.claude_client import ClaudeClient, ModelCallFailed + +client = ClaudeClient("triage") # key from the OS keychain; every request audited +response = client.analyze(system, user, effort="medium", output_schema=SCHEMA) +# response.text is JSON constrained by SCHEMA; validate it with pydantic anyway. +# ModelCallFailed.outcome is "answered", "rejected" or "unavailable"; only an +# answered failure is a fact about the pair. src/evidence/claude_adjudicator.py +# is the only caller and should stay the only one. ``` ### Database Operations diff --git a/.claude/skills/onboard/SKILL.md b/.claude/skills/onboard/SKILL.md new file mode 100644 index 0000000..2c88e7c --- /dev/null +++ b/.claude/skills/onboard/SKILL.md @@ -0,0 +1,96 @@ +--- +name: onboard +description: Interview the operator for the decisions they are carrying and the claims they want watched, transcribe the answers into position.yaml and watches.yaml in the private directory, validate them, and run `insightweaver watch sync`. Use on first setup, when a decision is added or closed, or when the operator asks to review the Position. +allowed-tools: Read, Write, Bash(insightweaver:*), Bash(ls:*), Bash(cat:*), Bash(diff:*), Bash(mkdir:*), Bash(python:*) +--- + +# Onboard + +You are transcribing, not authoring. Every decision, deadline, stake, claim, belief, trigger +word, expiry and staleness window in the files you write is something the operator said in this +conversation and heard read back. If an answer is missing, ask; if it is vague, ask for the +concrete form; never fill a field yourself. This is invariant 6 of `docs/CONCEPTS.md`, the system +never authors its own watches, applied to the one place where it is easiest to break: a drafting +interview is one helpful suggestion away from being a generator. + +The files are private. They name real decisions and real deadlines. They live outside the +repository at `POSITION_PATH` and `WATCHES_PATH` (default `~/.config/insightweaver/`), ideally +under git in the operator's private repo, because a review's value is the diff. This +repository's `.gitignore` refuses `position.yaml` and `watches.yaml` at the root and under +`config/`. Do not write them anywhere under the checkout. + +## 1. Find what exists + +```bash +insightweaver watch list +ls -la ~/.config/insightweaver/ 2>/dev/null +echo "POSITION_PATH=$POSITION_PATH WATCHES_PATH=$WATCHES_PATH" +``` + +If a Position exists, read it and start from it: show each decision and ask whether it is still +live, closed, or changed. If none exists, say so and start the interview. Read +`config/position.example.yaml` and `config/watches.example.yaml` once for the exact field names +and the trigger rules; the loaders reject any field that is missing or malformed, and default +nothing. + +## 2. Decisions + +A decision is something the operator will do or not do by a date. Ask, one at a time, and stop +when the operator says there are no more: + +1. What is the decision? (`name`: one sentence they could act on.) +2. By when? (`deadline`: a date. A decision with no date is an interest, and the loader refuses + it; do not invent one and do not accept "soon".) +3. What is at stake if it goes the wrong way? (`stake`: their words, one or two sentences.) +4. A short key for it (`key`: a slug such as `renew-authorization`; propose one built from + their words and let them confirm). + +Read the list back. Then set `reviewed` to today's date and `version: 1`. If the file +runs past two pages the loader warns; that is drift from stakes into interests, so ask which +decisions are really dated before writing more. + +## 3. Watches + +For each decision, ask: what would you want to know before that date that would change what you +do? Each answer that is a claim about the world becomes one watch. Ask the fields in this order +and write down the answers verbatim: + +1. `claim`: the thing that is or is not true, phrased so that afterwards they could say which. + If the answer is a topic ("FedRAMP changes"), ask for the claim inside it. +2. `belief`: their probability now, 0.0 to 1.0. Do not suggest a number. +3. `so_what.because`: what changes for the decision if the claim resolves. +4. `triggers`: the words, names and sources that would appear in a document that bears on the + claim. Explain the rule once: a trigger is a list of clauses; within a clause every populated + field must match and any listed value will do; across clauses any one firing is enough; + `terms` and `entities` match whole words, an all-caps term matches case-sensitively, `sources` + must equal a registered source name exactly (case aside): the `name` fields in + `config/feeds/*.json`, or `Federal Register - Documents API`. The loader does not check + source names, so check them yourself against those files before writing; a misspelt name is + a clause that never fires and no command will say so. Ask for the actual words. A trigger + that cannot be compiled never fires, so do not accept a sentence. +5. `expires`: when the question stops mattering, usually on or before the decision's deadline. +6. `staleness_alert_days`: after how many days of nothing routed the silence should be reported. + +A watch serves exactly one decision (`so_what.decision` is that decision's key). Give each an +`id` slug built from the claim and confirmed by the operator. + +## 4. Write, validate, sync + +Write both files with the exact structure of the example files. If a file already exists, show +`diff` against the new content and ask before replacing it. Then: + +```bash +insightweaver watch sync +insightweaver watch list +``` + +`watch sync` validates both files together and refuses the whole set if any field is missing or +malformed (it does not check source names; see step 3); fix what it names and run it again. Do not work around a refusal by changing what the operator said +without asking them. When it succeeds, tell the operator what was added, updated or retired, and +that `insightweaver run` is the morning command. + +## What this skill does not do + +It does not rank decisions, suggest beliefs, propose claims the operator did not state, or write +a watch for a decision the operator did not connect it to. It does not run `ingest`, `route` or +`adjudicate`. It does not touch the database except through `watch sync`. diff --git a/.claude/skills/review-tests/SKILL.md b/.claude/skills/review-tests/SKILL.md index d6a5c6e..4ac3cfb 100644 --- a/.claude/skills/review-tests/SKILL.md +++ b/.claude/skills/review-tests/SKILL.md @@ -15,125 +15,115 @@ Review tests to ensure they describe behaviors, not implementations. ### Good Test Characteristics 1. **Describes behavior, not methods** - - Test name: `test_citation_map_overrides_claude_response` (behavior) - - Not: `test_build_synthesis_task_with_citations_returns_tuple` (implementation) - -2. **Decoupled from implementation details** - - Test the contract, not the internals - - If refactoring breaks tests but not behavior, tests are too coupled - -3. **Follows Arrange-Act-Assert structure** - ```python - # Arrange: Set up preconditions - articles = [{"id": 1, "title": "Test"}] - - # Act: Execute the behavior - result = await synthesizer.synthesize() - - # Assert: Verify outcomes - assert result["status"] == "success" - ``` - -4. **Tests at boundaries, not internals** - - Public API boundaries - - Integration points (database, external APIs) - - Error boundaries - -5. **Meaningful assertions** - - Assert on outcomes users care about - - Not: `assert mock.called` (verifies plumbing) - - Yes: `assert result["citation_map"]["1"]["title"] == "Expected Title"` (verifies value) + - Test name: `test_a_second_run_asks_nothing` (behavior: idempotency) + - Not: `test_pending_pairs_calls_query_filter` (implementation) + +2. **Can actually fail** + - A test earns its place only if a plausible bug turns it red. + - `tests/routing/test_regression.py` plants exactly 20 whole-word matches + among 1000 observations and 100 look-alikes, then asserts on the + identity of the routed set, not just a count -- a routing predicate + that is too loose bills real model calls, so the test is pinned with a + number and was verified to fail (61 routed) when the word-boundary + anchors were emptied out. + - `tests/brief/test_select.py` inserts rows out of the order the brief + must print them (`test_clusters_and_citations_are_ordered_by_date_before_hash` + even gives the earlier observation the *larger* hash in both pairs), so + a missing or wrong `ORDER BY` fails the test instead of passing by + accident. + +3. **No tautologies** + - Don't assert that a mock returned what you told it to return. + - Assert on what the code under test *did* with that input: what it + wrote, what it computed, what it left alone. + - `tests/position/test_ledger.py::test_only_sync_and_the_two_commands_write_belief_or_resolution` + is the extreme version of this: instead of trusting that every call + site remembers to go through `record_belief`/`resolve_watch`, it scans + every file under `src/` for the patterns that would write to the + ledger and asserts the only matches are the three allowed writers, by + name. + +4. **Mocks only at the boundary** + - Mock the external boundary (the model API, the network), never an + internal method of the unit under test. + - `tests/evidence/test_adjudicate.py`'s `FakeClient` stands in for the + Claude API client itself -- the one seam that would otherwise cost + money and require a key -- and returns scripted `ModelResponse` or + raises a scripted `ModelCallFailed`. Everything downstream (routing, + the adjudicator, the ledger writes) is the real code. + - `tests/sources/test_runner.py`'s `FakeAdapter` plays the same role for + a source: it returns a scripted list of items, an empty list, or + raises `SourceUnavailable`, and the runner, the silence watchdog and + the database writes are all real. + - `tests/brief/test_end_to_end.py` goes one boundary further: it patches + `get_db` to yield one shared test session and patches the HTTP layer + under each adapter, then runs the real CLI commands (`watch sync`, + `ingest`, `route`, `adjudicate`, `brief`) end to end and compares the + rendered bytes against a committed golden file. ## Red Flags -- Test names that mirror method names exactly -- Assertions that only check mock call counts -- Tests that break when implementation changes but behavior doesn't -- Heavy use of `mock.assert_called_with()` on internal methods -- Tests that require knowing private method signatures -- Excessive mocking of the unit under test - -## InsightWeaver-Specific Patterns - -### Async Tests -```python -@pytest.mark.asyncio -async def test_synthesis_produces_valid_output(self, mock_curator, mock_client): - # Arrange - mock_curator.curate.return_value = {"articles": sample_articles} - mock_client.analyze.return_value = valid_response_json - - # Act - result = await synthesizer.synthesize_with_trust_verification() - - # Assert on behavior - assert result["status"] == "success" - assert "citation_map" in result["synthesis_data"]["metadata"] -``` - -### Mocking External Services -Mock at the boundary (Claude API, database), not internal methods: -```python -# Good: Mock the external boundary -mock_client.analyze_with_context = AsyncMock(return_value=response) - -# Bad: Mock internal helper methods -mock_synthesizer._parse_synthesis_response = MagicMock() -``` - -### Testing Error Handling -Test that errors produce correct outcomes, not that specific exceptions flow: -```python -# Good: Behavior when API fails -async def test_synthesis_handles_api_failure_gracefully(): - mock_client.analyze.side_effect = Exception("API Error") - result = await synthesizer.synthesize() - assert result["status"] == "error" # Behavior - -# Bad: Testing exception plumbing -async def test_api_exception_propagates(): - mock_client.analyze.side_effect = APIError() - with pytest.raises(APIError): # Implementation detail - await synthesizer.synthesize() -``` +- Test names that mirror method or function names exactly +- Assertions that only check a mock's call count (`mock.assert_called_once()` + with nothing about what it produced) +- Tests that would still pass if the feature were deleted +- A test that asserts a value it just told a stub to return +- Mocking an internal function of the module under test rather than the + true external boundary (an LLM client, the network, the database engine) +- A clock read from the wall in a test that asserts on dates or ordering + (see `frozen_clock` in `tests/brief/test_end_to_end.py`, which replaces + the `datetime` class `src.utils.utcnow` reads) ## Review Checklist -When reviewing tests, ask: - -- [ ] Does the test name describe a behavior or outcome? -- [ ] Would this test break if I refactored without changing behavior? -- [ ] Am I testing what users/callers care about? -- [ ] Are assertions on outcomes rather than call patterns? -- [ ] Is mocking limited to true external boundaries? -- [ ] Can I understand what the code does just from reading tests? +When reviewing a test, ask: + +- [ ] Does the test name describe a behavior or outcome, not a method call? +- [ ] Is there a concrete bug that would turn this test red? (If you can't + name one, the test may be a tautology.) +- [ ] Are assertions on outcomes -- what got written, computed, or + rendered -- rather than on call patterns? +- [ ] Is mocking limited to a true external boundary (model client, + network, wall clock), with everything else real? +- [ ] Would this test survive a refactor that kept behavior the same but + changed internals (renamed a private function, changed a return + type)? +- [ ] If the test is about ordering or a threshold, is it exercised with + data that would expose a wrong sort or an off-by-one (both sides of + the boundary, not just one)? ## Questions to Ask -1. "If I renamed a private method, would this test break?" -2. "Does this test tell me what the feature does?" -3. "Am I testing the contract or the implementation?" -4. "Would a user of this code care about what I'm asserting?" +1. "If I renamed a private function, would this test break?" +2. "What real defect would this test catch?" +3. "Am I testing the contract (what the caller observes) or the internals?" +4. "Is every mock here standing in for the network, the model, or the + clock -- or did I mock something inside the unit under test?" ## Example Transformation -**Before (implementation-coupled):** +**Before (tautological, mock-verification only):** ```python -def test_build_synthesis_task_with_citations_returns_tuple(): - result = synthesizer._build_synthesis_task_with_citations(articles, 2) - assert isinstance(result, tuple) - assert len(result) == 2 +def test_run_calls_the_client(): + client = FakeClient(_verdict()) + run(corpus, ClaudeAdjudicator(client)) + assert client.calls == 1 ``` -**After (behavior-focused):** +**After (behavior-focused, from `tests/evidence/test_adjudicate.py`):** ```python -def test_synthesis_includes_citation_map_matching_input_articles(): - """Citation map in output should reference the exact articles provided""" - articles = [{"id": 1, "title": "Article One", "source": "Source A"}] +def test_every_pair_gets_a_ledger_row_and_evidence_gets_an_evidence_row(self, corpus): + client = FakeClient(_verdict(), _verdict(is_evidence=False, direction="none")) - result = await synthesizer.synthesize_with_trust_verification() + result = run(corpus, ClaudeAdjudicator(client)) - citation_map = result["synthesis_data"]["metadata"]["citation_map"] - assert citation_map["1"]["title"] == "Article One" - assert citation_map["1"]["source"] == "Source A" + assert (result.asked, result.evidence, result.none, result.failed) == (2, 1, 1, 0) + ledger = corpus.query(Adjudication).order_by(Adjudication.watch_id).all() + assert [(a.watch_id, a.outcome, a.audit_id) for a in ledger] == [ + ("conmon-scope-expands", "evidence", "audit-1"), + ("hiring-market-tightens", "none", "audit-2"), + ] ``` + +See `examples.md` for the full good/bad contrast pairs drawn from the +current suite. diff --git a/.claude/skills/review-tests/examples.md b/.claude/skills/review-tests/examples.md index ee06ef3..ddc6db1 100644 --- a/.claude/skills/review-tests/examples.md +++ b/.claude/skills/review-tests/examples.md @@ -1,152 +1,194 @@ # Test Examples from InsightWeaver -## Good Examples (Behavior-Focused) +Excerpts are trimmed to the lines the point needs; `# ...` marks lines left out. -### From test_synthesizer.py +## Good Examples (Behavior-Focused, Can Fail, Boundary-Mocked) + +### From tests/evidence/test_adjudicate.py ```python -class TestSynthesizeWithTrustVerificationCitationMap: - """Integration tests for citation_map handling in trust-verified synthesis""" - - @pytest.mark.asyncio - async def test_citation_map_overrides_claude_response(self, ...): - """Our citation map should override any citation_map Claude returns""" - # Arrange: Setup with KNOWN correct data - test_articles = [{"id": 99, "title": "Correct Title", ...}] - mock_curator.return_value = {"articles": test_articles} - - # Claude returns WRONG data (simulating the bug) - mock_client.return_value = json.dumps({ - "metadata": {"citation_map": {"1": {"title": "WRONG Title"}}} - }) - - # Act - result = await synthesizer.synthesize_with_trust_verification() - - # Assert: Our data wins (the behavior we care about) - citation_map = result["synthesis_data"]["metadata"]["citation_map"] - assert citation_map["1"]["title"] == "Correct Title" # Not "WRONG Title" +def test_a_second_run_asks_nothing(self, corpus): + client = FakeClient(_verdict(), _verdict()) + run(corpus, ClaudeAdjudicator(client)) + + second = run(corpus, ClaudeAdjudicator(client)) + + assert second.asked == 0 + assert client.calls == 2 + # ... ``` -**Why this is good:** -- Test name describes the behavior: "citation_map_overrides_claude_response" -- Tests a real scenario: Claude returning incorrect data -- Asserts on the outcome users care about: correct citation titles -- Does not assert on internal method calls +**Why good:** `FakeClient` replaces the one true boundary in this path -- +the Claude API -- and nothing else; routing, the adjudicator and the +database writes are all real. The name states the behavior (never-retried), +and the assertion checks both the observable count and the mechanism that +would leak a retry (`client.calls == 2`, not 4). -### From test_trust_pipeline.py +### From tests/routing/test_regression.py ```python -async def test_biased_response_detected(self, trust_pipeline): - """Test detection of bias in response""" - # Arrange - trust_pipeline.client.analyze = AsyncMock( - return_value="This revolutionary technology will change everything!" - ) - trust_pipeline.bias_analyzer.analyze = AsyncMock( - return_value=BiasAnalysis( - loaded_terms=[LoadedTerm("revolutionary", "dramatic", "innovative")] - ) - ) - - # Act - result = await trust_pipeline.run_full_pipeline( - user_query="Tell me about tech", verify_response=True - ) - - # Assert: Bias was detected (the behavior) - assert result["analysis"]["bias"]["total_issues"] > 0 +def test_exactly_the_planted_whole_word_matches_route(test_session): + # ... the two builders that plant the corpus + report = route(test_session, since=SINCE, today=TODAY) + + # ... + assert report.routed == 20 + routed_hashes = {h for (h,) in test_session.query(Route.observation_hash)} + assert routed_hashes == planted_hashes ``` -**Why this is good:** -- Tests the user-visible outcome: "bias detected" -- Does not care HOW bias was detected internally -- Meaningful assertion on what matters +**Why good:** pinned with a number, not "some routed" -- the file's +docstring records that this test was verified to fail (61 routed) when the +word-boundary anchors in `entity_matcher.py` were emptied. It checks +identity (`routed_hashes == planted_hashes`), not just count, so a router +that matched the wrong 20 items still fails. The look-alike corpus plants +`PRECISA` and `COMBAT` in capitals because task 010 found a boundary test +that passed for the wrong reason (case-sensitivity, not the anchors). ---- +### From tests/brief/test_select.py + +```python +def test_clusters_and_citations_are_ordered_by_date_before_hash(self, test_session): + # The earlier observation has the LARGER hash in both pairs, so an + # order by hash alone gets both wrong. + later_small = _obs(test_session, "aa", source.id, "later", None, datetime(2026, 9, 16), [7]*10) + earlier_big = _obs(test_session, "zz", source.id, "earlier", None, datetime(2026, 9, 15), [7]*10) + ... + assert [c[0].title for c in moved.clusters] == ["earlier", "single"] +``` -## Bad Examples (Implementation-Coupled) +**Why good:** rows are inserted with hashes running opposite to the +correct date order, so a missing or wrong `ORDER BY` fails loudly instead +of passing by coincidence. Elsewhere in the file, +`test_the_review_banner_turns_on_the_day_after_the_threshold` exercises +both sides of a threshold, which is what catches an off-by-one. -### Testing Method Signatures +### From tests/brief/test_end_to_end.py ```python -# BAD: Tests implementation detail (return type) -def test_build_synthesis_task_with_citations_returns_tuple(): - result = synthesizer._build_synthesis_task_with_citations(articles, 2) - assert isinstance(result, tuple) - assert len(result) == 2 +class _FrozenDatetime(datetime): + @classmethod + def now(cls, tz=None): + return NOW.replace(tzinfo=UTC) if tz is not None else NOW + +@pytest.fixture +def frozen_clock(monkeypatch): + monkeypatch.setattr("src.utils.datetime", _FrozenDatetime) + return NOW ``` -**Problems:** -- Name mirrors method name exactly -- Tests private method directly -- Asserts on structure, not behavior -- Would break if we changed return type but kept behavior +**Why good:** the clock is a boundary like any other -- every column +default and the belief ledger read `src.utils.utcnow`, so it is frozen here. +Everything else patched is a boundary too: the HTTP layer under each adapter, +the model client behind the adjudicator, the two private file loaders, and +each command's `get_db`, pointed at one test session. Nothing inside the +pipeline is mocked. The real CLI commands (`watch sync`, `ingest`, `route`, `adjudicate`, +`brief`) then run end to end against a real session, compared byte-for-byte +with a committed golden file -- catching regressions no single unit test +would see. + +### From tests/position/test_ledger.py -**Better:** ```python -# GOOD: Test the behavior enabled by this method -def test_synthesis_output_contains_accurate_citation_references(): - result = await synthesizer.synthesize_with_trust_verification() - # Assert on what the citation_map enables - assert result["synthesis_data"]["metadata"]["citation_map"] +def test_only_sync_and_the_two_commands_write_belief_or_resolution(): + patterns = [re.compile(r"\brecord_belief\("), re.compile(r"\bresolve_watch\("), ...] + allowed = {root / "position" / "ledger.py", root / "position" / "watches.py", + root / "cli" / "watch.py"} + offenders = [str(p.relative_to(root)) for p in sorted(root.rglob("*.py")) + if p not in allowed and any(pat.search(p.read_text()) for pat in patterns)] + assert offenders == [] ``` -### Excessive Mock Verification +**Why good:** instead of trusting every future call site to remember "only +the ledger writes belief", it scans the tree for anything that could +construct a ledger row or assign a resolution column and names the +offending file if one appears -- catching a bypass, not just documenting +the rule. + +### From tests/sources/test_runner.py ```python -# BAD: Tests plumbing, not behavior -async def test_synthesize_calls_curator_then_client(): - await synthesizer.synthesize() +async def test_source_unavailable_is_an_error_not_an_empty_run(self, db_factory, caplog): + adapter = FakeAdapter(SourceUnavailable("Fake Source", "HTTP 503")) - mock_curator.curate_for_narrative_synthesis.assert_called_once() - mock_client.analyze_with_context.assert_called_once() - # What did it produce? Who knows! + result = await run_adapter(adapter, SINCE, db_factory=db_factory) + + assert result.success is False + assert result.fetched == 0 ``` -**Problems:** -- Only verifies calls happened -- Says nothing about the outcome -- Would pass even if result is garbage +**Why good:** `FakeAdapter` mocks only the source boundary (`fetch`), which +can return items, return nothing, or raise. This test and its neighbor +`test_zero_after_some_is_loud` distinguish two failure classes that look +alike from outside (zero items): unreachable is loud on a first run, quiet +is loud only once a source has history to contradict. -**Better:** -```python -# GOOD: Test the outcome -async def test_synthesize_produces_structured_brief(): - result = await synthesizer.synthesize() +--- - assert result["status"] == "success" - assert "synthesis_data" in result - assert result["synthesis_data"]["bottom_line"] -``` +## Bad Examples (Tautological, Implementation-Coupled, or Untrustworthy) -### Testing Exception Flow +### Testing a Mock's Own Return Value ```python -# BAD: Tests exception propagation (implementation) -async def test_api_error_raises_exception(): - mock_client.analyze.side_effect = APIError("fail") +# BAD: asserts the stub returned what it was told to return +client = FakeClient(_verdict()) +response = client.analyze("system", "user") +assert response.text == _verdict() +``` - with pytest.raises(APIError): - await synthesizer.synthesize() +**Problems:** no code under test runs; this is a tautology about the +fixture, not a behavior of `run()`. No plausible bug would ever turn it +red. + +**Better:** assert on what `run()` does with that verdict, as in +`test_every_pair_gets_a_ledger_row_and_evidence_gets_an_evidence_row` +above. + +### Asserting Only a Count + +```python +# BAD: passes even if the wrong 20 items routed +def test_some_items_route(test_session): + report = route(test_session, since=SINCE, today=TODAY) + assert report.routed == 20 ``` -**Problems:** -- Tests how errors flow, not what happens -- Couples test to exception type +**Problems:** drops the identity check, so a router that matched 20 wrong +items (look-alikes instead of the planted whole words) still passes. + +**Better:** compare the routed set by hash against the known-planted set. + +### Mocking Past the Boundary -**Better:** ```python -# GOOD: Tests error handling behavior -async def test_api_failure_returns_error_status(): - mock_client.analyze.side_effect = Exception("API Error") +# BAD: mocks a method internal to the unit under test, not the true boundary +with patch("src.sources.runner.store_items") as mock_store: + await run_adapter(FakeAdapter([item("a")]), SINCE, db_factory=db_factory) + mock_store.assert_called_once() +``` - result = await synthesizer.synthesize() +**Problems:** `store_items` is internal to the module under test; the +assertion verifies a call happened, not that a row exists. - assert result["status"] == "error" - assert "error" in result +**Better:** mock only the adapter's `fetch` and assert on `RSSFeed`/ +`Article` rows through the real `db_factory` session, as the real tests do. + +### A Clock Read from the Wall + +```python +# BAD: uses the real clock in a test that asserts on dates +def test_watch_is_live_today(): + watch = Watch(id="w", expires=date.today() + timedelta(days=1), ...) + assert live_clause(date.today()) ``` +**Problems:** nothing pins the scenario; the test's meaning drifts with +the date it happens to run on. + +**Better:** pass an explicit `TODAY = date(2026, 9, 1)`, as +`tests/position/test_ledger.py` does throughout, or freeze `src.utils`'s +clock for a full command run as `test_end_to_end.py` does. + --- ## Refactoring Litmus Test @@ -155,9 +197,11 @@ Ask yourself: **If I refactor the implementation without changing behavior, do t | Refactoring | Good Test | Bad Test | |-------------|-----------|----------| -| Rename private method | Still passes | Breaks | -| Change return type of internal | Still passes | Breaks | -| Split class into two | Still passes | Breaks | -| Change algorithm (same output) | Still passes | May break | - -If your tests break on pure refactoring, they're testing implementation, not behavior. +| Rename a private helper | Still passes | Breaks | +| Change an internal data structure, same output | Still passes | Breaks | +| Split one module into two, same CLI/API behavior | Still passes | Breaks | +| Change an algorithm, same routed/adjudicated result | Still passes | May break | +| Introduce the exact bug the test exists to catch | Fails | Still passes | + +If your tests break on a pure refactor, or stay green through the bug they +were written for, they are testing implementation, not behavior. diff --git a/.env.example b/.env.example index 03839aa..a38d5c3 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,17 @@ -ANTHROPIC_API_KEY=sk-ant-your-api-key-here - +# The Anthropic API key is NOT read from this file any more (2026-09-22, +# backlog task 026). It lives in the OS keychain. Set it once with: +# +# insightweaver auth set anthropic +# # Position and the watch set are hand-authored and live in your private repo, # not this one. Defaults: ~/.config/insightweaver/{position,watches}.yaml POSITION_PATH=~/.config/insightweaver/position.yaml WATCHES_PATH=~/.config/insightweaver/watches.yaml + +# The database. The default is relative to the directory you run from; an +# absolute path (sqlite:////home/you/...) makes every directory the same. +# DATABASE_URL=sqlite:///./data/insightweaver.db + +# Where the model audit log is written. Keep it out of any cloud-synced folder. +# Default: ./data/llm-audit under the checkout. +# LLM_AUDIT_DIR=~/.local/state/insightweaver/llm-audit diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f610fbc..12766e2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -106,8 +106,16 @@ jobs: with: python-version: '3.11' + # Fails the build on a new secret. `safety` below never could (its `|| true` + # is a deliberate soft check of dependency advisories), so before 2026-09-22 + # this job could not fail on anything. (backlog task 026) + - name: Scan for secrets + run: | # pragma: allowlist secret + python -m pip install --upgrade pip + pip install detect-secrets==1.5.0 + git ls-files -z | xargs -0 detect-secrets-hook --baseline .secrets.baseline + - name: Check for security vulnerabilities run: | - python -m pip install --upgrade pip pip install safety safety check --json || true diff --git a/.gitignore b/.gitignore index 689343b..0ad56d4 100644 --- a/.gitignore +++ b/.gitignore @@ -12,10 +12,17 @@ config/position.yaml config/watches.yaml -# User profile and personal configuration (contains personal information) -config/user_profile.json -config/context_modules/core/decision_context.json -config/api_sources.json +# Backlog task 026, 2026-09-22 (docs/PLAN.md). A real estate/ directory at the +# repo root would hold the operator's private files; they belong in the private +# repo beside Position. The audit log holds every model payload that left the +# machine. Exports are the operator's data. +/estate/ +data/llm-audit/ +data/exports/ +# OAuth artefacts by name, in case a sensor library ever writes one to disk. +client_secret*.json +token*.json +.secrets.baseline.tmp # Claude Code local settings .claude/settings.local.json @@ -29,12 +36,7 @@ docs/philosophical_docs/ *.db-wal *.db-shm -# Forecast artifacts (forecast subsystem itself goes away in Stage 8) -/reports/forecasts/*.html -/reports/forecasts/*.json - # Logs -src/logs/*.log *.log # Python diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8152498..11258a0 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -30,13 +30,24 @@ repos: - id: mixed-line-ending args: ['--fix=lf'] + # Secret scanning (added 2026-09-22, backlog task 026). detect-private-key + # above catches PEM blocks only; this catches API keys and tokens. The + # baseline is empty: a false positive gets an inline `pragma: allowlist + # secret` beside it, so the exception is visible where it is made, and any + # other hit fails the commit. + - repo: https://github.com/Yelp/detect-secrets + rev: v1.5.0 + hooks: + - id: detect-secrets + args: ['--baseline', '.secrets.baseline'] + exclude: ^(requirements.*\.txt|\.secrets\.baseline)$ + # Type checking with mypy (optional, can be slow) - repo: https://github.com/pre-commit/mirrors-mypy rev: v1.19.1 hooks: - id: mypy additional_dependencies: - - types-requests - types-PyYAML args: [--ignore-missing-imports, --show-error-codes] # Only check files that are being committed diff --git a/.secrets.baseline b/.secrets.baseline new file mode 100644 index 0000000..fa812bc --- /dev/null +++ b/.secrets.baseline @@ -0,0 +1,133 @@ +{ + "version": "1.5.0", + "plugins_used": [ + { + "name": "ArtifactoryDetector" + }, + { + "name": "AWSKeyDetector" + }, + { + "name": "AzureStorageKeyDetector" + }, + { + "name": "Base64HighEntropyString", + "limit": 4.5 + }, + { + "name": "BasicAuthDetector" + }, + { + "name": "CloudantDetector" + }, + { + "name": "DiscordBotTokenDetector" + }, + { + "name": "GitHubTokenDetector" + }, + { + "name": "GitLabTokenDetector" + }, + { + "name": "HexHighEntropyString", + "limit": 3.0 + }, + { + "name": "IbmCloudIamDetector" + }, + { + "name": "IbmCosHmacDetector" + }, + { + "name": "IPPublicDetector" + }, + { + "name": "JwtTokenDetector" + }, + { + "name": "KeywordDetector", + "keyword_exclude": "" + }, + { + "name": "MailchimpDetector" + }, + { + "name": "NpmDetector" + }, + { + "name": "OpenAIDetector" + }, + { + "name": "PrivateKeyDetector" + }, + { + "name": "PypiTokenDetector" + }, + { + "name": "SendGridDetector" + }, + { + "name": "SlackDetector" + }, + { + "name": "SoftlayerDetector" + }, + { + "name": "SquareOAuthDetector" + }, + { + "name": "StripeDetector" + }, + { + "name": "TelegramBotTokenDetector" + }, + { + "name": "TwilioKeyDetector" + } + ], + "filters_used": [ + { + "path": "detect_secrets.filters.allowlist.is_line_allowlisted" + }, + { + "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies", + "min_level": 2 + }, + { + "path": "detect_secrets.filters.heuristic.is_indirect_reference" + }, + { + "path": "detect_secrets.filters.heuristic.is_likely_id_string" + }, + { + "path": "detect_secrets.filters.heuristic.is_lock_file" + }, + { + "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string" + }, + { + "path": "detect_secrets.filters.heuristic.is_potential_uuid" + }, + { + "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign" + }, + { + "path": "detect_secrets.filters.heuristic.is_sequential_string" + }, + { + "path": "detect_secrets.filters.heuristic.is_swagger_file" + }, + { + "path": "detect_secrets.filters.heuristic.is_templated_secret" + }, + { + "path": "detect_secrets.filters.regex.should_exclude_file", + "pattern": [ + "^(requirements.*\\.txt|\\.secrets\\.baseline|\\.venv/.*|htmlcov/.*)$" + ] + } + ], + "results": {}, + "generated_at": "2026-09-22T10:57:52Z" +} diff --git a/CLAUDE.md b/CLAUDE.md index 9d76dff..a4767c6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -70,7 +70,15 @@ You are working on InsightWeaver, a CLI tool that processes RSS feeds into exami 4. Epistemic autonomy as the goal -- the tool equips reasoning, does not deliver conclusions. 5. Honest self-awareness about the tool's own narrative. -**The architectural through-line:** Questions are the join key. Predictions key off Questions. DecisionEvidence keys off Questions. The forecast command is a derived view over the predictions ledger, not a separate engine. There is no "unknown unknowns" bucket -- the tool does not fabricate observables it cannot ground. +**The architectural through-line** (rewritten 2026-09-22 for the decision monitor, `docs/PLAN.md`; +Questions, Predictions and Frames were deleted on 2026-08-31): decisions are the root and watches +are the join key. A Watch is the standing requirement; it names the decision it serves, and a watch +that names none is refused. Routing is deterministic and selects candidates; adjudication is the one +model call and produces Evidence keyed to a watch; belief and resolution are written only by the +operator. The brief is a derived view over evidence, watch state and source state, not a separate +engine, and every line in it cites the observation hashes it rests on. Silence is reported as +"nothing routed since", never as nothing. There is no "unknown unknowns" bucket -- the tool does +not fabricate observables it cannot ground. Reference `docs/CONCEPTS.md` for the entity-by-entity model. @@ -78,7 +86,8 @@ Input sources arrive through the adapter layer in `src/sources/`, not through RS was relaxed deliberately on 2026-08-26 (backlog task 005) because the US public sector compliance domain does not publish enough RSS to support a brief: of the eight feeds that beat resolves, two carried articles. An adapter changes *ingestion only* -- every adapter emits the same normalized -article row the RSS path produces, so clustering, frames, questions, predictions and synthesis are -unaware adapters exist. If a change to ingestion requires editing `src/processors/` or -`src/prompts/`, the seam is in the wrong place. Every source must have a recorded basis for use in +item the RSS path produces and stores it through one path, so routing, adjudication and the brief +are unaware adapters exist. If a change to ingestion requires editing `src/routing/` or +`src/evidence/`, the seam is in the wrong place. (Reworded 2026-09-22, task 027: the consumers this +paragraph used to name were deleted.) Every source must have a recorded basis for use in `SOURCES.md`; a source with no recorded basis does not ship. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c70dca4..544be2a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,389 +1,200 @@ # Contributing to InsightWeaver -Thank you for your interest in contributing to InsightWeaver! This guide will help you get started. +## Development setup -## Table of Contents +Requires Python 3.11 or higher. -- [Development Setup](#development-setup) -- [Project Structure](#project-structure) -- [Development Workflow](#development-workflow) -- [Code Standards](#code-standards) -- [Testing](#testing) -- [Documentation](#documentation) -- [Pull Request Process](#pull-request-process) - -## Development Setup - -### Prerequisites - -- Python 3.11 or higher -- pip and virtualenv -- Git - -### Initial Setup - -1. **Clone the repository** +1. Create a virtual environment and activate it: ```bash - git clone https://github.com/yourusername/insightweaver.git - cd insightweaver + python -m venv .venv + source .venv/bin/activate ``` -2. **Create and activate a virtual environment** +2. Install development dependencies: ```bash - python -m venv venv - source venv/bin/activate # On Windows: venv\Scripts\activate + make install-dev ``` + This runs `pip install -r requirements-dev.txt`, then `pip install -e .` (editable install, + so CLI changes are picked up immediately), then `pre-commit install` (registers the git hooks + in `.pre-commit-config.yaml`). -3. **Install development dependencies** +3. Set the Anthropic API key. It is never read from `.env` -- it lives in the OS keychain: ```bash - make install-dev - # Or manually: - pip install -r requirements-dev.txt - pip install -e . - pre-commit install + insightweaver auth set anthropic ``` + `insightweaver auth status` shows which known credentials are set, without printing values; + `insightweaver auth clear` removes one. - This installs the package in editable mode (`-e`) so you can test CLI changes immediately. +4. Copy `.env.example` to `.env` and, if you keep your Position and watch set outside the + default location, point the two paths at them: + - `POSITION_PATH` (default `~/.config/insightweaver/position.yaml`) + - `WATCHES_PATH` (default `~/.config/insightweaver/watches.yaml`) -4. **Set up environment variables** - ```bash - cp .env.example .env - # Edit .env with your API keys and configuration - ``` + These are private, hand-authored files and do not live in this repository. -5. **Set up database** +5. Create a fresh database: ```bash - make db-migrate + make db-init ``` + This runs `src.database.migrations.create_schema`, which creates every table the SQLAlchemy + models declare that the database is missing, and touches nothing that already exists. If you + are working from an older checkout instead of a fresh one, the additive migrations + (`make db-add-watches`, `make db-add-observations`, `make db-add-monitor`) add whatever those + earlier stages introduced; each is safe to re-run. -6. **Run tests to verify setup** +6. Verify the setup: ```bash - make test + make check ``` -## Project Structure - -``` -insightweaver/ -├── src/ -│ ├── cli/ # Command-line interface (one module per command group) -│ ├── context/ # Synthesis orchestration: synthesizer, matcher, -│ │ # tracker, router, reconciler, frame manager -│ ├── prompts/ # Analysis rules and per-pass prompt templates -│ ├── processors/ # Content filter, deduplicator, normalizer -│ ├── pipeline/ # Top-level pipeline orchestrator -│ ├── rss/ # RSS fetching -│ ├── database/ # SQLAlchemy models and migrations -│ ├── config/ # Settings and feed loaders -│ └── utils/ # Profile loader, base formatter, logging -├── tests/ # Pytest suite, mirrors src/ layout -├── config/ # User profile + feed JSON -└── docs/ # CONCEPTS.md and other reference docs -``` - -## Development Workflow - -### 1. Create a Feature Branch +## Project structure -```bash -git checkout -b feature/your-feature-name ``` - -### 2. Make Your Changes - -Follow the [Code Standards](#code-standards) below when writing code. - -### 3. Run Quality Checks - -Before committing, run all checks: - -```bash -make check # Runs lint + typecheck + test +src/ + brief/ render the brief (header, MOVED, DUE, WATCHING, QUIET) from the database + cli/ one module per command group (adjudicate, auth, brief, ingest, replay, route, + run, sources, watch), wired together in app.py + config/ settings, OS-keychain credentials, feed matching + database/ SQLAlchemy models and the migrations under database/migrations/ + evidence/ the one adjudication model call and its prompt, plus the replay harness + llm/ the Claude client, audit logging, JSON parsing helpers + matching/ entity matching used by routing + position/ the Position and watch-set loaders, validation, and the belief/resolution ledger + routing/ compiles watch triggers and routes observations to the watches they match + rss/ RSS fetching + sources/ the adapter layer -- every source (RSS, Federal Register, ...) normalizes to + one observation shape and stores it through one path + +tests/ mirrors src/ one-to-one, plus tests/cli/ for command-level tests + +backlog/ task files (see Workflow, below) +config/ non-secret configuration checked into the repo +docs/ CONCEPTS.md (entity model), PLAN.md (architecture and delivery record), and + other reference docs ``` -Or run individually: -```bash -make lint # Run linter -make format # Auto-format code -make typecheck # Run type checker -make test # Run tests -``` +## Workflow -### 4. Commit Your Changes +Branch from `main`. `main` is protected and takes changes only through pull requests. -Pre-commit hooks will automatically run on each commit: +The convention is one backlog task per PR. A task lives as a file under `backlog/`, for example +`backlog/031-brief.md`. Its first line is a `#` title stating the task in one sentence, then a +fixed set of header fields: -```bash -git add . -git commit -m "feat: add new feature" -``` +- `REPO` -- the repository the task belongs to +- `STATUS` -- `QUEUED`, `IN_PROGRESS`, `PARKED`, `DONE`, or `FAILED` +- `SIZE` -- roughly how large the change is +- `ACCEPTANCE` -- the specific, checkable conditions the task is done against; this is the + approved plan, not a suggestion +- `OUT OF SCOPE` -- what the task deliberately does not touch, so a reviewer can tell scope + creep from the intended change +- `LANDMINES` -- known ways the task could be gotten subtly wrong, written down in advance +- `PLAN` -- where in `docs/PLAN.md` the task comes from, when it does -Use conventional commit messages: -- `feat:` New feature -- `fix:` Bug fix -- `docs:` Documentation changes -- `test:` Test changes -- `refactor:` Code refactoring -- `chore:` Maintenance tasks +A PR that closes a task updates that task's file (`STATUS: DONE` and any notes worth keeping) +as part of the same change. Commits are ordinary commits with an informative message; there is +no required commit format beyond that. -### 5. Push and Create Pull Request +## Quality gate ```bash -git push origin feature/your-feature-name -``` - -Then create a pull request on GitHub. - -## Code Standards - -### Python Style - -- Follow PEP 8 -- Use type hints for function signatures -- Maximum line length: 100 characters -- Use ruff for linting and formatting - -### Code Organization - -- Keep functions focused and single-purpose -- Avoid files longer than 300 lines -- Reuse existing functionality -- Add docstrings to all public functions and classes - -### Naming Conventions - -- **Functions/Variables**: `snake_case` -- **Classes**: `PascalCase` -- **Constants**: `UPPER_SNAKE_CASE` -- **Private members**: `_leading_underscore` - -### Example - -```python -class NarrativeSynthesizer: - """Generates narrative intelligence briefs using context engineering.""" - - async def synthesize_with_citations( - self, - hours: int = 48, - max_articles: int = 50, - ) -> dict: - """ - Generate narrative synthesis with inline citations. - - Args: - hours: Hours to look back for articles - max_articles: Maximum articles to include in context - - Returns: - Synthesis results dictionary - """ - # Implementation - pass -``` - -## Testing - -### Writing Tests - -- Place tests in `tests/` directory -- Use `test_*.py` naming convention -- Follow AAA pattern: Arrange, Act, Assert -- Use fixtures from `conftest.py` for common setup -- Mock external dependencies (API calls, file I/O) - -### Test Example - -```python -import json -import pytest - -from src.context.question_matcher import ProposedQuestion, QuestionMatcher -from src.database.models import QUESTION_STATUS_OPEN, Question - - -class TestQuestionMatcher: - """Validate LLM-output handling for the question matcher.""" - - @pytest.fixture - def matcher(self, mock_claude_client): - return QuestionMatcher(client=mock_claude_client) - - @pytest.mark.asyncio - async def test_exact_normalized_match_short_circuits_llm( - self, matcher, test_session, mock_claude_client - ): - existing = Question( - text="Will the Fed cut rates?", - normalized_text="will the fed cut rates", - status=QUESTION_STATUS_OPEN, - ) - test_session.add(existing) - test_session.commit() - - proposed = [ProposedQuestion("Will the Fed cut rates?", is_primary=True)] - result = await matcher.resolve_questions(proposed, test_session) - - assert result[0].id == existing.id - mock_claude_client.analyze.assert_not_called() +make check ``` - -When testing components that take a `session` argument, use the `test_session` fixture from `tests/conftest.py`. When testing components that open their own `get_db()` session (like the frame manager), patch `src.context..get_db` to yield the test session -- see `tests/context/test_frame_classification.py` for an example. - -### Running Tests - +runs lint, typecheck, and test, in that order, and stops if any of them fails. + +- **ruff** (`make lint`) runs `ruff check src/ tests/` and `ruff format --check src/ tests/`. + Rule set: pycodestyle, pyflakes, isort, flake8-bugbear, flake8-comprehensions, pyupgrade, and + flake8-unused-arguments/flake8-simplify (see `[tool.ruff.lint]` in `pyproject.toml`). Line + length is unenforced by the linter (left to the formatter); `make format` (alias `make fmt`) + applies fixes and formatting. +- **mypy** (`make typecheck`) runs `mypy src/ --show-error-codes --pretty`. Several modules + (`src.database.models`, `src.database.connection`, `src.rss.*`, `src.matching.*`, `src.llm.*`, + `src.cli.*`, `src.utils.*`, `src.config.*`) carry `ignore_errors` overrides in `pyproject.toml`; + new code outside those modules is checked in full. +- **pytest** (`make test`) runs `pytest tests/ -v`. +- **detect-secrets** is not part of `make check` -- it runs as a pre-commit hook and in CI (see + below), scanning against `.secrets.baseline`. A false positive gets an inline + `pragma: allowlist secret` next to it rather than a baseline edit that hides it. + +The pre-commit hooks (`.pre-commit-config.yaml`, installed by `make install-dev` or run on demand +with `make pre-commit`) run ruff (with `--fix`) and ruff-format, the standard +trailing-whitespace/end-of-file/check-yaml/check-json/check-toml/check-merge-conflict/ +detect-private-key/mixed-line-ending hooks, check-added-large-files (1000 kB, which a recorded +fixture can reach), detect-secrets, and mypy. The pre-commit mypy hook is +informational (`verbose: true`, no failure on type errors); `make typecheck` is the real gate. + +CI (`.github/workflows/ci.yml`) runs on push and PR to `main` and `develop`, as four jobs: `test` +(pytest with coverage, on Python 3.11 and 3.12), `lint` (ruff check and ruff format --check), +`typecheck` (mypy -- `continue-on-error: true`, so a type error there does not fail the build), +and `security` (detect-secrets over every tracked file, which does fail the build on a new +secret, plus a `safety` dependency check that only reports and never fails the build). + +## Tests + +Each test gets its own SQLite database through `tests/conftest.py`; no test needs a real key or +the network. `tests/evidence/stubs.py` states the rule directly in its module docstring: + +> Nothing here makes an LLM call and nothing here needs an API key. The whole point of the +> harness is that adjudication is pluggable and that the replay machinery can be exercised +> without the stochastic part. + +Anything that would otherwise touch the OS keychain uses the `memory_keyring` fixture from +`tests/conftest.py`, a keyring that forgets everything when the test ends. + +The brief has a golden end-to-end test, `tests/brief/test_end_to_end.py`, which drives recorded +RSS and Federal Register fixtures (`tests/brief/fixtures/` and +`tests/sources/fixtures/federal_register_week.json`) through `watch sync`, ingest, route, a stub +adjudicator, and the brief renderer, and compares the output byte-for-byte against +`tests/brief/golden/`. Regenerate the golden files with: ```bash -# Run all tests -make test - -# Run with coverage -make coverage - -# Run specific test file -pytest tests/context/test_synthesizer.py -v - -# Run specific test -pytest tests/context/test_synthesizer.py::TestSchemaValidation::test_passes_with_executive_summary -v +make golden ``` +and read the diff before committing it -- a golden file that changed is the test reporting a +behavior change, not noise to clear. -### Coverage Requirements - -- Aim for 85%+ overall coverage -- New features should have 90%+ coverage - -## Database Migrations - -InsightWeaver uses a custom migration system located in `src/database/migrations/`. - -### Running Migrations - +Run a single test file directly, e.g.: ```bash -# Apply migrations -make db-migrate - -# Rollback migrations -make db-migrate-down - -# Reset database (WARNING: deletes all data) -make db-reset +pytest tests/brief/test_end_to_end.py -v ``` -### Creating Migrations - -Migrations are Python modules in `src/database/migrations/` with an `upgrade()` function and optionally a `downgrade()`. For new tables, follow the pattern in `add_questions.py`: - -```python -""" -Migration: Add New Tables -Description of what this migration does. -""" -from src.database.connection import engine -from src.database.models import YourModel - - -def upgrade(): - """Apply migration.""" - YourModel.__table__.create(engine, checkfirst=True) - print(" your_table created") - - -def downgrade(): - """Rollback migration.""" - YourModel.__table__.drop(engine, checkfirst=True) - print(" your_table dropped") - - -if __name__ == "__main__": - import sys - if len(sys.argv) > 1 and sys.argv[1] == "down": - downgrade() - else: - upgrade() -``` - -For drop migrations (where there is no production rollback path), see `drop_orphan_tables.py` -- a hardcoded allowlist of table names used with `DROP TABLE IF EXISTS` via parameterized `text()`. Do not template table names from user input under any circumstances. +## Database migrations + +The modules under `src/database/migrations/`: + +- `create_schema.py` -- the one bootstrap for a fresh database. Creates every table the models + declare that is currently absent (`Base.metadata.create_all`); adds no columns to an existing + table. Run with `make db-init`. +- `add_watches_table.py` -- additive; creates the `watches` table from `Watch.__table__` so the + migration and the model cannot drift. Run with `make db-add-watches`. +- `add_observations_and_evidence.py` -- additive; creates `observations` and `evidence`, and + does not read, rewrite, or migrate the pre-existing `articles` table. Run with + `make db-add-observations`. +- `add_monitor_tables.py` -- additive; creates whichever of the decision monitor's tables + (`routes`, `adjudications`, `watch_beliefs`, `briefs`) are absent and adds the lifecycle + columns an older `watches` table lacks. Run with `make db-add-monitor`. +- `drop_briefing_tables.py` -- destructive; drops the tables belonging to the deleted briefing + product. This one refuses to run without `--confirm`; `make db-drop-briefing` deliberately + does not pass it, so the target only shows what would be destroyed and the operator has to + type the real command themselves. ## Documentation -### Code Documentation - -- Add docstrings to all public functions and classes -- Use Google-style docstrings -- Include parameter types and return types -- Provide usage examples for complex functions - -### Project Documentation - -- Update README.md for user-facing changes -- Update this CONTRIBUTING.md for development workflow changes -- Add comments for complex logic (explain "why", not "what") - -## Pull Request Process - -### Before Submitting - -1. **Ensure all checks pass** - ```bash - make check - ``` - -2. **Update tests** - - Add tests for new features - - Update tests for modified behavior - - Ensure coverage doesn't decrease - -3. **Update documentation** - - Update docstrings - - Update README if needed - - Add comments for complex logic - -4. **Clean commit history** - - Squash fixup commits if needed - - Use meaningful commit messages - -### PR Guidelines - -1. **Title**: Use conventional commit format - ``` - feat: add claim verification timeout - fix: resolve race condition in parallel fetcher - ``` - -2. **Description**: Include - - Summary of changes - - Motivation and context - - Testing performed - - Breaking changes (if any) - -3. **Size**: Keep PRs focused - - Prefer smaller, focused PRs over large ones - - One feature/fix per PR - - Large refactors should be discussed first - -### Review Process - -1. Automated CI checks must pass -2. At least one maintainer approval required -3. Address review feedback promptly -4. Squash and merge when approved - -## Getting Help - -- **Questions**: Open a GitHub Discussion -- **Bugs**: Open a GitHub Issue -- **Features**: Open a GitHub Issue with proposal - -## Code of Conduct - -- Be respectful and inclusive -- Provide constructive feedback -- Focus on the code, not the person -- Help others learn and grow - -## License - -By contributing, you agree that your contributions will be licensed under the MIT License. - ---- - -Thank you for contributing to InsightWeaver! +- `README.md` -- what the tool is and why +- `GETTING_STARTED.md` -- first-run walkthrough +- `docs/CONCEPTS.md` -- the entity model (Watch, Evidence, Position, etc.) +- `docs/PLAN.md` -- the architecture and the delivery record it was built from +- `SOURCES.md` -- every source InsightWeaver retrieves and its recorded basis for use; a source + with no recorded basis does not ship +- Comments that record a decision carry the date the decision was made, so a later reader can + tell whether the reasoning still applies. + +## Pull requests + +A reviewer checks: + +- `make check` is green +- the backlog task file is updated (`STATUS`, and notes on what changed vs. what the task + described) +- no fallback or mock data is hiding a problem that should fail loudly instead +- changed files stay under roughly 200-300 lines; a file that grew past that is a refactor + candidate, not an exception diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index aebb516..f084414 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -1,217 +1,150 @@ -# Getting Started with InsightWeaver +# Getting Started -> **Superseded 2026-08-31 (backlog task 012).** The briefing product this -> document describes -- `brief`, beats, questions, predictions, frames, -> synthesis and rendering -- has been **deleted**. Roughly 8,900 lines of source -> and most of the test suite went with it, in a single commit, because the -> operator's call was that git history is the rollback path and dead code in the -> tree reads as current. `insightweaver` now exposes one command, `sources`. -> -> What survives is ingestion: `src/sources/`, `src/rss/`, `src/processors/`, the -> feed config, and five modules ported for tiers not yet built -> (`src/matching/entity_matcher.py`, `src/matching/coverage_probe.py`, -> `src/llm/claude_client.py`, `src/utils/cadence.py`, -> `src/processors/deduplicator.py`). -> -> **Everything below this banner describes the deleted product and has not been -> rewritten.** Rewriting it needs the new pipeline to exist first, which task 012 -> explicitly puts out of scope. Read it as history until it is replaced. +From a clean checkout to a first brief. Rewritten 2026-09-23 (backlog task 033). ---- +## What you need -This guide walks you through downloading, installing, and running InsightWeaver on your computer. +- Python 3.11 or newer. +- An Anthropic API key, for the one model call the tool makes (`adjudicate`). Everything else, + including the whole test suite, runs without one. +- A place outside this checkout for two private files, described in step 3. ---- +## 1. Install -## What You Need - -1. **A computer** (Windows, Mac, or Linux) -2. **Python 3.11 or newer** -- [Download Python](https://www.python.org/downloads/) -3. **An Anthropic API key** -- [Get one here](https://console.anthropic.com/) (requires account; ~$0.20-0.40 per brief) - ---- - -## Step 1: Download InsightWeaver - -**Option A: Download ZIP** (easiest) -1. Click the green "Code" button on this page -2. Click "Download ZIP" -3. Extract the ZIP file to a folder (e.g., your Documents folder) - -**Option B: Using Git** (if you have it installed) -``` -git clone https://github.com/YOUR_USERNAME/InsightWeaver.git +```bash +git clone https://github.com/sam-aydlette/InsightWeaver.git +cd InsightWeaver +python -m venv .venv +source .venv/bin/activate +make install-dev ``` ---- - -## Step 2: Open a Terminal +`make install-dev` installs the pinned dependencies, the package in editable mode so that +`insightweaver` is on your path, and the pre-commit hooks. Check it worked: -**Windows:** -1. Press `Windows + R`, type `cmd`, press Enter -2. `cd Documents\InsightWeaver` - -**Mac:** -1. Open Spotlight (`Cmd + Space`), type `Terminal`, press Enter -2. `cd ~/Documents/InsightWeaver` - -**Linux:** -1. Open your terminal application -2. `cd ~/Documents/InsightWeaver` - ---- - -## Step 3: Install InsightWeaver - -``` -python -m venv venv +```bash +insightweaver --help +make check ``` -Activate the virtual environment: - -- Windows: `venv\Scripts\activate` -- Mac/Linux: `source venv/bin/activate` +`make check` runs the linter, the type checker and the test suite. It needs no key and no +network. -Install: +## 2. Store the key +```bash +insightweaver auth set anthropic ``` -pip install -e . -``` - ---- - -## Step 4: Add Your API Key - -``` -cp .env.example .env # Mac/Linux -copy .env.example .env # Windows -``` - -Open `.env` in any text editor. Replace `your_key_here` with your actual API key. Save. ---- +You are prompted for the key, hidden, and it is written to the OS keychain. It is never read +from `.env` and never printed; `insightweaver auth status` says whether it is set. -## Step 5: Set Up Your Profile +## 3. Write your Position and watches -Copy the example profile to its expected location: +The tool's whole input is two hand-authored YAML files: the decisions you are carrying, with +deadlines, and the claims you want watched, with the words a document would contain if it +bore on them. They name real decisions and real deadlines, so they belong in a private +repository of your own, not in this one. Tell the tool where they are: +```bash +cp .env.example .env +# edit POSITION_PATH and WATCHES_PATH in .env, or leave the defaults: +# ~/.config/insightweaver/position.yaml +# ~/.config/insightweaver/watches.yaml ``` -cp config/user_profile.example.json config/user_profile.json -``` - -Open `config/user_profile.json` and edit it for your situation -- location, profession, civic interests, etc. The profile is what makes the brief location-aware and personally relevant. - ---- -## Step 6: Generate Your First Briefing +Two ways to write them: -``` -insightweaver brief -``` +- **Interview.** In Claude Code, run the `/onboard` skill. It asks for each decision and each + watch, field by field, writes the two files from your answers, and ends by syncing them. It + transcribes; it does not suggest decisions, beliefs or claims. +- **By hand.** Copy `config/position.example.yaml` and `config/watches.example.yaml` to the + private paths and edit them. The comments in both files explain every field, and the loader + refuses a file with a missing or malformed field, all problems at once, so a mistake is a + message rather than a silent default. One thing it cannot check: a `sources` trigger names a + source by its exact registered name (the `name` in `config/feeds/`, or `Federal Register - + Documents API`), and a misspelling is a clause that never fires. `insightweaver sources list` + shows the names once a first `ingest` has run. -This takes 2-5 minutes. The brief renders directly to your terminal. To archive a copy as markdown: +Then create the database and load the watches: -``` -insightweaver brief --save brief.md +```bash +make db-init +insightweaver watch sync +insightweaver watch list ``` ---- - -## Daily Use - -The minimum rhythm is one command: +## 4. The first morning +```bash +insightweaver run ``` -insightweaver brief -``` - -Each morning. That's it. The brief renders to your terminal with everything you need: situation analyses, narrative-layer mapping, branching paths, information gaps, returning question identity (`Q47 (run 4, asked 2026-03-12)`), and a transparency line reporting which of yesterday's flagged observables resolved. -You don't need to touch anything else. +This runs four commands in order and stops at the first that fails: ---- +1. `ingest` reads every configured source and stores what is new. Each source is reported as + fetched, inserted, unreachable, or went silent. +2. `route` links each new observation to the watches whose triggers it matches, and reports + what routed nowhere, grouped by story and by source, so you can see what your triggers miss. +3. `adjudicate` asks the model, once per routed pair, whether the item bears on the claim. + Every request is written to `data/llm-audit/` before it is sent. +4. `brief` prints the brief. -## Optional: tracking threads across time +Read the brief top to bottom. The header says whether every source ran; MOVED is what gained +evidence; DUE is what has a date on it; WATCHING is every live claim and your current belief; +QUIET is where silence might be breakage. A brief whose QUIET section is all zeros and whose +sources all fetched is a quiet week. A brief with a source marked `LAST ATTEMPT FAILED` or a +watch marked `never routed` is telling you where to look. -InsightWeaver maintains a persistent commitment graph behind the brief -- Questions, Predictions, Decisions, Frames. These accumulate automatically whether or not you ever query them, but the CLI exposes them when you want to look. +To see what would be sent before spending anything: -**See [docs/CONCEPTS.md](docs/CONCEPTS.md)** for a one-page reference on what each entity is and when it gets created. - -Commands available when you want depth: - -``` -insightweaver questions list # threads the coverage is still tracking -insightweaver questions show 47 # full history of question Q47 -insightweaver predictions track-record # the tool's own calibration record -insightweaver decisions list # standing decisions -insightweaver decisions show 1 # factors and routed evidence for D1 -insightweaver diet feeds # which frames each feed carries -insightweaver diet gaps # frames consistently absent (curation signal) -insightweaver sources list # per-source structural calibration -insightweaver frames list # the narrative frame glossary -insightweaver forecast # open observables + resolved record +```bash +insightweaver adjudicate --dry-run ``` -If you want to register decisions so they accumulate evidence over time: +## Daily use +```bash +insightweaver run # the morning +insightweaver watch believe my-watch 0.6 --note "the notice narrows the scope" +insightweaver watch resolve my-watch --outcome yes --note "final rule published 2026-10-02" +insightweaver brief --format md --output ~/briefs/today.md ``` -insightweaver decisions add --name "housing market timing" --type housing -insightweaver decisions factor add 1 --name "interest rates" \ - --update-when "Fed signals a cut or hold at the next meeting" -``` - -Then each subsequent brief will route relevant situation evidence into that decision automatically. - -Run `insightweaver --help` or type `help` in interactive mode for the full command list. - ---- -## Filtering the brief +Beliefs are yours to move and are appended, never edited. A watch is graded once. When a +decision closes or a claim stops mattering, edit the private files and run `watch sync`; a +watch removed from the file is retired, not deleted, so its history stays. -The brief accepts topic and scope filters: - -``` -insightweaver brief --hours 48 # look back 48 hours -insightweaver brief -cs -n # national cybersecurity only -insightweaver brief --hours 48 -l # 48-hour local news -``` - -Topic flags: `--cybersecurity` (`-cs`), `--ai` (`-ai`). Scope flags: `--local` (`-l`), `--state` (`-s`), `--national` (`-n`), `--global` (`-g`). Combine with AND logic. - ---- +The default window of a brief opens at the last brief before today, so running `brief` twice +in a morning reports the same window and the same items; only the as-of stamp in the first +line moves. With `--as-of` fixed, the bytes are identical, and the suite asserts it. ## Troubleshooting -**"command not found" or "not recognized"** -- the virtual environment isn't active. Run `source venv/bin/activate` (Mac/Linux) or `venv\Scripts\activate` (Windows). You should see `(venv)` at the start of your prompt. - -**"No module named..."** -- reinstall: `pip install -e .` - -**API key errors** -- check that `.env` exists and contains your key with no extra spaces around the `=`. Verify the key at [console.anthropic.com](https://console.anthropic.com/). - -**Brief is empty or errors out** -- check internet connection and API credit balance. Add `--debug` for verbose logs: `insightweaver brief --debug`. - ---- - -## Configuration - -**Your profile** is `config/user_profile.json`. Edit directly to change your location, professional domain, or topic interests. Most users edit this once a year, when major life circumstances change. - -**Your RSS feeds** are configured in `config/feeds/`. Each JSON file lists feed URLs by category. Add or remove sources to shape your information diet -- the `diet gaps` command will tell you what perspectives are missing. - ---- +- **`insightweaver: command not found`**: the virtual environment is not active. Run + `source .venv/bin/activate`. +- **`no credential 'anthropic_api_key' in the keychain`**: run `insightweaver auth set anthropic`. +- **`No Position at ...` or `No watch set at ...`**: `POSITION_PATH` or `WATCHES_PATH` does not + point at a file. Check `.env`. +- **`no such table`**: run `make db-init`. +- **`unable to open database file`**: the database path is relative to the directory you run + from. Run commands from the checkout, or set `DATABASE_URL` in `.env` to an absolute path + (`sqlite:////home/you/insightweaver/data/insightweaver.db`). +- **A source reports UNREACHABLE every morning**: `insightweaver sources show NAME` prints its + URL and last error. Old feeds in `config/feeds/` do go dark; remove the entry and `ingest` + stops asking it. Its row stays in the database, so the header keeps printing its last attempt + and `sources list` keeps listing it; there is no command to remove a source yet. +- **The run stopped at `adjudicate` with "the API was unavailable"**: nothing was recorded for + the pair it stopped on; run `insightweaver adjudicate` again later and it resumes. ## Privacy -- All data is stored locally in `data/insightweaver.db` -- News articles come from public RSS feeds you configure -- Synthesis runs through the Anthropic API (no third-party sharing) -- Delete `data/` to wipe all accumulated state - ---- - -## Requirements - -- **Python:** 3.11 or newer -- **Disk:** ~100MB for database -- **Internet:** for RSS fetch and API calls -- **API budget:** ~$0.20-0.40 per brief +- The database is `data/insightweaver.db`, relative to the directory you run from, and the audit + log is `data/llm-audit/` under the checkout. Keep both out of cloud-synced folders; + `DATABASE_URL` and `LLM_AUDIT_DIR` in `.env` move them. +- The only network calls are fetching your configured sources and the model API. Nothing + listens, nothing sends mail, nothing writes to any external service. +- The audit log holds every request that left the machine, in full, and each response's usage + and stop reason. It is yours to read and to delete. +- Delete `data/` to wipe all accumulated state. Your Position and watches are elsewhere and are + untouched. diff --git a/Makefile b/Makefile index 22a1473..59600b4 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: help install install-dev test lint format fmt typecheck check pre-commit clean clean-all coverage db-add-watches db-add-observations db-drop-briefing update-deps +.PHONY: help install install-dev test lint format fmt typecheck check pre-commit clean clean-all coverage db-add-watches db-add-observations db-add-monitor db-drop-briefing update-deps # Tool resolution (added 2026-08-24). # Before this, every recipe called bare `pytest` / `ruff` / `mypy`, which only @@ -44,8 +44,10 @@ help: @echo " make check Run all checks (lint + typecheck + test)" @echo "" @echo "Database:" + @echo " make db-init Create every table a fresh database lacks (additive, safe)" @echo " make db-add-watches Create the watches table (additive, safe)" @echo " make db-add-observations Create observations and evidence (additive, safe)" + @echo " make db-add-monitor Create the decision monitor tables (additive, safe)" @echo " make db-drop-briefing Drop the deleted briefing product's tables" @echo " (DESTRUCTIVE; captures to a dump first)" @echo "" @@ -72,6 +74,11 @@ test: coverage: $(PYTEST) tests/ --cov=src --cov-report=term-missing -v +# Rewrite tests/brief/golden/ from the current renderer. Read the diff before +# committing it: a golden that changed is the test reporting a change. +golden: + INSIGHTWEAVER_UPDATE_GOLDEN=1 $(PYTEST) tests/brief/test_end_to_end.py -q + lint: $(RUFF) check src/ tests/ $(RUFF) format --check src/ tests/ @@ -115,6 +122,12 @@ clean-all: clean rm -rf venv/ rm -rf .venv/ +# A fresh database: every table the models declare, creating what is absent +# and touching nothing that exists. The additive targets below add columns to +# older tables and are harmless after this. (2026-09-23, backlog task 033.) +db-init: + $(PYTHON) -m src.database.migrations.create_schema + # Additive: creates the watches table if it is absent and prints that it did # nothing if it is not. No --confirm, because nothing here can lose data; the # --down direction can, and requires one. (2026-08-31, backlog task 013.) @@ -127,6 +140,11 @@ db-add-watches: db-add-observations: $(PYTHON) -m src.database.migrations.add_observations_and_evidence +# Additive: the decision monitor's tables (routes now; adjudications, +# watch_beliefs and briefs as tasks 029-031 land). (2026-09-22, backlog task 028.) +db-add-monitor: + $(PYTHON) -m src.database.migrations.add_monitor_tables + # Deliberately does NOT pass --confirm. The migration refuses without it, so # running this target prints what it would destroy and stops; the operator types # the real command themselves. A Makefile target that drops tables on `make` is diff --git a/README.md b/README.md index 345e5fb..f2599bf 100644 --- a/README.md +++ b/README.md @@ -1,604 +1,262 @@ # InsightWeaver -> **Superseded 2026-08-31 (backlog task 012).** The briefing product this -> document describes -- `brief`, beats, questions, predictions, frames, -> synthesis and rendering -- has been **deleted**. Roughly 8,900 lines of source -> and most of the test suite went with it, in a single commit, because the -> operator's call was that git history is the rollback path and dead code in the -> tree reads as current. `insightweaver` now exposes one command, `sources`. -> -> What survives is ingestion: `src/sources/`, `src/rss/`, `src/processors/`, the -> feed config, and five modules ported for tiers not yet built -> (`src/matching/entity_matcher.py`, `src/matching/coverage_probe.py`, -> `src/llm/claude_client.py`, `src/utils/cadence.py`, -> `src/processors/deduplicator.py`). -> -> **Everything below this banner describes the deleted product and has not been -> rewritten.** Rewriting it needs the new pipeline to exist first, which task 012 -> explicitly puts out of scope. Read it as history until it is replaced. +A compass for insight at cybernetic speed. + +In land navigation you don't walk with your face in the compass. You shoot an azimuth to a +point you can actually see, drop the compass to your side, and walk to it -- counting paces, +reading the terrain, following a handrail where the ground gives you one. You picked that +azimuth once, at the start point, relative to where you actually stood and where you actually +needed to go. The compass doesn't know what's out there. It only gives you a bearing, and the +bearing only means anything once you've oriented it to your own position on the map -- there's +no reading a compass from nowhere. + +Most information tools skip the orientation step. They hand you volume in the general direction +of "everything," which isn't a bearing at all -- it's what you get when you start walking before +you've found your position on the map. InsightWeaver asks for the start point first: the +decisions you are actually carrying, each with a real deadline. A **watch** is the azimuth shot +to one of them -- a specific claim, at a specific bearing, that would move you if it turned out +true. Routing is pacing toward it. Adjudication is terrain association: does what you're +passing actually confirm the bearing, or is it a lookalike a keyword caught without being on +the route. And when nothing has confirmed the route in longer than expected, that's not +silence to read as "all clear" -- it's the catching feature telling you that you may have +drifted, and the tool says so instead of staying quiet about its own quiet. + +Nothing in it authors a watch, moves a belief, or sends anything anywhere. It runs on your +laptop, from the command line, when you run it. ---- - -**A tool for building warranted, inspectable understanding from RSS feeds.** - ---- - -## Current state - -**A research prototype under active development, not a finished product.** It runs, it is tested, -and parts of it do not yet work. This section says which is which, and is updated when that -changes. Last updated 2026-08-27. - -**What works today** - -- The pipeline runs end to end and produces a brief: RSS and Federal Register ingestion, dedup, - filtering, clustering, three synthesis passes, and rendering to terminal, Markdown, HTML, or - email. The most recent live run analysed 50 articles into 9 situations in about ten minutes. -- Beats scope a brief to a subject rather than a person, without a `beat_id` column on any graph - table -- scope is derived from a join, so one question can belong to two scopes with independent - counts (`backlog/004`). -- Ingestion is behind an adapter interface, so a source that publishes no RSS can still be read - (`backlog/005`). -- Standing questions: a beat declares what it watches, and a question that did **not** move is - reported rather than dropped (`backlog/007`). -- Institutional activity is reported as movement against a trailing average, never as a tally, - and tracks organizations, programs, and document types -- **never individuals** (`backlog/006`). -- A stored brief can be re-rendered offline in any format with no API key and no network call. -- 852 tests; `make check` runs lint, typecheck, and the suite. `main` requires a pull request and - five green checks, enforced for administrators. - -**Known limitations, stated plainly** - -- **The calibration record is still empty, though the machinery now exists.** 33 model-generated - predictions have been graded zero times; 25 are phrased "X would signal Y", an interpretation - rule that cannot be wrong. As of `backlog/011` an operator can stake a dated, confidence-bearing - claim and resolve it, and those are counted separately from the model's. **Nothing has been - staked yet.** Until something is, the tool's central claim remains unmet -- the fix is a - mechanism, not a result. -- **Adding a feed to `config/feeds/` does not add it to the database.** `FeedManager.load_feeds_to_database()` - syncs config into the `rss_feeds` table, and the fetcher reads the table, not the config. A beat - resolves feeds from config, so a newly added source will resolve, pass its tests, and fetch - nothing until that sync is run. This was found on 2026-08-28 when five trade outlets were - configured, CI was green, and the corpus stayed empty of them. -- **Questions declared in a beat config carry no review cadence.** The four standing questions on - the `us-public-sector-compliance` beat -- including the CMMC one -- predate cadences, and there is - no `questions set-cadence`. They are invisible to `forecast --due` until re-declared with - `questions add --cadence`. Per-question cadences otherwise work (`backlog/011`). -- **Per-run cost is unmeasured.** There is no token accounting. -- **Delta-based features need history to mean anything.** Institutional activity reports "no - trailing average yet" until several runs have accumulated. This is by construction, not a bug. - -**How the work is recorded** - -Every change lands as a pull request, and every non-trivial one is specified first in -`backlog/NNN-*.md` with a goal, acceptance criteria, explicit out-of-scope boundaries, and known -landmines. Those files are kept after the work ships, including where a later task documents that -an earlier one measured the wrong thing -- `backlog/009` and `backlog/010` exist because -`backlog/005` reported document counts as domain coverage, and that is written down rather than -quietly corrected. - -## The Problem - -The dominant narratives in daily news coverage preclude alternatives without the reader knowing it. This is a structural feature of how information is produced and distributed. Every article frames its subject: it foregrounds certain facts, backgrounds others, and takes certain premises for granted. When your information sources all use the same frame, you are not exposed to the alternatives. You cannot evaluate what you cannot see. - -The traditional response to this problem -- aggregating more sources -- does not solve it. More articles using the same frame is not more perspective. It is more volume. - -Information overload is a real problem, but it is a symptom. The deeper problem is that the reader has no way to see the editorial structure of their information diet: which frames are present, which are absent, and what assumptions are embedded in the coverage they consume. - ---- - -## What You Get - -You read your morning brief and come away understanding: - -1. **What is actually happening** -- not just what is being reported. The underlying situation, not the headline. -2. **Who is doing what to whom, and why** -- named actors with identified interests, not abstract forces. -3. **What the coverage makes easy to see and what it makes hard to see** -- the narrative layers in the reporting, where they conflict, and what is structurally absent from the sources you read. -4. **Where the story could go** -- the branching paths, what would have to be true for each one, and the unresolved question that determines which way it breaks. -5. **What you would need to know to make a good decision about this** -- the specific information gaps, why they exist, and what kind of source would fill them. - -This is the value proposition. Everything else -- the architecture, the frame glossary, the clustering -- exists to deliver these five outcomes. - ---- - -## Two ways to use it - -**Just stay informed.** Run `insightweaver brief` in the morning. Read the output. You get all five outcomes above, plus a transparency line at the top reporting which of yesterday's flagged observables resolved overnight. That's the whole rhythm. - -**Track threads across time.** Behind the brief is a persistent commitment graph: Questions the coverage is still tracking, Predictions whose triggers may yet fire, Decisions you're carrying, Frames each feed exhibits. The graph accumulates whether or not you ever query it -- but you can query it. `insightweaver questions list`, `decisions show housing`, `predictions track-record`, `diet gaps`. The brief itself surfaces returning question identity inline (`Q47 (run 4, asked 2026-03-12)`), so the graph is visible even from the minimal flow. - -The deeper layer is optional. Most readers will never touch it. The architecture exists so that the brief is grounded in accumulated context rather than reset every morning. - -See [docs/CONCEPTS.md](docs/CONCEPTS.md) for the one-page reference if you want to understand the persistent layer. - ---- - -## Principles - -### 1. Insight over information - -The output should help you understand what story is being told and what it assumes -- not just what was reported. A list of headlines is not a briefing. A briefing that tells you what happened without surfacing the frame through which "what happened" was constructed has done half the job. - -### 2. Warranted trust over projected confidence - -Transparency about sourcing, epistemic status, and uncertainty is the mechanism. Every claim carries a label: reported fact, single-source claim, consensus view, or speculation. When the label is ambiguous, the system defaults to the weaker one. False confidence is a violation even when the underlying claim is accurate. A synthesis that honestly maps what it does not know is more useful than one that papers over holes. - -### 3. Frame visibility over false balance - -Balance does not mean equal treatment of all positions. It means making the frames present in the corpus visible, naming their assumptions, and explicitly flagging what is absent. Bothsidesism is itself a framing choice -- one that treats the number of perspectives presented as a proxy for fairness while obscuring the structural question of which perspectives were available in the first place. InsightWeaver surfaces frames as structural features of coverage: what a frame emphasizes, what it de-emphasizes, and what it takes for granted. It does not evaluate which frame is "correct." - -### 4. Epistemic autonomy as the goal - -The system equips the user to reason. It does not hand them conclusions. Synthesis is not the same as manipulation. When information is insufficient to draw a conclusion, the system says what is missing and stops. It does not fill gaps with plausible-sounding inferences. The user decides what the information means. - -### 5. Honest self-awareness about the tool's own narrative - -InsightWeaver makes editorial choices: which feeds to include, how to cluster topics, which frame candidates to surface for validation. Those choices shape the output. They are surfaced to the user, not hidden behind a veneer of objectivity. RSS feed selection is explicitly the user's responsibility. Frame validation requires human review. The system's own assumptions are part of what it reports on. - ---- - -## What InsightWeaver Does - -InsightWeaver is a CLI tool that runs on your computer. It fetches RSS feeds you configure, synthesizes them into daily briefings using Claude (Anthropic's AI), and makes the narrative structure of the coverage visible. - -The output is organized around **situations**, not headlines. A situation is a mini-narrative with examined characters: who are the actors, what are their interests, what are they doing, who benefits, who is harmed, who decides. The actors and interests emerge from sourced evidence, not from the tool's editorial preference. When the evidence is ambiguous about who benefits, the tool says so rather than picking a side or retreating into "there are many perspectives." - -**Epistemic labeling.** Every claim carries a status: reported fact, single-source claim, consensus view, or speculation. Uncertainty is expressed as a structural feature of the information -- what is missing and why it matters -- not hidden behind hedging language. - -**Frame analysis.** For each situation, the system identifies the dominant frame in today's coverage, names its assumptions, and flags which frames are absent. It also identifies the causal structure that determines outcomes regardless of how the coverage frames it -- the forces, constraints, and dependencies that matter whether or not the articles mention them. - -**An emergent frame glossary** built from your actual corpus over time. When a topic cluster has no known frames, the system discovers candidates. You validate them interactively: accept, reject, or edit. Nothing enters the glossary without your review. - -**Gap detection as a feed curation signal.** When a frame is consistently absent from your feeds, the system logs the gap and recommends a type of source that would carry the missing perspective. It does not attempt to fill the gap itself. It does not search the web. Source control stays with the user. - -**Transparency about the tool's own choices.** Every briefing tells you which feeds contributed, what was filtered, how articles were clustered into situations, and which frames are known versus newly discovered. The system's editorial decisions are part of what it reports on. - ---- - -## How It Works - -InsightWeaver uses context engineering: it curates optimal context for Claude and bakes analytical guardrails into the prompt rather than checking outputs after the fact. The pipeline has three synthesis passes (clustering, situation analysis, cross-cluster reconciliation) plus supporting passes that maintain the persistent layer. - -The synthesis path (what produces the brief you read): - -1. **Collection** -- RSS feeds are fetched in parallel from sources you configure -2. **Deduplication** -- duplicate and near-duplicate articles are removed -3. **Context curation** -- articles are selected based on your profile (location, profession, interests) -4. **Pass 1 -- Clustering and frame discovery** -- articles are grouped into situations. For each situation, the system checks for known frames or discovers new ones. This pass is auditable: you can inspect which articles landed in which cluster. -5. **Pass 2 -- Situation synthesis** -- Claude analyzes each situation with known frames injected, producing examined narratives with actors, interests, power dynamics, frame analysis, and information gaps. `ANALYSIS_RULES.md` is injected into every prompt, enforcing epistemic labeling and structural honesty. -6. **Pass 3 -- Cross-cluster reconciliation** -- looks for meta-fractures: a single underlying frame conflict appearing across multiple topically distinct situations. Empty result is common and expected. - -The persistent-layer maintenance that runs alongside (you don't have to read any of this -- it just makes the next brief grounded in accumulated context): - -- **Pre-pass: prediction check.** Before any new analysis, the open-prediction ledger is graded against today's coverage. Observables flagged in past runs are marked triggered, contradicted, or still open. A transparency line at the top of every brief reports the result. -- **Question matching.** Each situation's unresolved questions are bound to a persistent graph. Returning questions surface their identity inline (`Q47 (run 4, asked 2026-03-12)`). A beat can also declare standing questions it always reports against, moved or not. -- **Prediction creation.** `what_to_watch` observables from each situation become open predictions, keyed to their question. -- **Frame classification.** Each article in each cluster is tagged with the frame it most exhibits. -- **Decision routing.** Situations are matched against the factors of standing decisions you've registered. Today's coverage gets recorded as evidence per decision, so each run updates an accumulating record. - -RSS is the only input source. The `forecast` command is a derived view over the predictions ledger -- not a separate engine. - -See [docs/CONCEPTS.md](docs/CONCEPTS.md) for the entity-by-entity reference. - ---- - -## Who This Is For - -People who want to understand the structure of the news they consume, not just its content. People who want to know who benefits, who is harmed, and what the coverage makes hard to see. People who are willing to curate their own sources and validate the system's frame discoveries. People who prefer tools that are transparent about their own editorial choices. - ---- - -## Getting Started - -```bash -git clone https://github.com/YOUR_USERNAME/InsightWeaver.git -cd InsightWeaver -python -m venv venv && source venv/bin/activate -pip install -e . -cp .env.example .env # Add your ANTHROPIC_API_KEY -insightweaver brief # Generate your first briefing ``` - -See [GETTING_STARTED.md](GETTING_STARTED.md) for detailed setup instructions. - ---- - -## Re-rendering a Stored Brief - -`insightweaver brief` runs the whole pipeline: it fetches feeds and re-synthesizes, -so two invocations never produce the same brief. When you want *last night's* brief -again -- as HTML, as email, or just on screen -- render the stored run instead: - -```bash -insightweaver brief --from-run 176 # terminal -insightweaver brief --from-run 176 --format html --output out.html # self-contained page -insightweaver brief --from-run 176 --format email # send via SMTP -insightweaver brief --from-run 176 --save brief.md # markdown archive +insightweaver run ``` -The id is a `narrative_syntheses` row id; an unknown id lists the recent ones. This -path is offline and deterministic -- no feeds, no Claude call, no `ANTHROPIC_API_KEY` -required, and the same id always renders the same bytes. Email uses the SMTP -variables in `.env` (`SMTP_SERVER`, `SMTP_PORT`, `EMAIL_USERNAME`, `EMAIL_PASSWORD`, -`FROM_EMAIL`, `RECIPIENT_EMAIL`); a failed send reports why and exits non-zero, -with no retry or outbox. +## Status, stated plainly + +- The monitor runs end to end: ingestion, deterministic routing, one structured model call per + candidate pair, an append-only belief ledger, hand grading, and the brief. `make check` runs + lint, types and the suite, and a golden-file test drives a recorded Federal Register week and + a recorded feed through `watch sync`, `ingest`, `route`, `adjudicate` and `brief` with a + scripted model and a frozen clock. +- Track record builds from your own watches resolving against your own coverage, week over + week (`docs/PLAN.md`, section 5, is the plan it's measured from). Read the QUIET section of + every brief; it's where a run tells you where it might be missing something, instead of + staying quiet about its own silence. +- `articles` is the table the product this one replaced ingested into. Ingest still writes a + row there beside each new observation, and `sources list` counts them; the rows written before + the rewrite have no observation and nothing in the monitor reads them. The rule is in + `src/database/models/__init__.py`. +- The earlier product, a daily synthesis over questions, predictions and frames, was deleted on + 2026-08-31 in one commit. Git history is where it lives; `docs/RECONCILIATION.md` says why. + +## The idea + +Every platform you use is already a feedback loop: it reads what moves you, adjusts what it +shows you, and reads the result -- steering, continuously, at whatever speed its infrastructure +allows. That's not a metaphor; it's how a recommendation system is built, and it is cybernetics +in the original sense of the word, steering. The asymmetry is that the loop steers toward the +platform's ends, not yours, and it moves faster than you can audit it. + +The individual-scale answer isn't to opt out of information -- that just hands the steering to +someone else's loop by default. It's to build your own, deliberately, at the same speed, and +keep it in view instead of behind an interface. A watch is the stake in the ground: a claim, +tied to a decision you're actually carrying, that you commit to caring about before anything +happens, so that what arrives afterward has a bearing to be measured against instead of just +adding to the pile. Routing, one model judgment per candidate, and an append-only record of what +you believed and when are the loop itself, running for you, on your terms, on your machine. + +The design follows from five principles the project has kept since it began. Each is stated +with how this build carries it, or does not. + +1. **Insight over information.** The brief has no headline list. Its unit is a watch that gained + evidence, and a watch exists only because a decision needs it. +2. **Warranted trust over projected confidence.** Every evidence line carries the observation + hash it rests on, the source, the direction, a magnitude, and the prompt version that judged + it. A belief is a number the operator wrote, with a date and a note, never one the tool + inferred. +3. **Frame visibility over false balance.** Not implemented in this build. The monitor has no + notion of a frame; it returns, if it does, with the deferred synthesis pass (`docs/PLAN.md`, + section 8). +4. **Epistemic autonomy as the goal.** There is no view from nowhere for the tool to hand you a + conclusion from -- it reports that an item bears on a claim and how strongly, from the bearing + you already staked. What that means for the decision is the operator's, and the `so_what` the + operator wrote is printed back, not paraphrased. +5. **Honest self-awareness about the tool's own narrative.** A brief that looks the same when + nothing happened and when the pipeline is broken is the failure the design exists to prevent. + The header names every source whose last attempt failed, in full, by default; a summary + count covers the rest (`--verbose` lists every source). QUIET prints every watch that + heard nothing, every source that ran and returned nothing, every routed pair no adjudication + has answered, and every model call that failed, with zeros when there are none. Every model + request is written to a local audit log before it is sent, and each response's usage after. + +## How a morning runs + +| step | command | what it does | writes | model | +|---|---|---|---|---| +| 1 | `insightweaver ingest` | reads every configured source through the adapter layer and stores what is new, content-addressed | `observations`, `articles`, `rss_feeds` | no | +| 2 | `insightweaver route` | compiles each live watch's triggers to word-boundary rules and links matching observations | `routes` | no | +| 3 | `insightweaver adjudicate` | one structured call per routed pair that this prompt version has not answered; records every outcome, retries nothing | `adjudications`, `evidence`, audit log | yes | +| 4 | `insightweaver brief` | renders the brief as of now, deterministic to the byte | `briefs` | no | + +`insightweaver run` chains the four and stops at the first that fails. Belief and grading are +separate, by hand: `watch believe` appends to the ledger, `watch resolve` grades a claim yes or +no, once. + +The brief, in fixed order: -Rendering lives in `src/render/`: one `BriefDocument` model plus a renderer per -medium (`terminal.py`, `html.py`, `markdown.py`, `email.py`). The live pipeline path -builds the same document and uses the same renderers, so there is exactly one place -that decides what a brief looks like. - ---- - -## The calibration loop: staking and grading your own calls - -Every other ledger command reads. These four write, and they are what makes the graph -a calibration instrument rather than a reading list -- the thing being calibrated is -*your* judgement. - -```bash -questions add "Does CMMC Phase 2 slip past its statutory date?" --cadence 90d -predict 23 "Yes -- slips" --by 2026-12-31 --confidence 0.7 -forecast --due -resolve 41 --outcome no --note "DFARS class deviation published 2026-11-14" ``` - -All four are local database work: no `ANTHROPIC_API_KEY`, no network call. The loop is -`forecast --due` (what is due right now, at each question's own speed), grade what -resolved, read the diff on whatever came up for review, stake anything new. **The brief -is optional to that loop** -- ingestion is the fragile half, and the ledger should keep -working on a week where the sources returned nothing worth reading. - -**A date and a confidence are required, and rejected at entry.** Nothing is stored -without them. The tool's first 33 predictions were graded zero times: 25 were phrased -"X would signal Y" -- an interpretation rule, which cannot be wrong -- and only 3 -carried a date, so 19 aged out unjudged. A claim with no resolution date can never come -due. There is no confidence default either; an unstated confidence is a non-commitment -in a different costume. - -**A cadence is not a deadline.** A question's `--cadence` says how often it is worth -re-examining; a prediction's `--by` says when a specific claim resolves. A question -reviewed quarterly can hold a claim resolving in three weeks. `forecast --due` tests -each question against its *own* interval -- a 7d question and a 90d question come due -independently -- and **stamps a question as reviewed whether or not anything moved**, -because a quiet question that reappears every day trains you to skim. - -**`predictions track-record` counts your predictions only.** The model's are reported -under a separate heading and never folded into the figure; a hit rate that blends the -two measures nothing. Nothing auto-resolves from coverage: a tool that grades its -operator's calls using the corpus that produced them is measuring agreement with itself. - -Schema: `questions.cadence`, `questions.last_reviewed_at`, and -`predictions.author | due_by | confidence | outcome`, added by -`python -m src.database.migrations.add_calibration_loop` (reversible; the downgrade -refuses rather than misattributing an operator claim). Commands live in -`src/cli/stake.py`, `src/cli/questions.py` and `src/cli/forecast.py`; interval -arithmetic in `src/utils/cadence.py`. - +BRIEF AS OF 2026-08-24 06:00 +window: since 2026-08-17 06:00 +position: reviewed 2026-08-01 (23 days ago) +sources: 4 configured, 3 fetched, 1 failed, 0 never fetched (--verbose for every source) +* Broken Feed: LAST ATTEMPT FAILED 2026-08-24 06:00: HTTP error: connection refused; 0 in window + +MOVED +----- +* nist-site-rules-loosen: NIST relaxes the conduct rules at its sites before the visit is scheduled. + * supports 0.80 2026-08-21 Federal Register - Documents API: Traffic and Conduct on the Grounds of Certain National Institute of Standards and Technology Sites [sha256:841e04c37028, claude-v1] (+1 near-duplicate) + * also supports 0.80 2026-08-21 Compliance Weekly: Traffic and Conduct on the Grounds of Certain National Institute of Standards and Technology Sites [sha256:8f54b09130d9, claude-v1] +* opm-benefit-forms-change: OPM reopens comment on the retirement benefit application forms. + * supports 0.55 2026-08-20 Federal Register - Documents API: Submission for Review: 3206-0156, Application for Death Benefits Under the Civil Service Retirement System, (SF 2800); Documentation in Support of Application for Death Benefits When Deceased was an Employee at the Time of Death, (SF 2800A) and Applying for Death Benefits Under CSRS Pamphlet, (SF 2800-1) [sha256:c2fcbdff3a66, claude-v1] + +DUE --- - -## Beats: briefing a subject instead of a person - -The user profile models *you* -- a location, a profession, a voting context. A **beat** -models a *subject*: a standing topic with its own sources. Both coexist, and the -person path is unchanged. - -```bash -insightweaver brief --beat us-public-sector-compliance -``` - -A beat lives in `config/beats/.json` and selects its feeds through the same -`applicability` tags (`scope` / `geo_tags` / `domain_tags` / `specialty_tags`) that -`config/feeds/` already uses: - -```json -{ - "name": "us-public-sector-compliance", - "sources": [ - { "adapter": "rss", "feed_tags": ["regulatory", "federal_policy"], "geo_tags": ["usa"] } - ], - "coverage": { - "orgs": [{ "name": "CISA", "aliases": ["Cybersecurity and Infrastructure Security Agency"] }], - "programs": ["FedRAMP 20x", "CMMC"], - "document_types": [{ "name": "Binding Operational Directive", "aliases": ["BOD"] }] - }, - "standing_questions": [ - "Does CMMC Phase 2 slip past its statutory date?", - "Which CSPs move to FedRAMP authorized, and at which impact level?" - ], - "channels": ["terminal"] -} -``` - -A beat's brief is drawn only from that beat's sources, renders through the same -`BriefDocument` as every other brief, and accumulates its own slice of the graph: -its Questions and Predictions are kept apart from the default brief's, so a -returning question's run number means "the Nth time *this subject* raised it". - -### Standing questions - -`standing_questions` is what makes the output a brief rather than a digest. A -question there is *declared*, not discovered: the beat carries it whether or not -this week's coverage mentions it, and every run reports what moved against it. - -``` -STANDING AGENDA -What this beat declared it is watching. Unmoved items are reported, not dropped. - - [MOVED] Does CMMC Phase 2 slip past its statutory date? - Q1 (declared 2026-08-26, run 2) - Moved in: Situation 1: DoD signals CMMC Phase 2 timeline pressure[3] - Watching for: A DFARS class deviation naming CMMC Phase 2 -- published before the statutory date - - [NO MOVEMENT] Which CSPs move to FedRAMP authorized, and at which impact level? - Q2 (declared 2026-08-26, never moved) - No coverage this run bore on this question, and none ever has. -``` - -The second entry is the whole point: **"no movement on CMMC Phase 2 this week" is -itself information**, so a quiet standing question is reported as unmoved rather -than dropped as an empty section. Declared questions are still bound to coverage -by the same matcher emergent questions use, but on a tighter threshold, because a -standing question that falsely reads "moved" is worse than one that misses a -match. Nothing is auto-generated and nothing is auto-retired: the agenda is the -human's. See `docs/CONCEPTS.md`, "Standing questions", for the binding rule. - -The ledger commands read the same way. `questions list`, `predictions`, and -`forecast` show your own ledger by default and never surface a beat's rows; -pass `--beat NAME` to read that subject's instead: - -```bash -insightweaver questions list --beat us-public-sector-compliance -insightweaver predictions track-record --beat us-public-sector-compliance -insightweaver forecast --beat us-public-sector-compliance -``` - -`questions show ` and `questions resolve ` are addressed by id, so they -stay global and disclose which ledger the row belongs to. -Run attribution lives in the `beats` and `beat_runs` tables -- no existing table -grew a `beat_id` column. See `docs/CONCEPTS.md` for the scoping rationale and for -what stays deliberately global (the decision journal, the frame glossary). - -RSS was the only adapter until 2026-08-26, and the first beats were thin because -of it. See "Source adapters" below for what changed. - -### Institutional activity - -The `coverage` block names the **institutions** a beat tracks: organizations, programs -and document types. Each run counts how many items mention each one and the brief -reports what departed from its trailing average, not a tally: - +* decision schedule-site-visit: Schedule the NIST site visit before or after the conduct rule changes (2026-09-10, 17 days) + * stake: Two travel days and the assessor's calendar, against a visit under rules that change mid-stay. +* watch nist-site-rules-loosen: NIST relaxes the conduct rules at its sites before the visit is scheduled. (expires 2026-09-15, 22 days) + +WATCHING +-------- +* dfars-cyber-reporting: belief 0.20 (file, 2026-08-24); serves renew-authorization; expires in 160 days; evidence in window 0, last never + * DFARS adds a cyber incident reporting collection before the renewal. +* nist-site-rules-loosen: belief 0.30 (file, 2026-08-24); serves schedule-site-visit; expires in 22 days; evidence in window 2, last 2026-08-24 + * NIST relaxes the conduct rules at its sites before the visit is scheduled. +* opm-benefit-forms-change: belief 0.50 (file, 2026-08-24); serves renew-authorization; expires in 219 days; evidence in window 1, last 2026-08-24 + * OPM reopens comment on the retirement benefit application forms. + +QUIET +----- +watches with nothing routed inside their staleness window: 1 +* dfars-cyber-reporting: never routed (alert after 7 days) +sources that ran in the window and returned nothing: 1 +* Agency Newsroom (never produced) +routed pairs no adjudication has answered: 0 +failed adjudications in the window: 1 +* sha256:ebf02a3e9ea4 / opm-benefit-forms-change [claude-v1]: Model declined the request (category: scripted) ``` -INSTITUTIONAL ACTIVITY -Movement against each entity's trailing average. A count is an observation, not a measure of significance. - - FedRAMP PMO appeared in 4 items this run, against a trailing average of 0. - CISA appeared in 0 items this run, against a trailing average of 1. - GSA appeared in 1, unchanged. -``` +That is `tests/brief/golden/brief.txt`, whole, which the suite regenerates only through +`make golden` so that a change to the brief is a diff a reviewer reads. + +## The model + +Two hand-authored files, kept in a private repository and pointed at by `POSITION_PATH` and +`WATCHES_PATH`, are the whole input the operator writes. `config/position.example.yaml` and +`config/watches.example.yaml` show the shape. + +- A **Position** is the decisions being carried. A decision has a key, a name, a deadline and a + stake. A decision without a deadline is an interest, and the loader refuses it. +- A **Watch** is one pre-registered claim serving one decision: the claim, the operator's belief + at registration, why it matters to that decision, structured triggers, an expiry, and how many + days of silence should be reported. Triggers are a list of clauses over `terms`, `entities` + and `sources`; within a clause every populated field must match, across clauses any one + firing is enough, and a trigger that cannot be compiled is refused rather than stored. +- An **Observation** is one thing a source published, keyed by a content hash, immutable once + written, with a MinHash signature so near-duplicates from different outlets group as one + story. +- A **Route** links an observation to a watch by the clause that fired. Deterministic, + rebuildable, no model. +- An **Adjudication** is one model call about one routed pair, whatever it answered, with its + audit id and token cost. **Evidence** is the subset that bore on the claim: direction, + magnitude, prompt version. Evidence is derived; `replay` rebuilds it for a prompt version + and diffs it against what is stored. +- The **belief ledger** is append-only. The file's belief is the prior; every later value is + the operator's, with a note. **Resolution** is the operator grading the claim yes or no. + A watch removed from the file is retired, never deleted, because history hangs off it. +- A **brief** is a derived view. A row per render sets the next brief's default window to the + last brief before today, so a second run the same morning reproduces the first. + +`docs/CONCEPTS.md` has the entity-by-entity reference. + +## Six invariants + +Each is a test, not a convention. + +1. **Nothing sends.** No email, no webhook, no listener. The one outbound call is to the model + API, and every payload that leaves is in `data/llm-audit/` first. +2. **Every watch names a decision.** A watch whose `so_what.decision` is not a key in the + Position is refused. +3. **Observations are immutable; evidence is derived.** An update to an observation raises in + the ORM and is refused by a database trigger. Evidence can be deleted and rebuilt, per prompt + version, by `replay --commit` and nothing else. +4. **One stochastic component.** Adjudication is the only model call. Routing before it and + the brief after it are pure functions of the database. +5. **Silence is distinguishable from breakage.** The header and QUIET sections, above. +6. **The system never authors watches.** There is no `watch add`; the file is the only way a + watch reaches the table, and the onboarding skill transcribes what the operator says. + +## Commands + +| command | does | +|---|---| +| `auth set / status / clear` | the Anthropic key in the OS keychain; never printed, never in `.env` | +| `sources list / show` | configured feeds and what each has contributed | +| `ingest [--since] [--source]` | every configured source; per source: fetched, inserted, unreachable, went silent | +| `watch sync / list` | file to table; retire, never delete | +| `watch believe ID P --note` | append an operator belief | +| `watch resolve ID --outcome yes/no --note` | grade a claim, once | +| `route [--since] [--dry-run] [--rebuild]` | link candidates; report the unrouted clusters | +| `adjudicate [--dry-run] [--limit]` | one structured call per pending pair; `--dry-run` prints what would be sent | +| `replay --prompt-version V [--against] [--adjudicator] [--limit] [--commit]` | rebuild evidence and diff it; writes only with `--commit` | +| `brief [--since] [--as-of] [--format] [--output] [--dry-run]` | the document | +| `run` | ingest, route, adjudicate, brief, stopping at the first failure | + +## Sources + +Input arrives through the adapter layer in `src/sources/`: RSS and Atom feeds from +`config/feeds/`, and the Federal Register documents API filtered server-side by +`config/sources/federal_register.json`. Every adapter emits the same normalized item and +stores it through one path, so routing, adjudication and the brief do not know adapters exist. +An adapter that cannot reach or cannot understand its upstream raises; it never returns an +empty list, and a 200 that carries no feed is an error, not a quiet day. + +Which sources may be retrieved at all, and on what basis, is recorded in `SOURCES.md`. A source +with no recorded basis does not ship. + +## Privacy and safety + +- The API key lives in the OS keychain (`insightweaver auth set anthropic`). There is no + environment fallback. +- Every model request is written, in full, to `data/llm-audit/` before it is sent, and each + response's usage and stop reason after; one JSONL file per day. Keep that directory, and the + database, out of cloud-synced folders; `LLM_AUDIT_DIR` and `DATABASE_URL` move them. +- The Position and watch files name real decisions and deadlines. They live outside the + checkout, and `.gitignore` refuses them at the root and under `config/`. +- Nothing listens on any interface and nothing writes to an external service. The pre-commit + hooks and CI scan for secrets. + +## What is deliberately not built + +Recorded in `docs/PLAN.md`, section 8, each with what would bring it back: a belief update rule +(the operator moves beliefs; auto-updating one without resolved watches to calibrate against +would be inferring calibration that doesn't exist), a synthesis pass over the brief, sensors +beyond published sources, an MCP server, and any integration that writes anywhere. + +## Development -A flat count would be noise -- these are the entities that appear most days. Matching is -deterministic word-boundary alias matching with no model call, because a count a model -produced is not reproducible tomorrow and an unreproducible baseline cannot support a -delta. Expect it to look uninformative until several runs have accumulated. - -**There is no person kind and no persons table.** `kind` is `org`, `program` or -`document_type`; a `coverage.people` key is rejected by the loader with an error rather -than ignored. Personnel rotate and offices persist, so tracking `FedRAMP PMO` survives a -staffing change while tracking a name goes silently dark on reassignment and the absence -reads as inactivity. A named individual may appear inside a rendered situation where the -source document names a signatory -- an attribute of a document, which expires with it -- -but never as a stored row, which would accumulate. See `docs/CONCEPTS.md`. - -### Coverage probes: can the beat actually see its domain? - -Added 2026-08-27. An article count tells you ingestion is *running*. It does not tell -you ingestion *reaches the domain*, and the two were conflated once already: a beat -resolving hundreds of Federal Register documents missed the reinstatement of the -FedRAMP director, because a personnel change is not a document. The corpus held three -incidental FedRAMP mentions across 50,983 articles and none within two weeks. Every -volume number was green. - -A **coverage probe** is the test that catches it: name something that actually happened -in this domain, then check whether the beat can see it. - -```json -"coverage_probes": [ - { - "date": "2026-08-24", - "what": "FedRAMP director reinstated", - "terms": ["FedRAMP"], - "any_of": [["director", "administrator"], ["reinstat*", "return*", "restored"]] - } -] ``` - -```bash -insightweaver beat coverage us-public-sector-compliance +python -m venv .venv && source .venv/bin/activate +make install-dev # dependencies, editable install, pre-commit hooks, into the active interpreter +make db-init # every table a fresh database lacks +make check # ruff, mypy, pytest +make golden # regenerate the brief's golden files; read the diff ``` -``` -[MATCHED] OPM issued corrections to its final rules on reduction-in-force appeals - event 2026-08-25 | window 2026-08-11 .. 2026-09-08 - 4 matching article(s); earliest shown - seen by Federal Register - Documents API (2026-08-25) - Suitability Action Appeals; Correction - -[UNMATCHED] FedRAMP director reinstated - no article from this beat's feeds matched - closest article lacked: FedRAMP - and no feed anywhere in the corpus carried it either. - -2 matched + 1 unmatched + 1 inconclusive of 4 probe(s) declared -``` - -`terms` must all appear in one article; each `any_of` group needs one member. The two -levels exist because `FedRAMP` alone is too weak to be evidence -- an AWS region-launch -post mentions it -- while an exact headline is too brittle to survive a second outlet's -phrasing. A probe resting on one bare term is **rejected by the loader**, not accepted: -a probe that passes on generic terms manufactures the confidence this command exists to -remove. - -Matching is deterministic word-boundary matching, no model call. That anchoring is what -makes a match evidence: of 54,044 articles stored on 2026-08-27, 657 titles contain the -substring `nist` -- "administration", "minister", "Afghanistan", "communist" -- and four -are about NIST. A trailing `*` marks a stem (`reinstat*` matches "reinstatement"); the -marker is explicit rather than inferred so the widening is visible to whoever has to -trust the result. - -The command reports **which feed carried each match**, because "your expected source -carried it" and "an unrelated outlet mentioned it in passing" are different findings -with different repairs. An unmatched probe is re-checked across the whole corpus, so the -output distinguishes "nobody had it" from "feeds you do not subscribe to had it". - -It exits non-zero so it can gate: `1` if any probe is unmatched, `2` if nothing could be -measured. A probe whose window predates the corpus is `INCONCLUSIVE` -- neither pass nor -fail -- and stays in the denominator, because a probe set that quietly decays to the -events still in retention is a green light that means nothing. That is also why an -all-inconclusive run and a beat with no probes both exit `2` rather than `0`. - -Reads the article corpus only. No API key, no network, and it never writes. - -Running your first beat needs the two beat tables, plus one each for institutional -activity and standing questions: - -```bash -python -m src.database.migrations.add_beats # or: insightweaver brief setup -python -m src.database.migrations.add_beat_entities -python -m src.database.migrations.add_standing_questions -``` - -All are additive and reversible (`... down`). Until you run `add_beats`, `--beat` -stops with a clear error naming what is missing, and every other command -- -including plain `insightweaver brief` -- carries on exactly as before. Without -`add_beat_entities` a beat brief still runs and simply has no activity section; -`add_standing_questions` is required before a beat that declares an agenda will -run, because a declared question that cannot be recorded must not be silently -dropped. - ---- - -## Source adapters: ingestion beyond RSS - -Added 2026-08-26. The `us-public-sector-compliance` beat resolved eight RSS feeds -and only two of them carried any articles at all -- 346 of 50,983 in the corpus. -The regulatory sources that matter most (CISA advisories, Federal Register public -inspection, the White House, the Department of Education) returned zero rows. -The domain does not publish enough usable RSS to support a brief. - -`src/sources/` fixes that without touching the pipeline. An adapter answers one -question -- "what has this upstream published since ``?" -- and answers it -in the same normalized article row `src/rss/fetcher.py` has always produced. -Clustering, frames, questions, predictions and synthesis are unaware adapters -exist. - -| Adapter | Reads | -| --- | --- | -| `rss` | Any RSS or Atom feed. The default for every source in `config/feeds/`. | -| `federal_register` | The Federal Register documents API, filtered server-side by the named queries in `config/sources/federal_register.json`. | - -Three properties are the point of the layer, and each is tested rather than -assumed: - -- **Unreachable is not empty.** An adapter that cannot reach or cannot - understand its upstream raises; it never returns an empty list. An empty list - means "reachable, nothing new". -- **A source that goes quiet says so.** An adapter returning zero items when it - has produced articles before logs an error and the brief prints a - `SOURCE ALERT` banner. A thin brief with no stated cause is the failure this - layer exists to prevent. -- **Identity is content, not URL.** The same Federal Register document is - reachable at several URLs, so items are keyed by a content hash. Re-running an - adapter over unchanged upstream content inserts zero new articles. - -Which sources may be retrieved at all, and on what basis, is recorded in -[`SOURCES.md`](SOURCES.md). A source with no recorded basis does not ship. - -To add a source that is not RSS: give its `config/feeds/` entry an `"adapter"` -key, register a factory in `src/sources/runner.py`, add its row to `SOURCES.md`, -and add the adapter name to `SUPPORTED_ADAPTERS` in `src/config/beats.py` so a -beat can select it. - ---- - -## Observations, Evidence, and replay - -Added 2026-08-31 (`backlog/014`). Adjudication -- deciding whether an item bears -on a pre-registered Watch -- is the only stochastic component in the system. -Everything either side of it is deterministic and unit-testable. This layer is -what makes the stochastic part reviewable: hold the inputs fixed, change the -prompt, and diff the outputs. - -**Observations are immutable and content-addressed.** An observation is one -thing a source published, keyed by a SHA-256 hash of the normalized adapter -output. Nothing per-fetch is in the hashed payload -- not the fetch time, not a -session id -- so re-fetching an unchanged document is a no-op rather than a -second row. Once written, a row cannot be changed: an ORM update raises -`ObservationIsImmutable`, and a `BEFORE UPDATE` trigger refuses an `UPDATE` -issued from anywhere else, including the `sqlite3` shell. - -**Evidence is derived, and every row records the prompt version that produced -it.** `evidence` links `(observation, watch)` with a direction and a magnitude. -The `prompt_version` column is per row, not per run, so "where did this -judgement come from" is answerable six weeks later. - -```bash -# Rebuild v2's evidence and diff it against what v1 stored. Writes nothing. -insightweaver replay --prompt-version v2 --against v1 - -# Re-run v1 against its own stored rows. An empty diff is the reproducibility check. -insightweaver replay --prompt-version v1 - -# Persist. --commit is required; a replay that wrote by default would destroy -# the before-state at the moment you wanted to compare against it. -insightweaver replay --prompt-version v2 --commit -``` - -Replay needs no `ANTHROPIC_API_KEY`. The adjudicator is a plug-in seam -(`src/evidence/adjudicator.py`); the adjudication prompt itself is a later task, -and the only version this build ships is `null-v0`, which returns no verdicts. -An adjudicator that guessed a direction from a keyword match would put -fabricated judgements into the table whose whole purpose is to make judgements -reviewable. - -**Near-duplicate detection.** Two feeds carrying the same wire story with -different boilerplate have different content hashes, correctly. A MinHash -signature over 5-word shingles is written beside each observation and groups -them: `settings.near_duplicate_threshold` (default 0.7, `NEAR_DUPLICATE_THRESHOLD`) -is the tunable. Measured on two real corpus pairs, a genuine near-duplicate -scores 0.89 and the hardest distinct pair 0.016. - -**`observations` versus the 55,249-row `articles` table.** They coexist, with one -stated rule: `articles` is the pre-rewrite archive and keeps the row shape the -older code reads; `observations` is authoritative for everything built from task -014 onward. Exactly one code path writes an observation -(`src/sources/observation.py`, called from the adapter store path), and each new -article gets an observation in the same transaction, linked by -`observations.article_id`. The pre-existing rows have no observation and are not -migrated -- the hash is a pure function of columns they already carry, so a -backfill is mechanical and is left to its own task. - -Create the tables with `make db-add-observations` (additive; it does not touch -`articles`). - ---- +`CONTRIBUTING.md` has the workflow; `backlog/` holds one task file per change, with its +acceptance, its out-of-scope and its landmines, and `docs/PLAN.md` is the plan they implement. ## Requirements -- Python 3.10+ -- Anthropic API key -- Internet connection -- ~100MB disk space - ---- - -## Contributing - -See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. - ---- +Python 3.11 or newer, an Anthropic API key, and network access for `ingest` and `adjudicate`. +Everything else runs offline, including the whole test suite. ## License -See [LICENSE](LICENSE) for details. +See `LICENSE`. diff --git a/SOURCES.md b/SOURCES.md index d0de999..ae90e73 100644 --- a/SOURCES.md +++ b/SOURCES.md @@ -20,7 +20,7 @@ operator gets actual counsel before anything publishes. | **Intergovernmental org** | Public-information output of an intergovernmental organization, retrieved through its own published feed. | | **Publisher RSS** | A feed the publisher chose to publish. Offering an RSS feed is an explicit syndication offer for headline, summary and link. It is **not** a licence to republish full text, and InsightWeaver does not: it stores what the feed served and produces analysis over it. | | **Publisher RSS — personal use only** | A publisher's own feed, offered on terms that limit use of the feed to personal, non-commercial purposes and ask for attribution. Retrieval and analysis for the private brief are expressly permitted; the licence does **not** reach a published product, and doing so needs the publisher's written permission first. Added 2026-08-27 for the Government Executive Media Group titles, whose terms grant the feeds explicitly and narrowly. | -| **Commercial wire** | Associated Press and Reuters. Their terms are restrictive about derivative works and redistribution. **They may remain in the personal brief, which is private use. They must not be selected into a beat whose output is published.** | +| **Commercial wire** | Associated Press and Reuters. Their terms are restrictive about derivative works and redistribution. **They may remain in the personal brief, which is private use. They must not feed anything that is published.** | ## Rules this file encodes @@ -40,13 +40,12 @@ operator gets actual counsel before anything publishes. over a secondary one covering the same fact is correct. Preferring primary sources *as a category* leaves the beat unable to see anything that is not a published document. See `backlog/009-federal-it-trade-press.md`. -2. **Commercial wire content must not feed a beat intended for publication.** AP and Reuters are +2. **Commercial wire content must not feed anything intended for publication.** AP and Reuters are tagged `general_news` / `international` in `config/feeds/core.json` and carry no `regulatory`, `federal_policy`, `legislative`, `judicial` or `cybersecurity` tag, so the - `us-public-sector-compliance` beat's tag selectors do not reach them. This is asserted by - `tests/config/test_beats.py::test_resolves_to_a_small_us_federal_feed_set`, which fails if - either wire is ever pulled into that beat. If a future beat's selectors do reach them, exclude - them explicitly and record the reason here. + `us-public-sector-compliance` beat's tag selectors do not reach them. The beat that selected sources and the test that asserted this were deleted on + 2026-08-31 (backlog task 012); the rule stands and nothing publishes today. If a published + output is ever built, exclude them explicitly and record the reason here. 3. **No HTML scraping adapters exist yet, and none may be added without following this file's rules.** When they land: honour `robots.txt`, identify the client honestly in the User-Agent with a contact URL, rate-limit conservatively, and never route around an access control. @@ -63,8 +62,9 @@ operator gets actual counsel before anything publishes. *Federal-IT trade press — the detailed basis* below. **Every licence claim there carries the URL it was read at, the date, and whether it was confirmed by retrieving that URL**, because a quoted licence term with no traceable source is the same defect as a synthesis claim with no - citation — and `src/prompts/ANALYSIS_RULES.md`, injected into every synthesis prompt, already - requires that a single-source claim "name the source explicitly". Hold a licence claim in this + citation. (The analysis rules that required a single-source claim to name its source went with + the deleted synthesis product on 2026-08-31; the adjudication prompt in `src/evidence/prompt.py` + keeps the rule that a claim the item does not address is not evidence.) Hold a licence claim in this file to the standard the tool holds its own output to. Rejecting a source on its terms is a normal outcome, and the absence of a source from this file's table is not evidence that nobody looked at it. diff --git a/backlog/015-tier1-deterministic-routing.md b/backlog/015-tier1-deterministic-routing.md index 7e4a2f1..23dc28b 100644 --- a/backlog/015-tier1-deterministic-routing.md +++ b/backlog/015-tier1-deterministic-routing.md @@ -2,6 +2,7 @@ REPO: InsightWeaver STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED SIZE: medium +RESCOPED: Rescoped 2026-09-22 into estate Phase 1d (docs/PLAN.md, section 5): the trigger clause vocabulary gains a `grid` axis evaluated against grid state, and the CLI name is `estate route --dry-run`. Everything else here stands. ACCEPTANCE: `make check` passes, plus: each Watch's triggers compile to a deterministic predicate over entities, terms and source allowlists, with **no LLM call anywhere in this tier** -- proved by a test that removes the Anthropic client and drives the full routing path; word-boundary matching is used throughout and reuses `src/context/entity_matcher.py`'s primitives rather than a second implementation; `insightweaver route --dry-run` reports, per watch, how many of the last N observations would route, and reports the **unrouted count and its clusters**; routing is idempotent -- the same observation routed twice produces one link; a test asserts that a corpus of 1,000 observations against 5 watches routes fewer than a stated ceiling, so a regression that widens routing fails rather than merely costing money; and the unrouted cluster output is written somewhere task 021 can consume it. OUT OF SCOPE: Adjudication -- routing decides *candidacy*, not whether something is evidence. Any change to what the adjudication prompt says. Proposing watches from unrouted clusters; that is task 021, and this task only has to make the signal available. Tuning the shipped watches' triggers. Belief updates or state transitions. LANDMINES: **This tier is the cost control, and a routing predicate that is too loose does not fail -- it bills.** The ceiling test exists because "most observations match nothing and die here" is an architectural claim that needs a number attached or it decays silently. **Word boundaries are load-bearing and the repository has already been bitten**: of 55,249 articles, 5,364 contain the substring `nist` and 73 match it at a word boundary; `mail` is 1,842 versus 339. Task 010 also found that a boundary test can pass for the wrong reason -- its shouted-term cases were rejected by case-sensitivity before the anchors were consulted, so the class passed with anchoring deleted from the codebase. Any boundary test written here must be verified by stripping `LEFT_BOUNDARY`/`RIGHT_BOUNDARY` and confirming it fails. **The unrouted count is the coverage-gap signal and is the only place a missing sensor becomes visible before a staleness alert fires**; logging it as a bare integer with no clustering makes it useless. `main` is protected -- open a PR. diff --git a/backlog/016-tier2-adjudication.md b/backlog/016-tier2-adjudication.md index 129c757..51dc517 100644 --- a/backlog/016-tier2-adjudication.md +++ b/backlog/016-tier2-adjudication.md @@ -2,6 +2,7 @@ REPO: InsightWeaver STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED SIZE: medium +RESCOPED: Rescoped 2026-09-22 into estate Phase 1d (docs/PLAN.md, section 5). Task 026 already landed the audit log, usage capture, role-chosen model (Sonnet 5 for this tier) and the 1.x SDK pin, so this task starts from `output_config.format` and `messages.parse()` rather than from a parsing convention. `parse_claude_json` must not be used here. ACCEPTANCE: `make check` passes, plus: one prompt, versioned and stored with every Evidence row it produces, runs only on pairs Tier 1 routed; output is structured and validated -- is-evidence, direction, magnitude, satisfies-which-trigger, confidence -- and a response failing validation is **recorded as a failed adjudication rather than silently dropped or retried into a different answer**; the tier is the only place in the codebase that constructs a model request, proved by a test asserting no other module imports the client; `insightweaver adjudicate --dry-run` prints what would be sent and its token estimate without calling; replay from task 014 reproduces Evidence for a given prompt version; and per-run token and cost are recorded, because the repository currently has **no token accounting at all** and a cost-controlled architecture that cannot measure its own cost is asserting the property, not holding it. OUT OF SCOPE: Belief updates, trigger firing, hysteresis, state transitions -- adjudication reports what an observation *is*, and task 017 decides what it *does*. Batching or Bedrock migration; get the semantics right at one-call-per-pair first and optimise once volume is known. Prompt tuning beyond a first version that passes replay. Multiple prompts or a prompt per watch type. LANDMINES: **The model has been retired underneath this repository once already.** `claude-sonnet-4-20250514` reached end of life on 2026-06-15 and every synthesis failed for ten weeks while the CLI printed a duration and exited 0, because the exception was caught and logged. Any adjudication path must make an API failure loud at the tier boundary. **The response shape changed too**: `content[0].text` was correct when the model did not think and returns a `ThinkingBlock` now; `src/context/claude_client.py` selects text blocks by type and raises on a refusal -- reuse it, do not reimplement the extraction. **Do not add fallbacks**; `CLAUDE.md` forbids concealing problems behind them, and an adjudication that silently degrades to a default verdict is the worst possible instance -- it writes wrong Evidence that the state machine then acts on. Structured output is a request parameter, not a parsing convention. `main` is protected -- open a PR. diff --git a/backlog/018-silence-must-be-distinguishable.md b/backlog/018-silence-must-be-distinguishable.md index d7f1a3c..af207c5 100644 --- a/backlog/018-silence-must-be-distinguishable.md +++ b/backlog/018-silence-must-be-distinguishable.md @@ -2,6 +2,7 @@ REPO: InsightWeaver STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED SIZE: medium +REWRITTEN: 2026-09-22 -- for the laptop plan (docs/PLAN.md, section 2.1). The dead-man's switch and the non-SES channel are gone: the operator runs the command and sees it fail. The staleness alert becomes the brief's `unknown` section ('not observed since'); the weekly receipt becomes a header on every brief stating when each sensor and adapter last ran and returned something. The four sections below still describe what that header must contain, and the 'emitted even when every count is zero' rule still holds. ACCEPTANCE: `make check` passes, plus: a Watch routing zero Observations for `staleness_alert_days` fires its own Alert naming the watch and the decision it serves; a **heartbeat and DLQ-depth alarm reach the operator through a channel that is not SES**, so a notification-path failure is reported by a path that did not fail -- the channel is named in the PR and its failure mode stated; a weekly receipt is emitted on a fixed schedule stating watches live, alerts fired, alerts suppressed **and why**, calibration by domain, and sources that contributed nothing; the receipt is emitted **even when every count is zero**, because that is precisely when it carries information; and a test drives a fully-silent week and asserts the receipt still goes out with its zeros intact. OUT OF SCOPE: Making the receipt interesting. It is a liveness proof and an audit surface, and every feature that makes it engaging moves it back toward being a briefing -- which is the product being replaced. No summarization, no highlights, no LLM call anywhere in the receipt path. Alert grouping or silencing UI. Adapter retry policy beyond what the DLQ requires. LANDMINES: **The brief names this as the requirement most likely to be quietly dropped under schedule pressure, and it is right, because nothing breaks when it is missing.** A system with no staleness alerting works perfectly on every test and fails only by saying nothing while the operator assumes it is watching. **Sequence this alongside task 017, not after it.** The moment hysteresis exists, silence becomes ambiguous; shipping the state machine without this is the window where the failure is live. **The dead-man's switch must not route through SES.** If SES is misconfigured, suspended, or the domain's DKIM breaks, an SES-delivered "SES is broken" alert is an empty inbox -- which is indistinguishable from a quiet week, which is the exact ambiguity this task exists to remove. **The receipt must stay dull on purpose** and this will be the hardest instruction in the plan to follow, because a boring weekly email is the thing everyone wants to improve. `main` is protected -- open a PR. diff --git a/backlog/019-tier4-notification.md b/backlog/019-tier4-notification.md index 8266b0b..cc3488c 100644 --- a/backlog/019-tier4-notification.md +++ b/backlog/019-tier4-notification.md @@ -1,7 +1,8 @@ # Deliver Alerts by email, one per firing batch, each naming the decision it bears on. REPO: InsightWeaver -STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +STATUS: PARKED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED SIZE: medium +SUPERSEDED: 2026-09-22 -- the laptop plan (docs/PLAN.md, section 2.1) sends nothing: no mail, no SES, no transport. Invariant 1 tightens to 'nothing sends anything'. What an Alert carried lands in the `estate brief` output instead. ACCEPTANCE: `make check` passes, plus: **only an Alert can cause mail to be sent**, enforced by a single send function that takes an Alert and by a test asserting no other module can reach the transport; Alerts are grouped by watch into one email per firing batch; the body states what changed, what it does to the named decision, **what would have to be true for this to be wrong**, and a link to resolve or adjust the watch; SES domain verification, DKIM, and a custom MAIL FROM are configured and verified against live AWS, with the verification output in the PR rather than asserted; a dry-run mode renders the exact body without sending; and a send failure is loud and lands in the DLQ from task 018, never swallowed. OUT OF SCOPE: HTML templating beyond what is needed for a readable message; this is not a newsletter. Unsubscribe or preference management at one-user scale. Retry policy beyond DLQ. Alert silencing. Any content the model authors beyond what Tier 2 already produced -- the body is assembled deterministically from Alert fields, with no LLM call. LANDMINES: **The repository already contains a live `smtplib` send path** at `src/render/email.py:124`, reachable from `brief --format email`. Task 012 deletes it; if 012 has not landed, this task inherits an existing invariant-1 violation and must not add a second transport beside it. **"What would have to be true for this to be wrong" is the field that makes the email worth reading**, and it is the one most likely to degrade into boilerplate. It must come from the Watch's own trigger conditions -- what would move the belief the other way -- not from a template sentence. If it cannot be derived from Watch state, say so rather than shipping a constant string. **SES has a sandbox.** A new SES identity can only send to verified addresses until production access is granted, which is a support request with a turnaround -- start it early or v0 delivery blocks on it. `main` is protected -- open a PR. diff --git a/backlog/020-v0-deployment.md b/backlog/020-v0-deployment.md index 38fa162..3cd1540 100644 --- a/backlog/020-v0-deployment.md +++ b/backlog/020-v0-deployment.md @@ -1,7 +1,8 @@ # Deploy v0: one scheduled Lambda, SQLite in S3, five watches, two adapters, SES delivery. REPO: InsightWeaver -STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +STATUS: PARKED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED SIZE: large +SUPERSEDED: 2026-09-22 -- no Lambda, no S3, no schedule; the operator runs `estate observe` and `estate brief` by hand on a laptop (docs/PLAN.md, section 2.1). The three-outcome measurement table below is still the right test of the property and moves to the brief. PERSISTENCE: SQLite in S3, single-writer Lambda -- chosen on shape, not price (see backlog/022 Q1). Revisitable before deploy; the cost comparison is unverified and recorded as such. ACCEPTANCE: `make check` passes, plus: one Lambda runs the full pipeline on an EventBridge daily schedule; persistence is whatever the operator chose (see BLOCKED-ON) and the choice is recorded in the PR with its cost; **five hand-authored watches** drawn from decisions falling inside 90 days are live; two adapters run -- Federal Register API and one existing RSS set; secrets are in SSM Parameter Store, never in the image or environment; the dead-man's switch from task 018 is live and its non-SES channel verified by **deliberately breaking the mail path and confirming the alarm arrives**; and after three weeks of operation the PR is updated with the observed email count against the acceptance bar of **fewer than two per week, every one naming a decision**. OUT OF SCOPE: Multi-tier Lambda decomposition, SQS between tiers, or per-tier DLQs -- v0 is one Lambda, and the tier boundaries are enforced in code rather than infrastructure until volume justifies otherwise. Bedrock migration or batch mode. IaC beyond what one Lambda and a schedule require. Any sixth watch. Any third adapter. diff --git a/backlog/022-open-questions.md b/backlog/022-open-questions.md index 0654111..28bbf5f 100644 --- a/backlog/022-open-questions.md +++ b/backlog/022-open-questions.md @@ -34,6 +34,20 @@ one user, one daily invocation, and the concurrency it cannot handle is concurre does not have. Task 020's BLOCKED-ON is cleared; the choice is revisitable before deployment and the cost comparison remains unverified, which is recorded rather than resolved. +## ANSWERED 2026-09-22 (the estate plan) + +The operator's brief of 2026-09-22 re-expresses this plan with the estate half added; the +decisions and the fifteen questions it raised are recorded in `docs/PLAN.md`, section 7. +The ones that bear on tasks in this directory: + +- **Laptop, not cloud.** Tasks 019, 020 and 023 are superseded; 018 is rewritten for a laptop. + **Q6 below is closed as moot**: there is no mail path for a dead-man's switch to be off. +- **PIR = Watch.** No `threat` or `indicator` node types; the trigger vocabulary gains a `grid` + axis. Tasks 015 and 016 are rescoped into estate Phase 1d. +- **Belief has one ledger** (`watch_beliefs`, append-only). Task 017's transitions append to it; + the `sync_watches` delete becomes a soft retire before 017 lands. +- **Deterministic brief first**; synthesis is an opt-in pass in Phase 1e. Invariant 4 stands. + --- ## Q1 -- ANSWERED 2026-08-31: not blocking; SQLite in S3 as the working assumption, revisitable. @@ -121,7 +135,9 @@ The plan above does **not** archive any of it, and does not port it either. That gap, not an oversight -- deciding it needs your view on whether the compliance beat continues to exist as a concept under the new architecture, or whether Position + Watches replaces it entirely. -## Q6 -- Dead-man's switch channel. Blocks task 018. +## Q6 -- CLOSED 2026-09-22 as moot: no mail path exists under the laptop plan. Original text kept. + +### Dead-man's switch channel. Blocked task 018. It must not be SES. SNS to SMS, a CloudWatch alarm to a phone push, or a third-party healthcheck service that alarms on a missed heartbeat are the obvious candidates, each with a different failure diff --git a/backlog/023-the-state-feed.md b/backlog/023-the-state-feed.md index 0da537a..6bdf5d4 100644 --- a/backlog/023-the-state-feed.md +++ b/backlog/023-the-state-feed.md @@ -1,7 +1,8 @@ # A password-protected feed showing current state of every live watch, so email carries transitions and the feed carries state. REPO: InsightWeaver -STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +STATUS: PARKED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED SIZE: medium +SUPERSEDED: 2026-09-22 -- no S3, no Cognito, nothing on a network interface. 'Email carries transitions, the feed carries state' survives as `estate status` (state) and `estate brief` (transitions), both local (docs/PLAN.md, section 2.1). ACCEPTANCE: `make check` passes, plus: the weekly Lambda writes a JSON state snapshot to S3 containing every live watch with its claim, current belief, date and direction of last change, the decision it serves, days to expiry, staleness state, and its last three evidence items; a static page renders one card per watch behind an auth gate that **fails closed** -- no credential configured returns 503, never open. `silk-reeling-mirror` replaced Basic Auth with Cognito JWT in its PRs #1-#4 and **carried its fail-open fallback forward into the new implementation**, fixed in its PR #5; reuse the corrected Cognito pattern, and confirm which it is at implementation time rather than trusting this line; the page has **no scroll beyond the card list, no counts, no badges, no history stream, and no infinite anything**; a week in which nothing changed renders every card reading "no change since " and that is a complete and correct view; belief can be adjusted and a watch resolved from the page, writing back through the same path the CLI uses; and the page renders correctly with zero live watches rather than erroring. OUT OF SCOPE: Any content the feed shows that the email does not. This is the constraint that keeps it from becoming a place to browse, and browsing is the addictive property. No article text beyond the evidence items already attached to a watch. No search, no archive, no "explore", no related-watch suggestions. No engagement metrics of any kind -- not view counts, not streaks, not "3 new since your last visit". No LLM call in the render path. No server: a JSON file and a static page, nothing to compromise beyond the bucket. No mobile app. LANDMINES: **Every feature that makes this more engaging moves it back toward being a briefing, which is the product being replaced.** The pressure will not arrive as "let's make it addictive"; it will arrive as "it would be useful to also see...". The acceptance criterion "shows nothing the email does not" is the line, and it is written that way so a proposed addition has to justify itself against the email first. **Auth must fail closed and this is not theoretical**: `silk-reeling-mirror` shipped fail-open under Basic Auth, then **re-implemented auth entirely with Cognito and preserved the same hole**, because a local-dev passthrough reads as a feature rather than as a config typo away from open. Both were fixed on 2026-08-31. A rewrite is not a fix; verify this gate behaviourally with the config absent. **The snapshot contains Position-derived data** -- decisions, deadlines, beliefs -- which is more sensitive than anything currently on samaydlette.com. The S3 object must not be public-read, and the bucket must not be the site's public bucket. `main` is protected -- open a PR. diff --git a/backlog/024-setup-interview-and-quarterly-review.md b/backlog/024-setup-interview-and-quarterly-review.md index 1be9e42..5c23d87 100644 --- a/backlog/024-setup-interview-and-quarterly-review.md +++ b/backlog/024-setup-interview-and-quarterly-review.md @@ -1,6 +1,7 @@ # An interview that drafts Position, and a quarterly review loop that degrades visibly when it lapses -- the outermost loop, which sets the thresholds every inner loop steers against. REPO: InsightWeaver -STATUS: QUEUED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +STATUS: PARKED # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +NOTE (2026-09-23): the interview half is done as the `onboard` skill (backlog/032). The review loop stays parked until there are resolved watches to review; the 90-day banner it specified ships in the brief (task 031). SIZE: medium ACCEPTANCE: `make check` passes, plus: `insightweaver setup` runs a question-and-answer interview that **writes a draft `position.yaml` to a scratch path and prints it for the operator to edit and commit** -- it never writes to the live Position and never creates a Watch, so invariant 6 holds; the interview elicits decisions with deadlines, refuses to record a decision with no date, and asks for each what evidence would change it; `insightweaver review` opens the quarterly loop, showing each decision, whether it is still live, each watch derived from it with its belief history since last review, and every watch that expired or went stale in the period; completing a review stamps `position.reviewed` and **records what changed, including "nothing"**; the weekly receipt shows days since last review; past 90 days every alert email and every feed card carries a visible staleness banner naming the review date; and a test drives a review with no changes and asserts it still stamps and still records. OUT OF SCOPE: The interview authoring watches, ranking decisions, or suggesting beliefs. It elicits and transcribes; the operator decides. Suppressing alerts when review lapses -- see the reasoning below. Auto-extending expiry dates. Any calendar integration, reminder service, or notification outside the receipt and the banner. Auto-retiring a decision because its deadline passed; surface it in the review and let the human close it. diff --git a/backlog/026-estate-phase0-hygiene.md b/backlog/026-estate-phase0-hygiene.md new file mode 100644 index 0000000..04d83fa --- /dev/null +++ b/backlog/026-estate-phase0-hygiene.md @@ -0,0 +1,40 @@ +# Estate Phase 0: keychain credentials, an audited model client, secret scanning, and the plan's decisions recorded. +REPO: InsightWeaver +STATUS: IN_PROGRESS # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: small +PLAN: docs/PLAN.md (section 5, Phase 0) +ACCEPTANCE: `make check` passes, plus: the Anthropic key is read from the OS keychain through `keyring` at the moment a model client is constructed, never at import and never from `.env`, with **no environment fallback** -- a test sets `ANTHROPIC_API_KEY` in the environment, leaves the keychain empty, and asserts the client refuses; `estate auth set|status|clear` exist and `status` never prints a value; **every outbound model request is written to a local JSON-lines audit log before it is sent** and its usage after, with a test that stubs the SDK to fail and asserts the request line exists with an error line and no response line; the client returns token usage rather than discarding it; the model is chosen by role (`triage` -> `settings.llm_triage_model`, `synthesis` -> `settings.llm_synthesis_model`) and no `src/` module outside the client constructs a request, asserted against the tree; a secret scanner runs in pre-commit and in a CI job that **can fail**; the `anthropic` pin is raised to 1.x so `output_config` is a named parameter; `.gitignore` refuses the audit log, an `estate/` directory at the root and OAuth artefacts; and the decisions of 2026-09-22 are recorded in `docs/PLAN.md`, `backlog/022`, and the superseded task files. +OUT OF SCOPE: The grid, any sensor, any brief section, the `grid` trigger axis, `watch_beliefs`, and `estate` commands other than `auth` -- each is its own Phase 1 task. Structured output in the client (Phase 1d, task 016). Rewriting `README.md` / `GETTING_STARTED.md` / `docs/CONCEPTS.md` (Phase 1c). Deleting the dead top-level `migrations/` directory. Moving the database file out of the checkout. +LANDMINES: **A fallback is a second place a secret lives.** The obvious convenience is "read the keychain, else the environment", and it is exactly the thing this task exists to remove; the test that sets the env var and asserts refusal is there to make the convenience fail loudly if someone adds it. **The audit log must be written before the send, not after**, or a process that dies mid-call leaves no record that a payload left the machine. **`parse_claude_json` returns `{}` on failure**; it is a silent default and Tier 2 must not use it -- noted in `src/llm/__init__.py` rather than deleted, because deleting it is not this task's call. **`safety check || true` cannot fail the build** and never could; the secrets step is the first thing in that job that can. **The requirements files are compiled artefacts**; regenerate them with `pip-compile`, do not hand-edit the pins. `main` is protected -- open a PR. +--- +Written 2026-09-22, the day the plan was approved. + +## Why this is its own PR + +Every later phase builds on three properties this one establishes: secrets have one home, model +calls have one door and it is logged, and a leaked key cannot be committed. None of them is +interesting on its own and each is the kind of thing that gets folded into a feature PR and then +half-done. Landing them first, small and reviewable, means Phase 1a starts from a tree where the +rules are already enforced rather than promised. + +## What changed in the tree, and why each + +| change | reason | +|---|---| +| `src/estate/credentials.py`, `src/estate/cli.py` | the keychain path and the one command that writes to it | +| `src/llm/audit.py` | the log; request before send, response or error after | +| `src/llm/claude_client.py` rewritten | key from keychain, role-chosen model, `output_config`, usage returned, dead briefing-era methods removed | +| `src/config/settings.py` | `anthropic_api_key` removed; `llm_audit_dir`, two model settings, `keyring_service` added | +| `pyproject.toml`, `requirements*.txt` | `anthropic>=1.7,<2`, `keyring`, `pydantic` explicit, `detect-secrets`, `types-PyYAML`, the `estate` script | +| `.pre-commit-config.yaml`, `.github/workflows/ci.yml`, `.secrets.baseline` | scanning that can fail | +| `.gitignore`, `.env.example` | the audit log and an `estate/` directory refused; the key line gone | +| `backlog/015, 016, 018, 019, 020, 022, 023` | rescoped, rewritten for a laptop, or superseded, each with a dated note | +| `docs/RECONCILIATION.md`, `CLAUDE.md` | the estate plan is now the plan; the North Star paragraph names nodes, not questions | + +## On `types-PyYAML` + +`make typecheck` failed in a fresh virtualenv on 2026-09-22 with "Library stubs not installed for +yaml" because the stubs were only ever installed by the pre-commit mypy hook's +`additional_dependencies`. A gate that passes in one environment and fails in another is the +pattern the Makefile's tool-resolution note already corrected once; the stubs are a dev dependency +now. diff --git a/backlog/027-sweep.md b/backlog/027-sweep.md new file mode 100644 index 0000000..9cab560 --- /dev/null +++ b/backlog/027-sweep.md @@ -0,0 +1,62 @@ +# Sweep: delete what has no caller, fold `estate` into `insightweaver`, and leave one command over a tree that reads as current. +REPO: InsightWeaver +STATUS: DONE # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: small +PLAN: docs/PLAN.md (section 5, task 027; section 6 item 1 and 2) +ACCEPTANCE: `make check` passes, plus: every module, config file and fixture listed below is gone from the tree, with its own tests; no module under `src/` is unreachable from a console script, a migration, or another live module -- asserted by a test that walks imports from those roots, which lands with task 029, because on 2026-09-22 the test found fourteen modules unreachable -- the whole source, routing and model stack -- and the last of them (`src/llm/`) gains its caller only when the adjudicator exists; the `estate` console script and `src/estate/` no longer exist, `auth` is a subcommand of `insightweaver`, and credentials live in `src/config/credentials.py`; `insightweaver` with no subcommand prints help and exits rather than entering a REPL; `FeedMatcher` loads `config/feeds/` and does nothing else; `tests/conftest.py` carries no fixture that patches or describes a module that does not exist; and the mypy override list in `pyproject.toml` names no deleted module. +OUT OF SCOPE: Anything the decision monitor will add (routing, adjudication, brief). Rewriting `README.md`, `GETTING_STARTED.md`, `docs/CONCEPTS.md`, `CONTRIBUTING.md` -- task 033; they keep their superseded banners until then. Deleting `src/rss/fetcher.py` (the RSS adapter reads feeds through it), `src/matching/entity_matcher.py` (routing needs it), or the `articles` table. Changing what `config/feeds/` contains. +LANDMINES: **`deduplicator.py` was an "explicit keep" in task 012's brief.** It reads the legacy `articles` table, which tiers built after task 014 must not, and `src/sources/minhash.py` records why a stored MinHash signature superseded it: the pairwise Jaccard produced nothing storable, so a grouping computed today and after a replay could differ. The keep is overridden on that reasoning, recorded here, and the operator approved the sweep list on 2026-09-22. **`coverage_probe.py` was ported "for task 018's staleness check."** The staleness check in `docs/PLAN.md` is a query over `routes` ("nothing routed for N days"), not a probe match over `articles`; 018 as rewritten on 2026-09-22 names no probe. The word-boundary rules the probe engine relied on live in `entity_matcher.py`, which stays. **Every deletion was adversarially reviewed** by an agent per candidate instructed to find a live caller, a build step, a CI step, a packaging entry or a standing commitment; none was found. The review's own list of what the sweep missed is recorded below and folded in. **The reachability test is the thing that keeps this from recurring**: a module nothing imports fails the suite, so the next leftover is caught at the PR rather than a month later. `main` is protected -- open a PR. +--- +Written 2026-09-22, after the plan was cut to the decision monitor. + +## What goes, and why each + +| path | why | +|---|---| +| `src/processors/content_filter.py` | keyword filter keyed off the deleted `user_profile.json`; no caller | +| `src/processors/deduplicator.py` | superseded by MinHash (task 014); reads `articles`; no caller | +| `src/utils/profile_loader.py` | loads the deleted product's profile; only `feed_manager` imported it | +| `src/feed_manager.py` | profile-matched feed sync; `store.py::ensure_source` registers sources when an adapter runs, which removes the "adding a feed does not add it to the database" trap by construction | +| `src/config/feeds.py` | an 813-line Python dict of 112 feeds from 2025-09; `config/feeds/*.json` is the live configuration; no caller | +| `src/utils/logging.py`, `src/utils/profiler.py` | 0% coverage, no caller | +| `src/rss/parallel_fetcher.py` | drove `fetch_all_active_feeds`, whose write path task 025 closed | +| `src/matching/coverage_probe.py`, `CoverageProbe` in `terms.py` | see LANDMINES | +| `migrations/` (top level) | targets tables dropped in task 012; the live directory is `src/database/migrations/` | +| `config/user_profile.example.json`, `config/context_modules/`, `config/probes/` | the deleted product's profile, context and probes | +| `main.py`, `src/__main__.py` | legacy entry points; the console script is `insightweaver = src.cli.app:cli` | +| the REPL in `src/cli/app.py` | ASCII art, a 2.5-second sleep and a prefix dispatcher; a scripted command has no use for any of it | +| `data/forecasts/`, `data/newsletters/` | placeholders for deleted subsystems | +| `tests/conftest.py` fixtures `mock_claude_client`, `mock_web_fetch`, `mock_authoritative_sources`, `sample_response`, `mock_settings`, `temp_yaml_file`; `tests/utils/conftest.py` | describe or patch modules that do not exist | +| `src/estate/` and the `estate` script | folded into `insightweaver`; one command | + +`FeedMatcher.match_feeds_to_profile`, `_calculate_match_score`, `_get_default_preferences`, +`get_feed_statistics`, `get_available_tags` go with `feed_manager`; the class keeps `Feed` and the +loader. + +## What the adversarial review found that the list missed + +Fifteen refuters, one per candidate above, found no blocker. Three independent hunters (by call +graph, by product history, by coverage) then found what the list had not named. Folded in: + +| path | evidence | +|---|---| +| `src/config/feeds.py`, `tests/config/test_feeds.py` | 813-line static feed dict from 2025-09; only its own tests import it | +| `src/database/migrations/drop_forecast_tables.py`, `drop_memory_facts.py`, `drop_orphan_tables.py` | one-off drops from the pre-August stages; no Makefile target, no test, no importer; the tables they drop have no model. A database that predates those stages can still run them from git history | +| `src/config/settings.py` fields `debug`, `log_level`, `enable_smart_rss_fetch`, `smart_rss_fetch_threshold_minutes`, `logs_dir` (and its `mkdir`), `src/logs/.gitkeep`; their tests in `tests/config/test_settings.py` | no reader anywhere in `src/`: the `--debug` flag goes through `src/cli/output.py`, which never consults settings, and the logging module that read `log_level` and `logs_dir` is deleted above | +| `src/utils/colors.py` merged into `src/cli/colors.py` | the two-module split existed for a `src/render` import cycle that no longer exists; `success`, `emphasis`, `colorize_priority`, `colorize_confidence` have no caller | +| `src/rss/fetcher.py::create_test_feed` and `TestCreateTestFeed` | a development helper in production code, called only by its own tests | +| `src/database/connection.py::create_tables` and `TestCreateTables` | called only by its own tests; the models module warns against calling it | +| `tests/config/conftest.py`; the unused fixtures in `tests/rss/conftest.py` | zero consumers | +| `pyproject.toml` dependencies `aiohttp`, `rich`, `requests`, `lxml`; dev `aioresponses`; `types-requests` in the pre-commit mypy hook; the `slow`/`integration`/`unit` markers | nothing imports or uses them; requirements recompiled | +| `.gitignore` entries for `config/api_sources.json`, `/reports/forecasts/*`, `src/logs/*.log` | name things that no longer exist | + +Left for task 033 (docs), not this sweep: `README.md`, `GETTING_STARTED.md`, `CONTRIBUTING.md`, +`docs/CONCEPTS.md`, `SOURCES.md` lines that cite deleted files, and `.claude/skills/review-tests/` +whose worked examples come from a deleted test module. Left alone on purpose: the unread columns +on `articles` (it is the pre-rewrite archive and its shape is the rule), and +`src/matching/entity_matcher.py`, which has no caller until task 028's compiler. The reachability +test was built here, run, and found fourteen modules unreachable from any command: `src/sources/`, +`src/rss/fetcher.py`, `src/matching/`, `src/llm/`, `src/config/feed_matcher.py`. That is the +finding, stated plainly: the repository has had no command that ingests since 2026-08-31 and none +that calls a model since ever. The test is removed from this commit and lands with task 029, when +the last of those modules is wired to a command. diff --git a/backlog/028-ingest-and-route.md b/backlog/028-ingest-and-route.md new file mode 100644 index 0000000..9a70205 --- /dev/null +++ b/backlog/028-ingest-and-route.md @@ -0,0 +1,59 @@ +# Ingest every configured source through the adapter path, then route observations to watches with compiled deterministic predicates. +REPO: InsightWeaver +STATUS: DONE # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: medium +PLAN: docs/PLAN.md (section 4; section 5, task 028; supersedes backlog/015 as rescoped) +ACCEPTANCE: `make check` passes, plus: `insightweaver ingest` builds an adapter for **every** feed in `config/feeds/` (RSS through `RSSAdapter`, others through `ADAPTER_FACTORIES`), runs them with bounded concurrency, stores through the one adapter store path, and prints per source fetched / inserted / unreachable / went-silent, with the `SOURCE ALERT` lines the runner already produces; a `routes` table links `(observation, watch)` with the index of the first trigger clause that fired, unique per pair, so routing twice produces one link; every clause compiles through `entity_matcher.term_pattern` with its shouted-term case rule and word boundaries, `entities` compiling exactly as `terms` do, `sources` matching the source name case-insensitively, every populated field in a clause required and any clause sufficient; `insightweaver route --dry-run` reports per watch how many observations in the window would route and reports the **unrouted count grouped by near-duplicate cluster and by source**, writing nothing; **no LLM call anywhere in this tier**, proved by a test that removes `src.llm` from `sys.modules` and blocks its import while driving the full routing path; and a regression test plants twenty whole-word trigger matches and one hundred substring look-alikes in a thousand synthetic observations against five watches and asserts exactly twenty route -- a test whose docstring records that it was verified to fail with `LEFT_BOUNDARY` and `RIGHT_BOUNDARY` stripped. +OUT OF SCOPE: Adjudication (task 029). Belief, retirement, resolution (task 030) -- until then a live watch is one whose `expires` is not past. The brief (task 031). An alias registry for entities; an entity compiles as a term until a watch needs aliases, and that is its own task. Tuning any configured feed. Numeric or `series` trigger clauses. Deleting `run_configured_adapters` or `build_configured_adapters`; they gain an `include_rss` switch and keep their callers. +LANDMINES: **A routing predicate that is too loose does not fail, it bills** -- every routed pair is a model call in task 029. The planted-substring test is the gate, and it must be verified by deleting the boundary anchors and watching it fail, because task 010 found a boundary test that passed for the wrong reason: shouted terms were rejected by case-sensitivity before the anchors were consulted. Plant lower-case look-alikes for shouted terms too (`precisa` for `CISA` proves nothing; `Cisa` inside `Cisak` does). **Concurrency and SQLite.** Five adapters awaiting network at once is fine; five sessions writing at once is not what happens, because each `run_adapter` does its database work synchronously between awaits, so writes never interleave mid-transaction. Do not introduce threads. **The unrouted report is the coverage-gap signal.** A bare integer is useless; cluster it with the stored MinHash signatures and name the source, or task 032's onboarding cannot tell "no source covers this" from "the trigger is wrong". **`published_date` can be null** (feeds without dates); the window falls back to `observed_at` for those rows rather than dropping them. `main` is protected -- open a PR. +--- +Written 2026-09-22. + +## Why ingest is here and not its own task + +Task 025 closed the legacy write path and task 012 deleted the orchestrator that called it, so the +repository has had no way to grow its corpus since 2026-08-31. Routing over an empty corpus proves +nothing. The two land together so the tier can be exercised end to end on a real feed the same day. + +Every feed in `config/feeds/` is ingested. The profile-driven selection that used to pick a subset +went with the profile; curation is now editing that directory, which is what `SOURCES.md` already +says it is. `store.py::ensure_source` registers the source row the first time an adapter runs, so +the "adding a feed to config does not add it to the database" trap recorded in tasks 020 and 025 +closes by construction. + +## Clause semantics, restated so the compiler and the file agree + +A watch's `triggers` is a list of clauses. A clause may populate `terms`, `entities`, `sources`. +Within a clause, **every** populated field must match; within a field, **any** value matches. Any +clause matching routes the observation. The clause index stored is the first that matched. The text +matched is the observation payload's title followed by its `normalized_content`, or its +`description` when there is no content -- the same title and body `ObservationView` exposes to the +adjudicator as two fields, so Tier 1 and Tier 2 read the same words. + +## What the adversarial review found, and what was done + +Four independent reviewers read the uncommitted change against this file. Fixed before commit: + +- **`--rebuild` handed every unrouted observation in the corpus to the pairwise MinHash grouper**, + which its own docstring sizes for a day of ingestion (measured: 4,000 signatures take 33s and + the cost quadruples per doubling). The unrouted report now describes the window only, rebuild + or not, and above `CLUSTER_LIMIT` (2,000) it skips clustering and says so; the per-source counts + and the total are always complete. +- **The compiler stringified non-string clause entries**, so a JSON `null` in a hand-written row + became the term `None`. It now refuses them. +- **The route command read the local calendar for liveness and UTC for the window**; one clock + now, and the CLI tests freeze it, since the stub watches expire in December. +- **Three tests asserted less than their names claimed**: the clause-index test could not fail + for a router that hard-codes 0 (now a two-clause watch whose second clause fires); the + concurrency test accepted sequential execution (now `== 3`); the regression gate counted rows + (now compares the routed hashes to the planted items by identity). +- The acceptance's "grouped by source" was only half met: per-source unrouted counts added. +- Went-silent and `SOURCE ALERT` rendering, and the `include_rss=True` request, gained CLI tests. +- Stale or false prose in five docstrings and one comment (the "forty feeds" claim: there are 78). + +Deferred, recorded here rather than fixed: `src/database/models.py` is 423 lines against the +300-line rule and should be split when the next model lands; `_window` inner-joins to the source +row, so an orphaned observation (possible only by hand-deleting a feed row, since SQLite is not +enforcing the foreign key) would vanish from the window rather than fail; a `watches.triggers` +cell that is not valid JSON fails in SQLAlchemy's deserialiser with a traceback rather than a +`ClickException` (still fail-fast). diff --git a/backlog/029-adjudicate.md b/backlog/029-adjudicate.md new file mode 100644 index 0000000..623ff7a --- /dev/null +++ b/backlog/029-adjudicate.md @@ -0,0 +1,109 @@ +# Adjudicate routed pairs with one structured model call each, recording every outcome including failure, and make replay read what adjudication read. +REPO: InsightWeaver +STATUS: DONE # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: medium +PLAN: docs/PLAN.md (section 4; section 5, task 029; supersedes backlog/016 as rescoped) +ACCEPTANCE: `make check` passes, plus: a `ClaudeAdjudicator` registered under prompt version `claude-v1` implements the existing `Adjudicator` protocol and is the **only** module that constructs a `ClaudeClient`, asserted against the tree; its response is requested as structured output (`output_config.format`, a JSON schema derived from a pydantic verdict model) and validated on receipt; a response that fails validation, a refusal, or an API error is recorded in an `adjudications` row with `outcome = 'failed'` and the error text, **never retried and never coerced into a verdict**, tested with a stub that returns malformed JSON; every routed pair the model is asked about gets exactly one `adjudications` row per prompt version (`evidence`, `none` or `failed`), so `insightweaver adjudicate` run twice sends nothing the second time; each row carries the audit id and the input and output tokens, and the command prints the run's totals; `adjudicate --dry-run` prints the exact system and user text for the first N pairs and a character-based estimate labelled as an estimate, without constructing a client; `rebuild` in `src/evidence/replay.py` iterates **routed pairs** rather than the full observation x watch product, and the replay stubs route their fixture corpus through the real router so the existing replay tests keep their meaning; and the observation text sent is capped, with the cap and whether it applied recorded in the audit entry. +OUT OF SCOPE: Belief updates from evidence (none, by decision of 2026-09-22). The brief. Batching, prompt caching, or a second prompt version; get one-call-per-pair right first. Any use of `parse_claude_json`. Cost in dollars: tokens are recorded; a price table goes stale silently and the operator can multiply. +LANDMINES: **A retry that produces a different answer to the same input is what breaks replay**, so a failed call is recorded and left. **Replay against a stochastic adjudicator is not expected to be empty.** The harness's `commit` refuses when the same version disagrees with its own stored rows; for `claude-v1` that refusal is the measurement of prompt stability, not a bug, and the task file for the first replay must say what rate was observed. **The adjudicator must see only what Tier 1 routed.** The protocol passes a watch list; `adjudicate` passes the routed subset per observation and `rebuild` must do the same, or a replay silently costs more and judges pairs adjudication never saw. **`_response_text` raises on refusal and on a missing text block**; catch those at the adjudicator boundary and record them as failures, do not let one refusal abort the run. **Structured output is a request parameter, not a parsing convention** (task 016's landmine); a schema in the prompt text is not the same thing. **The SDK is 1.x**: `output_config` is a named parameter and `messages.parse` exists; do not put the schema in `extra_body`. `main` is protected -- open a PR. +--- +Written 2026-09-22. + +## The verdict schema + +```python +class AdjudicationVerdict(BaseModel): + is_evidence: bool + direction: Literal["supports", "contradicts"] | None # required when is_evidence + magnitude: float = Field(ge=0.0, le=1.0) # strength of bearing, not a probability + satisfies_clause: int | None # index into the watch's trigger clauses + confidence: float = Field(ge=0.0, le=1.0) + rationale: str # one or two sentences, citing the text +``` + +A verdict with `is_evidence=false` writes an `adjudications` row with `outcome='none'` and no +`evidence` row. A verdict with `is_evidence=true` and no direction is a validation failure. + +**As built (2026-09-22):** `direction` is the three-valued enum `supports | contradicts | none` and +`satisfies_clause` is an integer with `-1` for no clause, instead of the nullable fields above. The +structured-output grammar takes a flat enum and an integer; a nullable union would need `anyOf`, +and the flat form keeps the schema the SDK sends identical to the one a reader sees here. The +validator enforces the same rule the nullable form would have. The schema is derived from the +pydantic model at import (`api_schema`), with the range keywords the grammar rejects removed and +their ranges kept in the field descriptions; pydantic enforces the ranges on receipt. The ledger +also keeps `confidence`, `satisfies_clause` and the rationale for every validated verdict, since +`evidence` holds only evidence. + +## The prompt, in outline + +System: the role (judge one observation against one pre-registered claim), the rules that survive +from the deleted `ANALYSIS_RULES.md` for a single judgement (label what the text says, not what it +implies; default to the weaker reading; do not recommend; do not infer beyond the text; a claim +the observation does not address is not evidence), and the schema semantics above. + +User: the watch's claim, its `so_what`, its trigger clauses with indices; then the observation's +source name, published date, title and text (capped). + +The prompt is a module constant beside the adjudicator with its version string; changing the text +without changing the version is the mislabelled-corpus failure task 014 was built to prevent, so a +test hashes the prompt constant and pins the hash to the version. + +## What the adversarial review found, and what was done + +Four independent reviewers read the uncommitted change against this file. Fixed before commit: + +- **A missing keychain entry was recorded as a permanent failure on every pending pair**, with no + call made, and the command exited 0. The client is now built before the first pair and outside + the recording path; a missing key raises with nothing written. The same rule covers a request + the API rejects (400, 401, 403, 404): `ModelCallFailed.misconfigured` aborts the run at the pair + it hit, earlier answers kept. +- **An interrupted run lost every answer it had paid for**: rows were flushed, never committed. + Each pair commits as it is answered; the pair in flight under Ctrl-C is re-asked, and the + module docstring says so. +- **The hand-written schema carried `minimum`/`maximum`**, which the grammar rejects, and could + drift from the model. It is derived from the model with those keywords stripped. +- **A refusal or API error wrote a ledger row with no audit id and zero tokens** although the + audit log had both. The client's failure is typed and carries them. +- **`max_tokens` of 2000 capped thinking and answer together**; a reply cut off there was recorded + as a JSON error. It is 16000 now and a `max_tokens` stop is recorded as what it is. +- **Adjudication and replay read different pair sets** (one filtered by expiry, one did not). + Expiry is Tier 1's gate at routing time; both tiers now read exactly the routed pairs. +- **`adjudicate` after `replay --commit` crashed** on the evidence unique constraint; a pair with + committed evidence now counts as answered. **`replay` over an unrouted corpus** read as "no + evidence" and would have deleted the version's rows with `--commit`; it now refuses and names + the fix. `replay --limit` counts routed observations, so a bounded model replay judges something. +- The truncation test was a tautology; it now checks the sent body. `--limit 0` is refused. + `satisfies_clause` beyond the watch's clauses is a validation failure. The prompt's stake heading + was reworded to state the record rather than frame urgency. Docstrings that still cited task 016 + were corrected. + +Recorded, not changed: the SDK resends an identical request up to twice on a 429 or 5xx, below the +never-retried rule, and the audit log records the request once. The replay path aborts at the +first failed pair by design (it has no ledger). The tree-grep gate for "only the adjudicator +constructs a client" matches the literal token and is a guard against habit, not an adversary. +`src/database/models.py` is 480 lines and is split in task 030. Live acceptance of the derived +schema is unverified from this machine: the first real run is the test, and if the API rejects the +schema the run stops at the first pair with the API's message and nothing recorded. + +## Verification follow-ups (2026-09-22, after the review above) + +A second pass tried to refute the review's fixes and found that "misconfigured" was too narrow a +classification: an outage (a connection error, a timeout, a 429, a 5xx) was neither rejected nor +answered, so the loop recorded it per pair and one bad hour would have burned every pending pair +into a permanent "failed" row. Fixed: + +- `ModelCallFailed.outcome` is one of `answered`, `rejected`, `unavailable`. The judge records + only an answered failure; the other two abort the run with the pair left pending. Only the + SDK's own `APIError` family is classified; any other exception is audited and re-raised as the + bug it is. `adjudicate` names which of the two stopped it; a keychain backend error is a + message, not a traceback. +- A reply cut off at `max_tokens` with no text block (thinking consumed the budget) is recorded + as such, not as "no text block". +- `replay --commit --limit` is refused: commit makes the stored rows equal the replay, and a + bounded replay would delete every row outside its bound. +- The prompt fingerprint now includes the pydantic model's own schema, so a change to a bound + that is stripped from the API schema but enforced on receipt moves the version. The pinned + value in the test changed accordingly; no evidence had been recorded under the old one. +- `adjudicate.py` states the one gap between the two paths: a replay judged not-evidence has no + row and is asked once more by `adjudicate`. + diff --git a/backlog/030-belief-and-resolution.md b/backlog/030-belief-and-resolution.md new file mode 100644 index 0000000..7097114 --- /dev/null +++ b/backlog/030-belief-and-resolution.md @@ -0,0 +1,60 @@ +# One belief ledger the operator writes, resolution as a human action, and retirement instead of deletion. +REPO: InsightWeaver +STATUS: DONE # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: small +PLAN: docs/PLAN.md (section 3; section 5, task 030; replaces backlog/017 and the resolution half of 021) +ACCEPTANCE: `make check` passes, plus: a `watch_beliefs` table is append-only, enforced by `BEFORE UPDATE` and `BEFORE DELETE` triggers and an ORM guard, tested from the ORM and from raw SQL; `sync_watches` writes a `source = 'file'` row when a watch is first stored or when its file belief differs from the latest ledger row, and **stops overwriting `watches.belief`**, which becomes the value at registration; `insightweaver watch believe ID P --note TEXT` writes a `source = 'principal'` row and refuses a belief outside [0, 1], a blank note, or an unknown, retired or resolved watch; `insightweaver watch resolve ID --outcome yes|no --note TEXT` sets `resolved_at`, `outcome` and `resolution_note` once and refuses a second resolution; `sync_watches` sets `retired_at` on a watch absent from the file **instead of deleting the row**, clears it if the id returns, and reports both; routing and every listing treat retired, resolved and expired watches as not live; `watch list` shows the current belief, its source and date, and the registration belief when they differ; and a test asserts no code path other than `sync_watches` and the two commands writes to `watch_beliefs` or the resolution columns. +OUT OF SCOPE: Any automatic movement of belief from evidence -- there is no update rule, no hysteresis, no debouncing; the brief groups near-duplicates and the operator moves belief. Brier or any calibration score; the brief states the resolved count and nothing else until there are enough resolutions for a score to mean something, and "enough" is a later decision with a stated denominator. Candidate watches. +LANDMINES: **This is the task where the `sync_watches` delete becomes destructive**, because history hangs off the row from here on; the soft retire must land in the same change as the ledger, not after. **A belief written by the file after the operator moved it is a real conflict**, not a merge: the ledger records both with their sources and the listing shows the latest, so the operator sees that the file is behind and fixes the file. Do not silently prefer either. **Resolution is one-way and human.** There is no `--force`, no unresolve, and no path from evidence to `outcome`; the 33 predictions graded zero times are the standing reason the grading has to be a deliberate act, and invariant 6's cousin is that the tool never grades itself. `main` is protected -- open a PR. +--- +Written 2026-09-22. + +## Why belief has no update rule + +Task 017 specified hysteresis, debouncing, N independent sources and append-only transitions. All +of it exists to let the system move belief without the operator. The decision of 2026-09-22 is +that it should not, yet: there are zero resolved watches to calibrate any rule against, and a rule +built ahead of the data is the pattern that left 25 unfalsifiable predictions in the old ledger. +What survives of 017 is its one non-negotiable: belief history is append-only and reconstructable. +The rest returns as its own task when there are resolutions to judge it by. + +## Decisions made while building (2026-09-22) + +- **A retired watch can be graded but takes no new belief.** The acceptance listed retired + watches only under `believe`; the review noticed that `resolve` refused them too, silently. + Settling a claim after dropping it from the file is an ordinary order of events, so `resolve` + accepts a retired watch; a retired watch is not being held, so `believe` refuses one. +- **Liveness is two clauses.** `live_clause(today)` (open and not expired) gates routing; + `open_clause()` (not retired, not resolved) gates adjudication and replay, which read routed + pairs and must not depend on the day they run. Expired-but-open watches keep their routed pairs + and are still judged; the asymmetry is stated in the ledger module and pinned by tests. +- **`models.py` became a package** (`src/database/models/`), one module per table family, + mechanically, when the single file passed 480 lines. Nothing about any table changed; the review + compared the generated DDL. +- **The `outcome` CHECK is a column constraint**, not a table constraint, because SQLite refuses + to drop a column a table constraint names and the migration's way down drops these columns. + +## What the adversarial review found, and what was done + +Four reviewers read the worktree against this file. Fixed before commit: + +- **The tree-scan test could not see the callers it was named for**: it matched constructors and + attribute assignments, not calls to `record_belief` or `resolve_watch` or a bulk `update()`. It + now matches all of them and allows exactly three writers by path. +- **The expiry test had no expired watch in it.** It does now, and pins that an expired watch's + routed pairs are still asked and still replayed. +- **`downgrade()` broke half-way on any table created from the model**, because the table-level + CHECK on `outcome` blocked `DROP COLUMN` after the ledgers were already gone. The constraint moved + to the column, the columns are dropped first in one transaction, the ALTER names the constraint + so a migrated table matches a fresh one, and a test downgrades a full model-built schema. +- **`replay --commit` would have deleted a retired watch's evidence**: rebuild skipped closed + watches, commit deleted every row the replay did not produce. Stored evidence is now read for + open watches only when comparing and committing; a closed watch's rows are outside the replay. +- **An orphaned ledger row crashed `watch list` and `watch sync` with a `KeyError`**; it now fails + by name. **`sync` reported `updated` for every watch on every run**, so "no change" was + unreachable; it now reports what changed. Docstrings that said "nothing else writes here" and + "three tables" were corrected; the replay report counts open watches. + +Recorded, not changed: resolution's one-way rule is enforced in Python and by the absence of any +other writer, not by a database trigger on `watches` (the plan mandates triggers for the ledger +only); a raw `UPDATE` from a shell can un-resolve a watch, as it can edit any other column there. diff --git a/backlog/031-brief.md b/backlog/031-brief.md new file mode 100644 index 0000000..1f48f45 --- /dev/null +++ b/backlog/031-brief.md @@ -0,0 +1,102 @@ +# The brief: what moved, what is due, what is watched, what went quiet, every line citing the observations it rests on, deterministic to the byte. +REPO: InsightWeaver +STATUS: DONE # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: medium +PLAN: docs/PLAN.md (section 4; section 5, task 031; absorbs backlog/018 as rewritten) +ACCEPTANCE: `make check` passes, plus: `insightweaver brief [--since] [--as-of] [--format terminal|md] [--output PATH]` renders five parts in fixed order -- header, MOVED, DUE, WATCHING, QUIET -- and every evidence item prints its observation hash, source, published date, title, direction, magnitude and prompt version; evidence in MOVED is grouped by MinHash near-duplicate cluster so one story from twelve outlets is one item with twelve citations; QUIET names every live watch with nothing routed for its `staleness_alert_days` with the date of its last routed observation or "never routed", every source that ran in the window and returned nothing, and every failed adjudication, **and prints those headings with zeros when there is nothing**; the header states `as_of`, the window, the Position's `reviewed` date with days since and a banner past 90 days, and each source's last successful fetch; the rendered bytes are a pure function of the database, `--since` and `--as-of`, asserted by rendering twice; `--since` defaults to the `as_of` of the most recent brief delivered before the start of `as_of`'s day, else seven days, so a second run the same morning reproduces the first; a `briefs` row is written per render unless `--dry-run` is given; `insightweaver run` chains ingest, route, adjudicate and brief and stops at the first that fails; and an end-to-end test drives recorded RSS and Federal Register fixtures through ingest, route, a stub adjudicator and the brief, comparing against a committed golden file. +OUT OF SCOPE: Synthesis or any model call in the render path. Colour, boxes, or terminal width handling beyond plain text and markdown. Email, HTML, or any delivery. Calibration figures. Anything the brief would show that the data does not contain. +LANDMINES: **A brief that looks the same when nothing happened and when the pipeline is broken is the failure this whole design exists to prevent** (invariant 5). The header's source-by-source line and the QUIET section are the receipt task 018 specified; they are the parts most likely to be cut for tidiness and must not be. **Determinism is a test, not a hope**: no wall-clock reads inside rendering, no unordered iteration over dicts or query results, `as_of` passed in explicitly, and the golden file regenerated only by a deliberate command whose diff a reviewer reads. **The window rule is what makes `run` idempotent within a day**; without it a second run reports "nothing since ten minutes ago" and reads as a broken pipeline. **`published_date` may be null**; order by `(published_date or observed_at, hash)` so the order is total. `main` is protected -- open a PR. +--- +Written 2026-09-22. + +## What each section answers + +| section | question | source of truth | +|---|---|---| +| header | did the machinery run, and against a current Position | `rss_feeds.last_fetched`, `last_error`, articles in window; `position.reviewed` | +| MOVED | which watches gained evidence, and what it was | `evidence` joined to `observations` in window, grouped by `near_duplicate_groups` | +| DUE | what has a date on it inside the horizon | Position decisions by `deadline`; watches by `expires` | +| WATCHING | what is being held, at what belief, with what recent support | live watches, latest `watch_beliefs`, evidence counts | +| QUIET | where silence might be breakage | `routes` recency per watch, sources with zero items, `adjudications.outcome = 'failed'` | + +The three-week measurement the plan ends on is read off the header: moved items per brief, and +the resolved count. Task 034 is written from those numbers. + +## Done (2026-09-22 and 2026-09-23) + +`src/brief/` (`sections.py`, `select.py`, `render.py`), `src/cli/brief.py`, `src/cli/run.py`, the +`briefs` table in the monitor migration, and the golden end-to-end test in `tests/brief/` +(recorded Federal Register week, a two-item feed that reprints one notice, an empty feed, an +unreachable feed, a scripted model client, a frozen clock). `make golden` rewrites the golden +files; read the diff before committing it. + +### Decisions taken here, for the reader to overturn + +- **DUE looks 30 days ahead** (`HORIZON_DAYS`). Neither this file nor `docs/PLAN.md` gives a + number; "the window ahead" could also be read as the brief's own window mirrored forward. The + constant is the one assumption in the brief and is marked as such in the code. +- **A Position that cannot be read does not stop the brief.** The header prints every problem + the loader found, DUE says its decisions are missing, the review banner is up, and the exit + code is 0, so `run` continues to the brief and records it. The alternative, refusing to render, + would hide the watches' state behind the config error. Reversible in `src/cli/brief.py`. +- **`run` does not include `watch sync`.** The plan names four steps. Syncing is an edit to the + private files followed by one command, not a morning step. +- **Staleness is tested on when routing last linked something** (`routes.routed_at`), not on the + item's publication date, and that is the date QUIET prints after "nothing routed since". A + backfilled document published three weeks ago and routed yesterday is not silence. +- **MOVED shows every watch with evidence in the window, live or not**, labelled `[expired ..., + unresolved]`, `[resolved yes]` or `[retired]`. The plan's wording has no liveness qualifier and + grading an expired watch needs the evidence that arrived. +- **The header prints the last attempt, labelled.** `rss_feeds.last_fetched` is stamped by every + attempt, success or failure, and the row keeps no separate time of the last success, so the + line reads `fetched ` or `LAST ATTEMPT FAILED : `, never a failure as a + fetch. "Last successful fetch" in this file's acceptance is met only when the last attempt + succeeded; keeping the last success through a failure needs a column, deferred. + +### Review (2026-09-23): five lenses, every finding tried by two refuters + +Twenty-five findings survived both refuters; three were refuted as the specified behaviour +(the default window's UTC day boundary, the collapsed "went silent" line, failed adjudications +leaving QUIET after the window). What changed: + +- **QUIET tested staleness on the observation's date**, so a watch routed yesterday read as + silent or never routed. Now `routes.routed_at`, bounded by `as_of`. +- **Evidence for a watch that expired or was resolved inside the window was cited nowhere.** + MOVED now shows it with the watch's state. +- **A failed fetch printed as a fetch.** Labelled as above; `store.record_attempt` is the one + stamp for the three writers (items stored, nothing returned, failure). +- **An observation judged under two prompt versions counted as its own near-duplicate.** The + count is over distinct observations. +- **Routed pairs no adjudication had answered were invisible**, byte-identical to pairs judged + not evidence. QUIET prints them, per watch, under any prompt version. +- **A 200 carrying a landing page, a challenge page or JSON was a clean empty fetch** and, with + the new stamp, would have cleared the source's error and listed it as quiet. `RSSAdapter` + raises when feedparser recognises no feed at all. +- **WATCHING's belief ignored `--as-of`**; `current_beliefs` takes `as_of`. +- **A brief whose `--output` could not be written was recorded as delivered.** Delivery now + precedes the row, and the write error is a message. +- **Only the first line of a Position error reached the header.** The whole message does, and + DUE and the banner say so as well. +- **Tests that could not fail**: MOVED order satisfied by hash alone, the 90-day banner unpinned + between 50 and 261 days, DUE and WATCHING order equal to insertion order, the empty-fetch + runner test unable to see its own stamp. Each now has rows inserted out of order and a case on + each side of the boundary. +- Sources going silent are marked "HAS PRODUCED BEFORE; check the source" versus "never + produced", the distinction the runner keeps and the brief had dropped. +- `docs/PLAN.md` gained `--dry-run` and `sections.py`; the pinned command and table sets in + `tests/cli/test_app.py` and `tests/database/test_models.py` name `brief` and `briefs`. + +Recorded, not changed: `src/sources/runner.py` and its test were over 300 lines before this +task and gained a few lines each; the stamp helper moved to `store.py` to keep it from growing +further. The row cannot hold the last success once a failure overwrote it (above). + +## Addendum (2026-09-24): the header's default became compact + +After a first real run against 72 configured sources, the operator asked for the per-source +header to be shorter by default -- 72 lines of mostly-successful status was burying the four +sections worth reading daily. The fix keeps the LANDMINES rule intact rather than relaxing it: +**a source whose last attempt failed is still named in full, every time, with no flag needed**; +only a source that *answered* (whatever it returned) is folded into a summary count. `--verbose` +restores the original always-list-everything behaviour. `src/brief/render.py`'s module +docstring and `src/cli/brief.py`'s carry the detail; the golden files were regenerated and the +README's embedded excerpt resynced. diff --git a/backlog/032-onboarding.md b/backlog/032-onboarding.md new file mode 100644 index 0000000..7c266b5 --- /dev/null +++ b/backlog/032-onboarding.md @@ -0,0 +1,27 @@ +# Onboarding as a skill: an interview that transcribes the operator's decisions and watches into the private files, validates them, and syncs. +REPO: InsightWeaver +STATUS: DONE # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: small +PLAN: docs/PLAN.md (section 5, task 032; replaces the interview half of backlog/024) +ACCEPTANCE: `make check` passes, plus: `.claude/skills/onboard/SKILL.md` exists with the frontmatter the other skills use; it interviews for decisions (name, deadline, stake, key) and, per decision, for watches (claim, belief, because, structured triggers, expiry, staleness), writes `position.yaml` and `watches.yaml` to `POSITION_PATH` and `WATCHES_PATH` with the structure of the two example files, shows a diff before replacing an existing file, and ends by running `insightweaver watch sync` and `watch list`; every value written is one the operator stated and heard read back; the skill names no command that does not exist (asserted by `tests/test_docs.py`). +OUT OF SCOPE: A `setup` command in the CLI. Ranking decisions, suggesting beliefs, proposing claims. The quarterly review loop of backlog/024 (deferred until there are resolved watches to review). Any write to the database other than through `watch sync`. +LANDMINES: **The interview is the seam through which the system starts authoring its own watches** (invariant 6). A drafting interview is one helpful suggestion away from a generator; the skill says, in its first paragraph and its last, that it transcribes and never fills a field. **A trigger written as a sentence never fires**: the skill explains the clause rule and asks for the actual words. **The files must not land in the checkout**: the defaults point outside it and `.gitignore` refuses the names, but the skill checks the path it is about to write. `main` is protected -- open a PR. +--- +Written 2026-09-23. + +## Why a skill and not a command + +The interview is a conversation, and the operator asked for it to happen in this terminal with +Claude asking the questions. A `setup` command would be a form; a skill is the conversation with +the rules written down: what to ask, in what order, what to refuse, and where to write. The +loaders (`src/position/`) remain the only validation and `watch sync` the only write path, so +the skill cannot put a watch in the table that the file would not. + +## What replaced backlog/024 + +Task 024 had two halves: an interview that wrote a draft Position to a scratch path, and a +quarterly review loop. The interview is this skill, writing to the real private path because the +operator is present and confirms each value; the draft-to-scratch rule was for an unattended +command. The review loop is deferred: the 90-day banner (task 031) is the part that degrades +visibly, and a review that records "what changed" has nothing to record until watches have +resolved. Task 024 is parked with that note. diff --git a/backlog/033-docs.md b/backlog/033-docs.md new file mode 100644 index 0000000..3c072c1 --- /dev/null +++ b/backlog/033-docs.md @@ -0,0 +1,59 @@ +# Documentation rewritten from what exists: README, GETTING_STARTED, CONCEPTS, CONTRIBUTING, the skills, and a test that the docs name only things in the tree. +REPO: InsightWeaver +STATUS: DONE # QUEUED | IN_PROGRESS | PARKED | DONE | FAILED +SIZE: medium +PLAN: docs/PLAN.md (section 5, task 033; decision Q12 in section 7) +ACCEPTANCE: `make check` passes, plus: README.md describes the decision monitor as built, states its status without claims about results it has not produced, carries the five principles each with how this build does or does not implement it, shows a real brief (an excerpt of the golden file), lists every registered command and no other, and names the six invariants; GETTING_STARTED.md takes a reader from a clean clone to a first brief with commands that exist, in an order that works on a fresh database; docs/CONCEPTS.md is the entity-by-entity reference for the monitor with no entity the code lacks; CONTRIBUTING.md matches the Makefile, the pre-commit hooks and CI; `.claude/skills/` name no deleted code; SOURCES.md keeps its licensing content with the deleted beat and its test no longer cited as present; and `tests/test_docs.py` fails when any of those documents names a command, an option, a make target or a repository path that does not exist. +OUT OF SCOPE: Rewriting SOURCES.md beyond the stale sentences (its basis-for-use content stands, per the plan). docs/PLAN.md and docs/RECONCILIATION.md, which are records. Screenshots, badges, a changelog. +LANDMINES: **A README that describes the deleted product as present.** Every sentence was written from the tree on 2026-09-23, and the drift test is the guard against the next rewrite drifting. **Numbers rot**: no test counts, no line counts, no costs. **A guide that cannot be followed on a fresh machine**: writing it found that nothing created `rss_feeds` and `articles` on a clean database, so `make db-init` (`src/database/migrations/create_schema.py`) was added here; the guide's sequence was then run against an empty database. `main` is protected -- open a PR. +--- +Written 2026-09-23. + +## What was written from scratch and what was kept + +README.md, GETTING_STARTED.md and docs/CONCEPTS.md are new text. The five principles keep their +headings from the earlier product because the operator's stated aims did not change; each body +now says what this build does about it, and the third says plainly that it is not implemented. +CONTRIBUTING.md and the review-tests skill were rewritten by a Sonnet 5 writer from the Makefile, +CI, pre-commit and the current suite, then reviewed. SOURCES.md lost only the sentences that +cited the deleted beat and its deleted test. + +## The bootstrap gap + +`get_db` opens a session; nothing created the schema. The three additive migrations create the +tables they were written for and `Base.metadata.create_all` ran only in the tests and in the +deleted pipeline's startup. On a clean checkout `ingest` failed on its first insert. `make +db-init` creates every declared table that is absent and touches nothing that exists; the +additive targets remain for older databases that need columns added. + +## Review (2026-09-23): five lenses, every finding tried by two refuters + +Twenty-nine findings survived both refuters, two split, two were refuted (the README's +`so_what` sentence, which `watch list` makes true; the onboard skill proposing slugs, which +its own scoping sentence allows). What changed: the README no longer says the golden test +drives "every command" or that `make install-dev` creates a venv, shows the golden file whole +rather than a trimmed excerpt, and says `ingest` writes `articles` too; CONCEPTS says what the +observation hash contains (the item and source URLs, so one text from two sources is two rows), +that a file holding an expired watch fails `watch sync` until the watch is graded and its date +moved or the entry removed, that a rebuild restarts QUIET's silence clock, that a replayed +not-evidence pair is asked once more, that the version is a pinned label rather than the +fingerprint itself, that `watch believe` refuses a retired watch, and that a file behind the +operator's belief re-applies the file value as a recorded row (task 030's decision, which the +first draft had reversed); GETTING_STARTED names the exact source names a `sources` clause +needs and says the loader does not check them, that the database path is relative to the +working directory, what "the same brief twice" means, and that removing a feed from config +does not remove its row; the onboard skill says the same about source names; +CONTRIBUTING's fixture path, module count, hook list, task-file fields and migration +description were corrected; SOURCES.md's sentence about the deleted analysis rules was +rewritten and the file joined the drift test. The example watches file named `Federal +Register`, which matches no registered source; it now names `Federal Register - Documents +API`. `.env.example` gained the `DATABASE_URL` line the guide refers to. + +Two invariants the README called tests were not: `tests/test_invariants.py` now pins that +nothing in `src/` imports anything that sends, serves or listens, that only the two fetchers +open an HTTP client, and that only `replay` deletes evidence. `tests/test_docs.py` now also +checks the README's commands table and top-level file names. + +Recorded, not changed: no command removes a source row (a feed dropped from config keeps its +header line); a `route --rebuild` resets `routed_at` and with it QUIET's staleness; both are +noted in the guide and the concepts reference. diff --git a/config/context_modules/README.md b/config/context_modules/README.md deleted file mode 100644 index 7e57302..0000000 --- a/config/context_modules/README.md +++ /dev/null @@ -1,128 +0,0 @@ -# Context Modules - -Context modules provide domain-specific background knowledge to Claude without consuming article tokens. This allows richer, more informed analysis by giving Claude reference context that doesn't change frequently. - -## Directory Structure - -``` -context_modules/ -├── core/ # Core system configuration -│ └── (reserved for future use) -├── domain_knowledge/ # Professional domain background -│ ├── cybersecurity_context.json -│ ├── local_governance_context.json -│ └── economic_indicators_context.json -├── historical/ # Historical patterns and memory -│ └── (auto-generated) -└── supplemental/ # Additional reference data - └── (calendar events, metrics, etc.) -``` - -## Module Structure - -Each module is a JSON file with this structure: - -```json -{ - "module_name": "unique_identifier", - "description": "What this module provides", - "version": "1.0", - "priority": "high|medium|low", - "content_sections": { - "section_name": { - "description": "Section purpose", - "content": [ - "Bullet point 1", - "Bullet point 2" - ] - } - }, - "key_metrics_baselines": { - "category": { - "metric": "value" - } - }, - "reference_links": { - "Link Name": "URL" - }, - "last_updated": "YYYY-MM-DD", - "token_estimate": 500 -} -``` - -## Module Types - -### Domain Knowledge -**Purpose:** Background context for professional domains -**Examples:** Cybersecurity frameworks, local government structure, economic indicators -**Token Budget:** 10,000-15,000 tokens total -**Priority:** High - always included - -### Historical -**Purpose:** Patterns from past analyses -**Examples:** Synthesis summaries, identified trends over time -**Token Budget:** 10,000-15,000 tokens -**Priority:** Medium - included when relevant - -### Supplemental -**Purpose:** Timely reference data -**Examples:** Upcoming events, calendar deadlines, current metrics -**Token Budget:** 15,000-20,000 tokens -**Priority:** Medium - context-dependent - -## Priority Levels - -- **High:** Always included, critical background knowledge -- **Medium:** Included if token budget allows -- **Low:** Included only if significant budget headroom - -## Token Estimates - -Each module should estimate its token cost. Rough guideline: -- 1 token ≈ 4 characters -- 250 tokens ≈ 1 paragraph -- 500 tokens ≈ 1/2 page -- 1000 tokens ≈ 1 page - -## Usage in Code - -```python -from src.context.module_loader import ContextModuleLoader - -# Load all modules -loader = ContextModuleLoader() -modules_by_type = loader.load_all_modules() - -# Get domain knowledge modules -domain_modules = modules_by_type['domain_knowledge'] - -# Format for Claude context -context_str = loader.format_for_claude_context( - domain_modules, - max_tokens=15000 -) -``` - -## Creating New Modules - -1. Create JSON file in appropriate subdirectory -2. Follow the structure above -3. Estimate token count (length / 4) -4. Set appropriate priority -5. Test with `python -m src.context.module_loader` (future CLI) - -## Maintenance - -- **Update frequency:** Domain knowledge: quarterly, Supplemental: weekly/daily -- **Review:** Check accuracy every 3-6 months -- **Token optimization:** Keep modules concise, bullet points preferred -- **Versioning:** Increment version number when making significant changes - -## Best Practices - -1. **Be specific:** "Fairfax County budget: $5.08B" not "County has large budget" -2. **Use bullets:** Easier for Claude to parse -3. **Include baselines:** Reference points for comparison -4. **Cite sources:** Add reference_links for credibility -5. **Estimate accurately:** Helps token budget management -6. **Prioritize ruthlessly:** Not everything needs to be high priority diff --git a/config/context_modules/core/decision_context.example.json b/config/context_modules/core/decision_context.example.json deleted file mode 100644 index 9148488..0000000 --- a/config/context_modules/core/decision_context.example.json +++ /dev/null @@ -1,56 +0,0 @@ -{ - "module_name": "decision_context", - "description": "Template for active decisions and priorities requiring intelligence monitoring", - "version": "1.0", - "priority": "high", - "active_decisions": [ - { - "decision_id": "example_career", - "decision": "Job search or career change", - "timeline": "Next 6 months", - "status": "active_monitoring|monitoring|on_hold", - "relevant_signals": [ - "job market trends in your field", - "salary trends", - "skills demand", - "company hiring/layoffs" - ], - "decision_criteria": [ - "Compensation: target range", - "Work-life balance: preferences", - "Growth: career trajectory" - ], - "why_matters": "Explain why this decision is time-sensitive or important" - }, - { - "decision_id": "example_housing", - "decision": "Home purchase, relocation, or major expense", - "timeline": "Next 12 months", - "status": "monitoring", - "relevant_signals": [ - "interest rates", - "housing market trends", - "local economic indicators" - ], - "decision_criteria": [ - "Affordability: specific thresholds", - "Market conditions: what you're waiting for" - ], - "why_matters": "How this affects financial planning or life decisions" - } - ], - "watching_topics": [ - "Topic 1 that affects you", - "Topic 2 that requires monitoring", - "Topic 3 with time-sensitive implications" - ], - "context_for_analysis": { - "life_stage": "Your current life stage", - "decision_mode": "Planning mode (strategic, reactive, etc.)", - "risk_tolerance": "How you approach risk", - "geographic_constraints": "Any location-specific factors" - }, - "instructions_for_synthesis": "How Claude should use this context when analyzing articles", - "last_updated": "YYYY-MM-DD", - "token_estimate": 500 -} diff --git a/config/context_modules/domain_knowledge/civic_engagement_context.json b/config/context_modules/domain_knowledge/civic_engagement_context.json deleted file mode 100644 index ec2d2a5..0000000 --- a/config/context_modules/domain_knowledge/civic_engagement_context.json +++ /dev/null @@ -1,165 +0,0 @@ -{ - "module_name": "civic_engagement_fairfax", - "description": "Civic engagement context for Fairfax County and Northern Virginia - governance structure, key issues, decision-making bodies, and civic participation framework", - "version": "1.0", - "priority": "high", - "content_sections": { - "local_governance_structure": { - "description": "Key decision-making bodies and officials in Fairfax County", - "content": [ - "Fairfax County Board of Supervisors: 9 district supervisors + 1 chairman, meet 1st & 3rd Tuesday monthly", - "Fairfax County Public Schools (FCPS) Board: 12 members, 193,000+ students, 3rd largest district in Virginia", - "Planning Commission: Reviews zoning applications, comprehensive plan amendments, holds public hearings", - "Board of Zoning Appeals: Hears variance requests and special exception cases", - "School Board meets 2nd & 4th Thursday monthly at Luther Jackson MS", - "County Executive: serves as chief administrative officer, implements Board policies" - ] - }, - "electoral_districts": { - "description": "Voting districts and representation structure", - "content": [ - "9 supervisor districts: Braddock, Dranesville, Hunter Mill, Lee, Mason, Mount Vernon, Providence, Springfield, Sully", - "At-large Chairman elected countywide", - "School Board: 9 district reps + 3 at-large members", - "Virginia House of Delegates: Northern Virginia has ~40 delegates", - "Virginia Senate: Northern Virginia has ~15 senators", - "U.S. Congress: Districts 8, 10, 11 cover Fairfax area" - ] - }, - "key_civic_issues": { - "description": "Ongoing civic issues affecting Fairfax County residents", - "content": [ - "School funding: FCPS budget battles, teacher pay, facility needs", - "Housing affordability: Missing middle housing, zoning reform, development density", - "Transportation: Metro funding, Route 28/66/495 congestion, bike/ped infrastructure", - "Development: Rezoning applications, comprehensive plan amendments, neighborhood impacts", - "Taxes: Real estate assessments, tax rate decisions, budget priorities", - "Public safety: Police funding, emergency services, mental health response", - "Environment: Tree canopy preservation, stormwater management, climate action" - ] - }, - "civic_participation_touchpoints": { - "description": "How residents engage with local government", - "content": [ - "Public hearings: BOS, Planning Commission, School Board all have citizen comment periods", - "Budget process: Feb-Apr, includes town halls and public input sessions", - "Zoning applications: 15-day neighbor notification, public hearing opportunities", - "School boundary reviews: When schools are over/under capacity, community engagement process", - "Comprehensive Plan: Updated every 5 years, extensive public input", - "Citizen advisory committees: 50+ committees on various topics", - "Elections: Nov general, June primaries, May local (odd years)" - ] - }, - "high_priority_signals": { - "description": "Signals that indicate important civic developments", - "content": [ - "Board/School Board meeting agendas with action items", - "Zoning application filings (especially rezonings, not administrative permits)", - "Proposed ordinance/policy changes", - "Budget amendments or significant expenditures", - "Leadership changes (appointments, resignations, retirements)", - "Public hearing schedules", - "Election filing deadlines and candidate announcements", - "Legislative bills affecting local governance (dillon rule, taxation, education)", - "Development proposals >50 units or >100K sq ft commercial", - "School capacity studies and boundary changes" - ] - }, - "regional_context": { - "description": "Northern Virginia regional governance and planning", - "content": [ - "Northern Virginia Regional Commission (NVRC): Coordinates across jurisdictions", - "Metropolitan Washington Council of Governments (MWCOG): Regional planning for DC metro", - "WMATA: Regional transit authority governing Metro", - "Virginia Railway Express (VRE): Commuter rail service", - "Regional housing initiatives: coordinated affordable housing efforts", - "Transportation planning: I-495/I-66 managed lanes, future projects" - ] - }, - "state_legislative_impact": { - "description": "How Virginia General Assembly affects local governance", - "content": [ - "Dillon Rule state: Localities only have powers explicitly granted by GA", - "Education funding: State share of K-12 budget, Standards of Quality", - "Taxation authority: GA controls what taxes localities can levy", - "Land use: Proffers, zoning authority defined by state code", - "Elections: State sets election laws, redistricting every 10 years", - "Transportation funding: NVTA allocates regional gas tax revenue", - "Key session dates: GA convenes 2nd Wed in January, 60-day session (long years) or 30-day (short years)" - ] - } - }, - "key_metrics_baselines": { - "governance": { - "board_meetings_per_month": "2 (1st & 3rd Tuesday)", - "school_board_meetings_per_month": "2 (2nd & 4th Thursday)", - "planning_commission_meetings": "Weekly on Wednesday evenings", - "public_comment_time_limit": "3 minutes per speaker typically" - }, - "fiscal": { - "county_budget_fy2024": "$5.08 billion", - "fcps_budget_fy2024": "$3.47 billion", - "real_estate_tax_rate": "$1.105 per $100 assessed value (2024)", - "median_home_value": "~$650,000 (2024)" - }, - "demographics": { - "population": "1.15 million (2024 est)", - "registered_voters": "~750,000", - "fcps_enrollment": "193,000 students", - "voting_age_population": "~900,000" - } - }, - "civic_keywords": { - "high_priority": [ - "Board of Supervisors", - "School Board", - "Planning Commission", - "public hearing", - "zoning application", - "rezoning", - "special exception", - "comprehensive plan", - "budget", - "tax rate", - "election", - "ballot measure", - "General Assembly", - "legislation", - "ordinance", - "development application" - ], - "medium_priority": [ - "supervisor", - "school boundary", - "FCPS", - "transportation project", - "infrastructure", - "affordable housing", - "parking", - "traffic", - "Metro", - "public comment", - "citizen input", - "town hall", - "community meeting" - ], - "contextual": [ - "neighborhood association", - "civic association", - "parent-teacher", - "volunteer", - "commission appointment", - "advisory board" - ] - }, - "reference_links": { - "Board of Supervisors": "https://www.fairfaxcounty.gov/boardofsupervisors/", - "FCPS School Board": "https://www.fcps.edu/school-board", - "Planning Commission": "https://www.fairfaxcounty.gov/planning-development/planning-commission", - "Virginia General Assembly": "https://virginiageneralassembly.gov/", - "NVRC": "https://www.novaregion.org/", - "MWCOG": "https://www.mwcog.org/" - }, - "last_updated": "2025-11-18", - "token_estimate": 1200 -} diff --git a/config/feeds/geographic/states/virginia.json b/config/feeds/geographic/states/virginia.json index 0c06ad2..863f684 100644 --- a/config/feeds/geographic/states/virginia.json +++ b/config/feeds/geographic/states/virginia.json @@ -1,17 +1,6 @@ { "description": "Virginia state-level feeds - state government, policy, and regional news", "feeds": [ - { - "name": "Virginia Mercury", - "url": "https://www.virginiamercury.com/feed/", - "applicability": { - "scope": ["regional"], - "geo_tags": ["virginia"], - "domain_tags": ["state_politics", "state_policy"], - "specialty_tags": [] - }, - "relevance_score": 0.9 - }, { "name": "Supreme Court of Virginia Opinions", "url": "https://www.vacourts.gov/static/rss/rss_scv_opinions.xml", diff --git a/config/position.example.yaml b/config/position.example.yaml index 1e6f8bf..cd4945b 100644 --- a/config/position.example.yaml +++ b/config/position.example.yaml @@ -20,8 +20,9 @@ version: 1 -# When you last sat down with this file. Task 024 turns this into the quarterly -# review loop; for now it is a date you can read. +# When you last sat down with this file. The brief prints the days since it and +# carries a banner past 90 days, or when it is missing (backlog task 031). The +# review loop that would stamp it is parked (task 024) until watches resolve. reviewed: 2026-08-31 decisions: diff --git a/config/probes/known-events.json b/config/probes/known-events.json deleted file mode 100644 index 2c5fbd5..0000000 --- a/config/probes/known-events.json +++ /dev/null @@ -1,74 +0,0 @@ -{ - "_provenance": "Authored by hand for the us-public-sector-compliance beat and recovered from commit 673a8dd when backlog task 012 deleted that beat. Beats no longer exist; these are kept because they are real, verified past events in the operator's domain and task 018's staleness check needs exactly this shape. The loader for the old beat format is gone -- task 018 reads this file directly. Recovered 2026-08-31.", - "probes": [ - { - "date": "2026-08-25", - "what": "OPM issued corrections to its final rules on reduction-in-force, suitability and probationary appeals", - "terms": [ - "OPM" - ], - "any_of": [ - [ - "reduction in force", - "suitability", - "probationary" - ], - [ - "final rule", - "correction" - ] - ] - }, - { - "date": "2026-08-24", - "what": "Supreme Court let the executive order restricting mail-in voting take effect", - "terms": [ - "Supreme Court", - "mail-in voting" - ], - "any_of": [ - [ - "allow*", - "restriction*", - "sides with", - "stay" - ] - ] - }, - { - "date": "2026-08-24", - "what": "FedRAMP director reinstated", - "terms": [ - "FedRAMP" - ], - "any_of": [ - [ - "director", - "administrator" - ], - [ - "reinstat*", - "return*", - "restored" - ] - ] - }, - { - "date": "2021-11-03", - "what": "CISA issued Binding Operational Directive 22-01, creating the Known Exploited Vulnerabilities catalog and its remediation deadlines", - "terms": [ - "CISA" - ], - "any_of": [ - [ - "binding operational directive", - "BOD 22-01" - ], - [ - "known exploited", - "catalog" - ] - ] - } - ] -} diff --git a/config/user_profile.example.json b/config/user_profile.example.json deleted file mode 100644 index 3d946dd..0000000 --- a/config/user_profile.example.json +++ /dev/null @@ -1,151 +0,0 @@ -{ - "profile_metadata": { - "created_at": "2025-09-30", - "last_updated": "2025-09-30", - "version": "1.0", - "description": "Personal context profile for InsightWeaver narrative synthesis" - }, - "geographic_context": { - "primary_location": { - "city": "Arlington", - "state": "Virginia", - "region": "Northern Virginia" - }, - "geographic_scope_priority": ["local", "regional", "national", "international"], - "areas_of_interest": [ - "Washington DC Metro Area", - "Virginia", - "Mid-Atlantic region" - ] - }, - "professional_context": { - "industry": "Technology", - "job_role": "Software Engineer", - "professional_domains": [ - "software development", - "cybersecurity", - "artificial intelligence", - "federal contracting", - "cloud computing" - ], - "career_stage": "mid", - "work_type": "federal contractor", - "education_background": "Computer Science degree, continuous learning in AI/ML" - }, - "civic_interests": { - "political_engagement_level": "high", - "policy_areas": [ - "technology policy", - "privacy and surveillance", - "education policy", - "transportation infrastructure", - "housing policy" - ], - "community_focus": [ - "local government", - "public education", - "urban development", - "civic technology" - ] - }, - "personal_priorities": { - "life_stage": "mid-career professional, family considerations", - "active_decisions": [ - { - "name": "career advancement opportunities", - "key_factors": ["salary range", "work-life balance", "growth potential", "remote work options"], - "decision_type": "career", - "created_at": "2025-01-15" - }, - { - "name": "housing market monitoring", - "key_factors": ["price trends", "interest rates", "neighborhood quality", "commute time"], - "decision_type": "housing", - "created_at": "2025-01-15" - }, - { - "name": "education system quality", - "key_factors": ["test scores", "teacher retention", "programs offered", "class sizes"], - "decision_type": "education", - "created_at": "2025-01-15" - } - ], - "priority_topics": [ - "economic trends", - "cost of living", - "local infrastructure projects", - "technology sector health", - "public safety", - "education quality" - ] - }, - "source_calibration": { - "trust_overrides": {}, - "calibration_alerts_enabled": true, - "alert_threshold_deviation": 0.2 - }, - "content_preferences": { - "excluded_topics": [ - "sports", - "celebrity news", - "entertainment gossip", - "clickbait", - "viral content" - ], - "source_preferences": [ - "official government sources", - "investigative journalism", - "technical analysis", - "policy briefs" - ], - "complexity_level": "technical" - }, - "briefing_preferences": { - "perspective": "daily_intelligence_brief", - "tone": "analytical_professional", - "reading_time_minutes": 7 - }, - "feed_preferences": { - "required_scopes": ["always", "national"], - "geographic_interests": [ - "usa", - "virginia", - "northern_virginia" - ], - "professional_domains": [ - "cybersecurity", - "technology", - "software_development" - ], - "specialty_interests": [ - "education", - "transportation" - ], - "excluded_topics": [ - "sports", - "entertainment" - ] - }, - "voting_context": { - "registered_state": "VA", - "county_fips": "51013", - "congressional_district": "VA-11", - "state_senate_district": "32", - "state_house_district": "36", - "school_district": "Arlington Public Schools", - "address": { - "street": "1234 Example St", - "city": "Arlington", - "state": "VA", - "zip": "22201" - } - }, - "civic_preferences": { - "track_elections": true, - "track_meetings": true, - "track_public_comments": true, - "track_budget_hearings": true, - "track_zoning": true, - "advance_notice_days": 7 - } -} diff --git a/config/watches.example.yaml b/config/watches.example.yaml index a037ca1..bf4d929 100644 --- a/config/watches.example.yaml +++ b/config/watches.example.yaml @@ -54,7 +54,7 @@ watches: triggers: - entities: [FedRAMP PMO, GSA] terms: [continuous monitoring, ConMon, significant change] - - sources: [Federal Register] + - sources: [Federal Register - Documents API] terms: [FedRAMP] expires: 2027-03-31 staleness_alert_days: 30 diff --git a/data/newsletters/.gitkeep b/data/newsletters/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/CONCEPTS.md b/docs/CONCEPTS.md index 32efb55..f591f9f 100644 --- a/docs/CONCEPTS.md +++ b/docs/CONCEPTS.md @@ -1,295 +1,217 @@ # InsightWeaver Concepts -A one-page reference for the entities the tool persists, how they relate, and when each one gets created. Read this once and the CLI commands will make sense. +The entity-by-entity reference for the decision monitor. Rewritten 2026-09-23 (backlog task +033) from the code as it stands; the earlier commitment graph of questions, predictions and +frames was deleted on 2026-08-31 and is described only in git history and +`docs/RECONCILIATION.md`. ---- +## The shape of the thing -## The core idea: a commitment graph +Decisions are the root. A watch is a claim that would change one decision, written before any +document arrives. Observations are what sources published. Routing links observations to +watches by rule. Adjudication asks a model whether a linked pair is evidence. Beliefs and +grades are the operator's. The brief is a view over all of it, as of a moment. -InsightWeaver is built around a small graph of **commitments** — things the system or the user has bound itself to track. Each daily brief is a diff against this graph, not a standalone artifact. The unit of value is the running record, not the morning report. - -The graph has five primary entity types. Everything in the CLI is either creating one of these, updating one, or reading the graph back out. - -A sixth concept, the **Beat**, is not a commitment but a *scope* over them: it says which sources a run reads and which slice of the graph that run accumulates into. See "Beats" below. - ---- - -## Questions - -A **Question** is an unresolved epistemic thread the coverage is implicitly tracking. Most situations end with one — "Will the Fed cut rates in June?" — and that question persists across daily runs until it resolves. - -A Question has one of three origins. Most are **emergent**: the graph notices what coverage leaves unresolved. A beat can also **declare** one up front — see "Standing questions" below. Since 2026-08-27 the operator can declare one directly with `questions add "..." --cadence 90d`. All three are the same kind of row, and everything downstream (predictions, decision evidence, appearance counts) treats them identically. - -**Cadence.** A question the operator declared carries a `cadence` — a review interval such as `7d`, `90d`, `1y`. **A cadence is not a deadline.** It says how often the question is worth re-examining; a Prediction's `due_by` says when a specific claim resolves. A question reviewed quarterly can hold a claim resolving in three weeks, and that nesting is the point: a CISA directive deadline is a 30-day loop and whether CMMC Phase 2 slips is a multi-year one, and forcing both onto one rhythm checks the fast one too late and buries the slow one in noise. - -`forecast --due` surfaces a question when *its own* interval has elapsed since `last_reviewed_at` (or `first_asked_at`, if never reviewed), and **stamps it whether or not anything moved** — a quiet question that reappears every day trains the operator to skim. A cadence is itself falsifiable: a question always quiet at its interval was set too fast, one that moved twice before its next review was set too slow. - -Cadence is nullable, and null means "not on a review schedule". Emergent questions have none — the interval is the operator's read on how fast a subject moves, so nothing infers it from coverage volume. - -**When created.** Each situation's `unresolved_questions.primary` (and optional secondaries) is matched against the open question graph by a Haiku call. If today's question is the same underlying question as one already open, today's situation gets bound to that existing Question. Otherwise a new Question is created. - -**When resolved.** Manually, via `insightweaver questions resolve --note "..."`. The tool never auto-resolves; deciding a thread has closed is editorial. - -**Reappearance.** When a previously resolved Question's text appears again in fresh coverage, a *new* Question is created with `previous_question_id` pointing at the resolved one. Resolution is never silently undone. - -**CLI.** `questions add "..." --cadence 90d | list [--beat NAME] | show | resolve --note ...`. `questions list` shows each question's cadence and time until next review. - -**In the brief.** Returning questions surface their identity inline: `Q47 (run 4, asked 2026-03-12)` for repeat appearances, `Q47 (new)` for first ones. - ---- - -## Predictions - -A **Prediction** is a falsifiable claim about the future. Every prediction carries an `author`: `model` or `operator`. - -**Model predictions.** Each `what_to_watch` entry in a situation's output becomes a Prediction keyed to that situation's primary Question, created during synthesis after questions are resolved. Before each new synthesis, a check pass grades the open ledger against today's coverage: triggered, contradicted, expired (no signal after 90 days), or still open. - -**Operator predictions.** Staked by hand: `predict "..." --by YYYY-MM-DD --confidence 0.7`. Both flags are **required and rejected at entry** — nothing is stored without them. That is not fussiness. Of the first 33 model predictions, 25 were phrased "X would signal Y" (an interpretation rule, which cannot be wrong) and only 3 carried a date; 19 expired unjudged. A claim with no resolution date can never come due, so it can never be graded, and a confidence with a default is a non-commitment in a different costume. - -**When an operator prediction resolves.** Manually: `resolve --outcome yes|no --note "..."`. `resolved_at` is recorded **separately from `due_by`** — resolving three months late is itself calibration data. A resolved prediction is not editable, and resolving one twice is refused. - -**Auto-resolution from coverage is deliberately absent.** A tool that grades its operator's calls using the same corpus that produced them is measuring agreement with itself. The friction of resolving by hand is the instrument, not an obstacle to it. - -**The author split.** `predictions track-record` reports the operator's plain hit rate — how often the claim, as written, came true — and reports model predictions under a separate heading. The two are never mixed: a track record blending them measures nothing. The model's stay in the ledger as *prompts*, suggestions about what is worth holding an opinion on. - -**CLI.** `predictions open | triggered | contradicted | track-record`, each taking `--beat NAME`; plus the write side, `predict` and `resolve`. - -**In the brief.** A transparency line at the top of each brief reports the check results: "Prediction check: 8 open observables graded — 1 triggered, 0 contradicted, 7 still open." - ---- - -## Decisions, Factors, and Evidence - -These three together form the **decision journal** — the user-side input that turns daily news into accumulating per-decision context. - -A **Decision** is a standing decision the user is carrying (e.g., "housing market timing"). A **DecisionFactor** is a specific variable inside that decision the user is tracking (e.g., "interest rates"). Each factor has a free-text `what_would_update_me` clause — this is the user's stated rule for what evidence would change their read, and it's what makes routing tractable. - -**DecisionEvidence** records that a specific situation contained evidence bearing on a specific factor, in a specific direction (`supports`, `complicates`, `neutral`), with an `epistemic_status` label. - -**When created.** Decisions and Factors are added by the user via CLI. Evidence is created automatically: after each synthesis's Pass 2, a Haiku router matches situations against open factors and writes Evidence rows for genuine connections. - -**Why it matters.** Real decisions accumulate over weeks of evidence, not a single brief. The decision journal is what turns the tool from a daily artifact into a working memory. - -**CLI.** `decisions list | show | add | resolve --note ... | factor add --name ... --update-when ...` - -**In the brief.** A "Your decisions" section shows which factors moved today and which direction. - ---- - -## Frames - -A **NarrativeFrame** is a coherent way of organizing a story: what it emphasizes, what it backgrounds, and what it takes for granted. Frames are structural features of coverage, not opinions. - -The frame layer has several related entities: - -- **TopicCluster.** A topical area (e.g., "fed policy"). Frames live inside clusters. -- **NarrativeFrame.** A discovered or validated frame for a cluster. Has `validated: bool` — discovered frames start unvalidated until the user approves them via `frames edit`. -- **ArticleFrame.** Maps an article to the frame it most exhibits, with a confidence in `[0, 1]`. Populated by a Haiku classifier on each run. -- **FrameGap.** A frame consistently absent from coverage. A feed-curation signal — if a known frame stops appearing, the gap is recorded. - -**Why it matters.** Once `article_frames` is populated, you can ask structural questions about your information diet: which frames does each feed carry, which frames does only one feed supply (single point of exposure), which frames have been absent for weeks. That's what `diet` shows. - -**CLI.** `frames list | show | edit | gaps`, and `diet feeds | gaps | overlap`. - ---- - -## Meta-fractures - -A **meta-fracture** is a single underlying frame conflict that surfaces across multiple topically distinct situations on the same day. Computed in Pass 3 (cross-cluster reconciliation) and not persisted as its own table — lives in the synthesis JSON. - -Most days have none. When one appears, it's structural insight: the same disagreement is shaping coverage in places you wouldn't have connected. - -**In the brief.** A META-FRACTURES section appears when results exist. - ---- - -## Beats - -A **Beat** is a *subject* the tool runs briefs for, as opposed to the *person* the user profile models. `config/user_profile.json` describes a location, a profession, a voting context and a set of civic interests; `config/beats/.json` describes a topic and the sources that cover it. The two coexist. The person path is unchanged and `insightweaver brief` with no `--beat` behaves exactly as it always has. - -**Shape.** A beat file is small on purpose: - -```json -{ - "name": "us-public-sector-compliance", - "description": "...", - "sources": [ - { "adapter": "rss", "feed_tags": ["regulatory", "federal_policy"], "geo_tags": ["usa"] } - ], - "coverage": {}, - "standing_questions": [], - "channels": ["terminal"] -} ``` - -**Source selection reuses the feed `applicability` tags**, it does not invent a parallel selector. `feed_tags` is matched against a feed's `domain_tags` and `specialty_tags`; the optional `geo_tags` and `scope` narrow against the families of the same name. Within a family the match is ANY, across families it is ALL, and multiple `sources` entries union. A beat is deliberately *not* validated by `src/utils/profile_loader.py` — that validator enforces a person-shaped schema, and a beat is a different shape. - -**Neither `coverage` nor `standing_questions` is reserved any more.** `coverage` declares the institutions the beat tracks — see "Institutional activity" below. `standing_questions` declares the agenda it reports against — see "Standing questions" below. - -**Run recording.** `beats` holds one row per subject; `beat_runs` holds one row per brief run, carrying the `analysis_run_id`, the `synthesis_id`, the article count and the number of feeds the beat resolved to. A run is attributed in the same transaction that stores its synthesis, so a stored synthesis is either attributed or does not exist. - -**CLI.** `brief --beat NAME`. `--beat` and `--from-run` are mutually exclusive: a stored run replays exactly as recorded. - -**Expect a beat to be thin.** RSS is the only adapter today, and specialist domains publish little of it. The shipped `us-public-sector-compliance` beat resolves to eight feeds. That thinness is a finding about the source layer, not a defect in the beat. - -### Scoping decision: the graph is scoped by derivation, not by a `beat_id` column - -Questions, Predictions and their join rows carry **no `beat_id` column**. A row's beat is derived from `beat_runs`: a synthesis belongs to a beat when a `beat_runs` row says so; a Question belongs to a beat when it appeared in one of that beat's syntheses; a Prediction inherits the beat of the Question it keys off. Two scopes exist — a beat's scope, and the **default scope**, which is everything no beat run ever touched. - -This is scoping, not collision-acceptance. The question matcher only ever binds within one scope, the prediction check only grades and expires within one scope, and — the load-bearing part — **appearance counts are counted within a scope**, so `Q47 (run 4, asked 2026-03-12)` means "the fourth time *this subject* raised it". - -Why derivation rather than a column: - -- **A Question's beat is not an independent fact.** It is discovered from coverage, and the only thing that knows which subject surfaced it is the run. A `beat_id` column would be a second, denormalized copy of something `beat_runs` already determines, and the two could disagree. -- **The same question can legitimately belong to two scopes.** A CISA directive can be both a compliance question and a personal-news question. A column forces a duplicate Question row and severs the link between them; derivation keeps one Question with an independent appearance count in each scope. -- **It is additive.** No existing table is altered, so an unmigrated database keeps working for every non-beat command, and the migration cannot lose data. On a database with no `beat_runs` rows — every database that predates this feature — the default scope is the whole graph and every scope filter is an identity filter. That is what makes the no-beat path provably unchanged rather than merely believed to be. - -What stays **global**, deliberately: - -- **Decisions, DecisionFactors and DecisionEvidence.** A standing decision belongs to the user, not to a subject; the point of routing beat coverage into it is that a compliance development can move the user's career-timing factor. Scoping the decision journal per beat would break exactly the connection it exists to make. -- **TopicClusters and NarrativeFrames.** A frame is a structural property of coverage, not of a subject. The same "national-security framing" appears in both the compliance beat and the general brief, and it is the same frame. Splitting the glossary per beat would fragment the frame vocabulary and weaken the `diet` signals, which depend on comparing feeds across the whole corpus. -- **Article content filtering.** Stage 3 still filters articles against the person profile's `excluded_topics` before a beat brief selects from what remains. A beat scopes which *sources* are read, not who the brief is for. - -### Standing questions: the agenda a beat declares - -A brief is a delta against a standing intelligence agenda, not a summary of events. Emergent Questions give half of that: the graph notices what coverage leaves unresolved. `standing_questions` gives the other half — the human writes down what the beat is watching, and the beat carries it **whether or not any given run's coverage mentions it**. - -```json -"standing_questions": [ - "Does CMMC Phase 2 slip past its statutory date?", - "Which CSPs move to FedRAMP authorized, and at which impact level?" -] -``` - -A list of strings, in the human's own agenda order. Duplicates are refused rather than deduplicated: two identical declarations mean the author lost track of the agenda, and collapsing them would hide that. - -**Seeding.** On the beat's first run each declaration becomes a real `Question` row, joined to the beat through `beat_standing_questions`. Seeding is idempotent by normalized text, and it happens at beat registration — before any coverage is read — because a declared question exists because a human declared it, not because an article mentioned it. If the beat is already raising that exact question emergently, the existing Question is *adopted* rather than duplicated, so its accumulated history survives the declaration. - -**Nothing is auto-retired.** Removing a question from the config stops it being declared; it does not close the Question. Closing one is editorial, and it stays a manual `questions resolve`. - -**Why a join table and not a `beat_id` column.** The derivation rule above places a Question by the runs it appeared in. A declared question can exist before — and without ever — appearing in a synthesis, so `beat_runs` alone cannot place it, and it would fall into the default scope and collide with the person brief's ledger. `beat_standing_questions` is a beat table in the same sense `beat_runs` is: the graph tables still carry no `beat_id`, and a beat's scope is still derived from a join. - -**A tighter binding threshold than emergent questions get.** Seeded questions enter the same matcher, so a run's coverage can bind to one. But a declared question is written before any coverage exists and is typically broad, and broad text is exactly what a similarity matcher over-matches. Binding one to unrelated coverage is worse than missing a real match, because a standing question that falsely reads "moved" destroys the only thing the agenda is for. So for declared questions the Haiku matcher's answer is treated as a *proposal*: it stands only if the proposed text also shares at least 60% of the shorter question's subject vocabulary (`STANDING_BINDING_MIN_OVERLAP`). A refused bind is not a failure — the proposed question becomes a new emergent Question and the standing question is reported unmoved, which is the honest answer when the coverage was about something else. Emergent matching is unchanged. - -**In the brief.** Every run reports movement against every declared question, in a `STANDING AGENDA` section ahead of the situations: - +Position (decisions) hand-authored, private + | +Watch (claim, triggers) hand-authored, private; the join key + | +Observation <-- Route --> Watch deterministic, no model + | +Adjudication --> Evidence one model call per routed pair + | +Belief ledger, Resolution operator only + | +Brief derived view, deterministic to the byte ``` - [MOVED] Does CMMC Phase 2 slip past its statutory date? - Q1 (declared 2026-08-26, run 2) - Moved in: Situation 1: DoD signals CMMC Phase 2 timeline pressure[3] - Watching for: A DFARS class deviation naming CMMC Phase 2 -- published before the statutory date - - [NO MOVEMENT] Which CSPs move to FedRAMP authorized, and at which impact level? - Q2 (declared 2026-08-26, never moved) - No coverage this run bore on this question, and none ever has. -``` - -The second entry is the point. **"No movement on CMMC Phase 2 this week" is itself information**, so a standing question with no coverage this run is reported as unmoved rather than filtered out as an empty section. That is the single failure mode this feature exists to prevent, and no layer — builder, stored payload, or renderer — is allowed to drop a quiet entry. - -The agenda is computed when the synthesis is stored, not when it is rendered, and lands in `synthesis_data.metadata.standing_agenda`. So `--from-run` replays the same agenda the live run reported, and no renderer needs database access. - -Standing questions need their own additive migration: - -```bash -python -m src.database.migrations.add_standing_questions # or: insightweaver brief setup -``` - -### Reading the graph back out: `questions`, `predictions`, `forecast` - -Scoping the write path is only half the boundary. `brief` writes the graph; `questions`, `predictions` and `forecast` read it back out, and an unscoped read would surface a beat's ledger as though it were the user's own. That is the same silent-wrong-answer failure the scoping exists to prevent, so these commands answer the same way `brief` does: - -**No `--beat` means your own ledger, `--beat NAME` means that subject's.** One flag, the same meaning everywhere. - -| Command | Scoped? | -| --- | --- | -| `questions list` | yes | -| `predictions open` / `triggered` / `contradicted` | yes | -| `predictions track-record` | yes | -| `forecast` | yes | -| `questions show ` | no -- id-addressed, discloses its ledger | -| `questions resolve --note ...` | no -- id-addressed, reports its ledger | - -`track-record` is the case that matters most. A calibration figure is only meaningful within one ledger: folding a compliance beat's resolved observables into the user's personal hit rate would corrupt the single number the tool exists to be honest about. `forecast` is a derived view over the predictions ledger, so it inherits the ledger's scoping rather than defining its own. - -**The two exceptions are deliberate, and they are not "left global by omission".** `questions show 47` and `questions resolve 47` name one specific row. Refusing to find it because it belongs to another ledger would be obstructive, and silently scoping the lookup would make a valid id look nonexistent — addressing a row by id is an explicit act, not a browse. So both operate on the whole graph, and both **disclose** the ledger the row belongs to: `show` prints a `Ledger:` line, and `resolve` names the beat in its confirmation. The appearance history inside `show` is likewise unscoped, because it is the full history of the row the user asked about. Scoping is thereby always either applied or stated, never assumed. - -**`--beat` on the read side resolves against the `beats` table, not `config/beats/`.** A ledger you have already accumulated stays readable after its config file is edited or deleted; reading is about what ran, not about what is currently configured to run. An unrecognised name is an error naming the beats that have runs, rather than an empty result that would read as "you have nothing here". - -On a database with no `beat_runs` rows these commands behave exactly as they always have, for the same reason the brief does: the default scope is the whole graph. - ---- - -## Institutional activity - -A beat's `coverage` block names the **institutions** it tracks: organizations, programs, and types of document. Each run counts how many of its items mention each one, and the brief reports the entities whose count **departed from their trailing average**. - -```json -"coverage": { - "orgs": [{ "name": "CISA", "aliases": ["Cybersecurity and Infrastructure Security Agency"] }], - "programs": ["FedRAMP 20x", "CMMC"], - "document_types": [{ "name": "Binding Operational Directive", "aliases": ["BOD"] }] -} -``` - -An entry is either a bare canonical name or `{"name": ..., "aliases": [...]}`. The three block names are the whole vocabulary: `kind` is `org`, `program` or `document_type`. - -**There is no person kind, and that is the design, not an omission.** The loader rejects a `coverage.people` key — and any other unrecognised block — with an error rather than ignoring it, so the boundary is enforced by the schema and cannot be reintroduced by convention. `beat_entities` has no person kind and there is no persons table, so no per-individual record exists to profile with. A named individual may appear inside a rendered situation where the source document names a signatory; that is an attribute of a document and expires with it, whereas a person row would accumulate across runs into a file on someone. - -The reasoning is on the merits as well as the ethics. Personnel rotate and offices persist: tracking `FedRAMP PMO` survives a staffing change, while tracking a name goes silently dark on reassignment and the absence reads as inactivity — a wrong answer that looks like a real one. The interesting signal was never a person; it is whether an office moved. - -**The signal is the delta, never the count.** A flat tally is noise: the entities a beat declares are the ones that appear most days, so "FedRAMP PMO: 6" reproduces a standing fact every morning. What the brief says is `FedRAMP PMO appeared in 6 items this run, against a trailing average of 1`. The baseline is the last five recorded runs, and a move must clear both one whole item and half the baseline before it is reported as movement. **Expect this to look useless on day one** — there is no baseline until several runs have accumulated, and it must not be tuned against a single run. - -**Matching is deterministic word-boundary alias matching. No model is involved.** A count a model produced is not reproducible from the same articles tomorrow, and an unreproducible baseline cannot support a delta. Acronyms collide badly — `CISA` sits inside "precisa", `OMB` inside "bombing" and "combat", `BOD` inside "body" — so every term is anchored between non-alphanumeric positions, and a term written entirely in capitals matches case-sensitively, because an acronym is only itself when it is shouted. Hyphens and slashes are boundaries, so "CISA-issued" counts. A mention is counted per *item*, not per occurrence: an article naming CISA nine times is one item. - -**What appears and what does not.** An entity with no mentions and no history does not appear — declaring it was a hypothesis about where news comes from, and one that has never paid out is a note about the config, not a line in the brief. An entity that **has** been active and is now quiet does appear: silence is information, and dropping it is the same class of bug as a standing question vanishing on a quiet day. `entity_mentions` records a row per entity per run including the zeroes, because a baseline that averaged only the busy days would always read as normal. - -**It is not a leaderboard.** Entries are ordered by kind then name, never by count, and the section states that a count is an observation rather than a measure of significance. Consistent with "no entity stores a truth value": activity is not importance, and the tool does not infer intent, motive or significance from it. - -**Schema.** `beat_entities` holds one row per declared institution per beat, carrying `kind`, the canonical `name` and the configured `aliases`. `entity_mentions` holds one row per entity per run, carrying `item_count`, `items_scanned` and the `beat_run_id` and `synthesis_id` of the run — written in the same transaction as the synthesis, so a stored run is either fully recorded or does not exist. An entity dropped from the config keeps its rows; deleting them would silently rewrite the record of what was observed. - -**Migration.** `python -m src.database.migrations.add_beat_entities`. Purely additive; a database without it keeps working and the activity section is simply absent. - ---- - -## Sources - -Each RSSFeed carries derived **calibration signals**, computed on demand from ArticleFrame and FrameGap data. No new schema for this — purely a view: - -- **Frame uniqueness:** fraction of this feed's tagged articles whose frame is carried by no other feed. High score = single point of exposure. -- **Gap-filling:** fraction of recorded gap labels this feed's articles cover. High score = this source brings perspectives the rest of your corpus lacks. - -**CLI.** `sources list | show ` - ---- - -## How a daily brief flows through the graph - -With `--beat`, step 0 is registering the beat, seeding the standing questions it declares, and resolving its sources; every graph read and write below is then confined to that beat's scope, and step 8 also writes the `beat_runs` row. Without `--beat` the run operates in the default scope, which on a database with no beat runs is the whole graph. - -0. **Coverage pass** (beats with a `coverage` block only) — the run's items are matched against the beat's declared institutions and read against their trailing averages. Deterministic, no model call. -1. **Prediction check** — open Predictions are graded against today's coverage. Resolutions written to the ledger. -2. **Pass 1** — articles clustered into topic groups. -3. **Pass 2** — each cluster gets a situation analysis (with frame-aware prompting if known frames exist) and its articles get tagged into ArticleFrame. -4. **Pass 3** — cross-cluster reconciliation looks for meta-fractures. -5. **Question matching** — situation `unresolved_questions` matched against the open Question graph; new Questions created or existing ones bound. With `--beat`, this is also where the beat's declared standing questions can be bound, on the tighter threshold, and where the standing-agenda review is computed — including every declared question that did *not* move. -6. **Prediction creation** — situation `what_to_watch` observables become new open Predictions keyed to the matched Questions. -7. **Decision routing** — situations matched against open DecisionFactors; Evidence rows written for genuine connections. -8. **Render** — the brief renders, surfacing question identity, the prediction-check summary, the decision routing, the standing agenda and the institutional activity (both for a beat), and any meta-fractures. - -After this loop runs, the graph has accumulated: -- new Questions or returning ones marked with appearance counts -- new open Predictions plus today's resolutions to the ledger -- new ArticleFrame rows -- DecisionEvidence linking today's situations to your standing decisions - -That accumulation is the point. The brief is the diff view onto it. - ---- - -## What's not modeled - -A few things deliberately don't exist as entities: -- **Unknown unknowns.** The Rumsfeld bucket is excluded by design. The tool does not fabricate observables it cannot ground. -- **Claim survival.** Computing per-source claim survival would require structured claim extraction we have not built. The `sources` command omits this signal honestly rather than computing a fake one. -- **Truth.** No entity stores a truth value. Predictions are graded for whether they *resolved*, not whether they were *right*. Frames have no "correct" status. The tool surfaces structure, not verdicts. +## Position and Decision + +`position.yaml`, at `POSITION_PATH`, outside this repository. It holds `version`, `reviewed` +(the date the operator last sat down with the file) and `decisions`. A decision has: + +- `key`: a slug, referenced by watches; +- `name`: one sentence the operator could act on; +- `deadline`: a date. The loader refuses a decision without one, because a decision with no + date is an interest, and interests are not what the system is for; +- `stake`: what is worse if the decision goes wrong. Missing, the loader warns. + +The loader (`src/position/position.py`) refuses structural problems, all of them at once, and +warns rather than refuses on drift: a file past two pages, a deadline already passed, a +decision with no stake. The brief carries a banner when `reviewed` is more than 90 days old, or +absent, or when the file could not be read at all. + +## Watch + +`watches.yaml`, at `WATCHES_PATH`, beside the Position. A watch is one pre-registered claim +serving one decision. Every field is required and none defaults (`src/position/_validate.py`): + +- `id`: a slug; the name every brief line carries; +- `claim`: the thing that is or is not true, phrased so that afterwards the operator could say + which; +- `belief`: the operator's probability at registration, 0.0 to 1.0. This is the prior; the + ledger below holds every later value; +- `so_what.decision`: a key from the Position. A watch naming no decision, or an unknown one, + is refused (invariant 2); +- `so_what.because`: what changes for that decision if the claim resolves. Printed back in the + adjudication prompt as the operator wrote it, never paraphrased; +- `triggers`: a list of clauses, below; +- `expires`: when the question stops mattering. Routing ignores an expired watch, and the brief + lists an expired, unresolved watch under DUE. The loader refuses a file that holds a watch + whose `expires` has passed, so the next `watch sync` fails until the operator grades the + watch (`watch resolve`) and then moves its date or removes it; removing it retires it, and a + retired watch leaves DUE; +- `staleness_alert_days`: after how many days with nothing routed the silence is itself + reported. A whole number of days or a cadence string such as `2w`. + +**Triggers.** A clause is a mapping over `terms`, `entities` and `sources`. Within a clause +every populated field must match; within a field any listed value will do; across clauses any +one firing routes the observation, and the first that fires is recorded. `terms` and +`entities` compile to word-boundary patterns (`CISA` is not inside `precisa`), and an all-caps +term matches case-sensitively (`BOD` matches, `body` does not). `sources` is a case-insensitive +exact match on a configured source's name. A trigger written as prose is refused by the loader +and again by the compiler (`src/routing/compile.py`), because a trigger that cannot be compiled +never fires, and the deleted prediction ledger held 33 free-text triggers that were never +graded for exactly that reason. + +**Sync.** `insightweaver watch sync` is the only path from the file to the `watches` table. A +watch that leaves the file is retired (`retired_at`), never deleted, because ledger rows and +evidence hang off it; a watch that returns is restored. There is no `watch add` (invariant 6). + +## Source and Observation + +A source is a row in `rss_feeds`: a configured feed from `config/feeds/`, or an adapter such +as the Federal Register documents API. Every adapter (`src/sources/`) emits the same +normalized item and stores it through one path, `src/sources/store.py`. An adapter that +cannot reach or cannot understand its upstream raises `SourceUnavailable`; it never returns an +empty list. Each attempt stamps the source row with its time and its error, if any, which is +what the brief's header prints. + +An observation (`observations`) is one thing a source published: + +- keyed by `content_hash`, a SHA-256 over the normalized payload, which includes the item's URL + and the source's URL, so re-fetching an unchanged document is a no-op while the same text from + two sources is two rows: who said it is part of what was observed, and grouping the pair back + together is the MinHash signature's job; +- immutable: an ORM update raises `ObservationIsImmutable`, and a database trigger refuses an + `UPDATE` issued any other way (invariant 3); +- signed: a MinHash over five-word shingles is written beside the payload, and + `NEAR_DUPLICATE_THRESHOLD` (default 0.7) decides when two observations are one story. The + brief groups a watch's evidence by these clusters, so twelve outlets carrying one wire story + are one item with twelve citations. + +`published_date` is the source's date when it gave one; `observed_at` is when the row was +written. Ordering in the brief is by published date, then observed date, then hash, so it is +total. + +## Route + +Tier 1. `insightweaver route` compiles every live watch's triggers, evaluates them over the +observations in the window, and writes one `routes` row per (observation, watch) that +matched, with the clause index that fired and when it was routed. The table is derived and +rebuildable (`route --rebuild` discards the live watches' links and routes the whole corpus +again; the new rows carry the rebuild's time, so QUIET's silence clock restarts for every watch +that matches anything). No model is involved; the routing regression test plants exact matches and near-miss substrings +and asserts which route. + +Everything that does not route is reported, grouped by near-duplicate cluster and by source, +because a trigger that misses is the operator's to fix and the report is where they see it. + +## Adjudication and Evidence + +Tier 2, and the only model call in the system (invariant 4). `insightweaver adjudicate` takes +every routed pair on an open watch that the current prompt version has not answered and asks +the model one structured question: does this item bear on this claim, in which direction, how +strongly, satisfying which clause, and why. The question is `src/evidence/prompt.py`; the +answer is validated against a pydantic schema (`src/evidence/claude_adjudicator.py`). + +- An **adjudication** (`adjudications`) is one call about one pair, whatever it answered: + `evidence`, `none`, or `failed`, with the audit id, the token counts the API reported, and + the rationale. A pair is asked once per prompt version, with one gap: `replay --commit` + writes evidence and no adjudication row, so a pair a replay judged not to be evidence is asked + once more by `adjudicate`. A failed call is recorded, not retried; retrying until an answer + looks right would make the replay below meaningless. +- **Evidence** (`evidence`) is the subset that bore on the claim: `direction` (`supports` or + `contradicts`; there is no neutral row), `magnitude` (a strength of bearing, not a + probability), and the `prompt_version` that produced it, per row. +- An API outage or a rejected request is neither an answer nor a verdict: the run stops with + the pair left pending, and the brief counts pending pairs under QUIET. + +**Prompt versions and replay.** The version written on every row is a hand-maintained label +(`claude-v1`). The prompt, its effort level, its caps and the schema are hashed into a +fingerprint that a test pins to that label, so a change to any of them fails the suite until +the label is bumped; a version cannot drift under the rows that carry it. `insightweaver replay +--prompt-version V` rebuilds evidence for a version over the routed pairs and diffs it against +what is stored, writing nothing; `--commit` replaces that version's rows and is the only path +that deletes evidence. The test suite's adjudicators are keyword stubs that live in the test +tree on purpose, so the replay machinery is exercised without a key. + +**The audit log.** `src/llm/audit.py` writes every request, in full, to `data/llm-audit/` +before it is sent, and the usage and stop reason of every response after. There is no way to +send a request without writing it. The log is for the operator's eyes; it is not a cache. + +## Belief ledger and Resolution + +`watch_beliefs` is append-only, enforced by database triggers and ORM guards. The first row +for a watch is the file's `belief`, labelled `file`, written at sync. `insightweaver watch +believe ID P --note` appends a row labelled `principal`; it refuses a retired watch (put it back +in the file and sync first). The file stays authoritative: whenever a sync finds the file's +belief different from the current belief, including after the operator moved it, it appends a +`file` row with a note naming the value it replaced. That is a recorded change, never a silent +overwrite, and it means the number in the file should be kept in step with the ledger or the +next sync moves the belief back (decided in backlog task 030). No code path in the tool moves a +belief on its own; a belief update rule is deferred until there are resolved watches to +calibrate one against. + +`insightweaver watch resolve ID --outcome yes|no --note` grades the claim, once, and sets +`resolved_at` on the watch. A resolved watch takes no further belief and leaves routing. A +retired watch may still be graded, because the operator may learn the answer after removing +the claim from the file. + +## Brief + +`insightweaver brief` is a pure function of the database, `--since` and `--as-of` +(`src/brief/select.py` selects, `src/brief/render.py` prints). No clock is read in the render +path, no iteration is unordered, and the golden test renders twice and compares bytes. Five +parts, in fixed order: + +1. **Header**: as of, the window, the Position's reviewed date with days since and the banner, + and one line per source with its last attempt (labelled as a failure when it was one) and + its count in the window. +2. **MOVED**: every watch that gained evidence in the window, live or not, with each cluster of + near-duplicate observations as one item citing hash, source, date, title, direction, + magnitude and prompt version. +3. **DUE**: decisions with a deadline inside the next 30 days or already past; open watches + expiring inside that horizon or already expired and unresolved. +4. **WATCHING**: every live watch with its belief as of the moment, its source and date, the + decision it serves, days to expiry, evidence in the window and the date of the last + evidence. +5. **QUIET**: watches with nothing routed inside their staleness window, sources that ran and + returned nothing, routed pairs no adjudication has answered, failed adjudications. Printed + with zeros; that is when the section carries information (invariant 5). + +A row in `briefs` records each render. The next brief's default window opens at the last brief +delivered before the start of today, so a second run the same morning reproduces the first +instead of reporting "nothing since ten minutes ago". `--dry-run` renders without recording. + +## Invariants + +1. Nothing sends. +2. Every watch names a decision. +3. Observations are immutable; evidence is derived. +4. One stochastic component. +5. Silence is distinguishable from breakage. +6. The system never authors watches. + +Each has a test that would fail if a change broke it; the tests are the specification. + +## What is not modeled + +- **Unknown unknowns.** The tool does not fabricate observables it cannot ground. A claim with + no trigger words is a claim that will never route, and the loader says so. +- **Truth.** No entity stores a truth value. A resolution records that the operator graded the + claim, not that the tool judged it; evidence records bearing, not correctness. +- **Frames.** The earlier product modeled the frame each source exhibits. The monitor does + not, and README.md says so under the third principle. +- **Automatic belief.** Every belief row was written by a person. diff --git a/docs/PLAN.md b/docs/PLAN.md new file mode 100644 index 0000000..59a9ee1 --- /dev/null +++ b/docs/PLAN.md @@ -0,0 +1,254 @@ +# InsightWeaver plan: the decision monitor + +Written 2026-09-22. Replaces `docs/ESTATE_PLAN.md` (written and deleted the same day), which +planned an estate graph with sensors. That plan was reviewed the same afternoon and cut to the scope below; section 8 records +what was cut and why, and section 7 keeps the decisions that still stand. + +**Observed** means read from the tree or git history; **assumed** means unverified and said so. + +--- + +## 1. Where the codebase stands + +The briefing product was deleted on 2026-08-31 (task 012). The monitoring re-architecture that +replaced it has three tasks built and the rest queued: + +| built | what | +|---|---| +| 013 | Position (decisions with deadlines, private YAML) and Watch (claim, belief, `so_what` -> decision, structured triggers, expires, staleness) with loaders that reject rather than default | +| 014 | immutable content-addressed `observations`, derived `evidence` with a per-row `prompt_version`, MinHash near-duplicate grouping, `replay`, a pluggable `Adjudicator` seam | +| 025 | the legacy article write path closed, so every stored article has an observation | +| 026 | credentials in the OS keychain, an audited model client that returns usage, secret scanning that can fail CI, the SDK on 1.x | + +Six invariants are enforced by tests and constraints: nothing sends anything; every Watch names a +decision; observations are immutable and evidence is derived; exactly one stochastic component; +silence is distinguishable from breakage; the system never authors its own watches. + +**What has never happened: the loop has never been run to a graded watch.** The ledger before the +rewrite held 33 predictions graded zero times. Position exists as an example. There is no command +today that ingests, routes, adjudicates or renders anything. Every earlier version stopped at this +point, and this plan is written to stop *after* it. + +## 2. The product + +A **decision monitor**. The operator writes down the decisions they are carrying, each with a +deadline and a stake, and the claims (watches) whose truth would change those decisions, each with +structured triggers and an expiry. Sources are read through adapters into an immutable corpus. +Deterministic routing selects the few observations that could bear on a watch. One model call +per routed pair judges whether it is evidence. A brief, run by hand, says what moved, what is due, +what is being watched, and what has gone quiet, and every line cites the observation hashes it +rests on. The operator adjusts belief and resolves watches; the tool never does either. + +**The measurable property** is inherited from the re-architecture: output scales with live watches, +not with news volume. The test of it is three weeks of real operation on the operator's own +professional watches, with the brief's own header counting moved items per period and at least one +watch resolved. That measurement is the deliverable this plan ends on. + +**What is deliberately not here.** No estate graph, no sensors beyond the two adapters, no belief +update rule, no synthesis pass, no MCP server, no cloud. Section 8 says why each was cut and what +would bring it back. + +## 3. Schema additions + +All additive, one migration created from the models (the `add_watches_table` pattern), +`--confirm` on the way down. Nothing existing is altered except `watches`, which gains columns. + +```sql +-- Tier 1 output: which observations are candidates for which watch. Derived and rebuildable. +CREATE TABLE routes ( + id INTEGER PRIMARY KEY, + observation_hash TEXT NOT NULL REFERENCES observations(content_hash), + watch_id TEXT NOT NULL REFERENCES watches(id), + clause_index INTEGER NOT NULL, -- the first trigger clause that fired + routed_at DATETIME NOT NULL, + UNIQUE (observation_hash, watch_id) +); + +-- Tier 2 run ledger: every pair the model was asked about, whatever it answered. +-- `evidence` (task 014) keeps holding the verdicts; this table is why a pair is not asked twice +-- and where the tokens went. outcome: 'evidence' | 'none' | 'failed'. +CREATE TABLE adjudications ( + id INTEGER PRIMARY KEY, + observation_hash TEXT NOT NULL REFERENCES observations(content_hash), + watch_id TEXT NOT NULL REFERENCES watches(id), + prompt_version TEXT NOT NULL, + outcome TEXT NOT NULL CHECK (outcome IN ('evidence','none','failed')), + error TEXT, -- validation or API failure text; never retried + audit_id TEXT, -- the src/llm/audit.py entry + input_tokens INTEGER NOT NULL DEFAULT 0, + output_tokens INTEGER NOT NULL DEFAULT 0, + created_at DATETIME NOT NULL, + UNIQUE (observation_hash, watch_id, prompt_version) +); + +-- Belief history, append-only. source: 'file' (from watches.yaml at sync) | 'principal'. +CREATE TABLE watch_beliefs ( + id INTEGER PRIMARY KEY, + watch_id TEXT NOT NULL REFERENCES watches(id), + belief REAL NOT NULL CHECK (belief >= 0.0 AND belief <= 1.0), + source TEXT NOT NULL, + note TEXT, + observed_at DATETIME NOT NULL +); +-- BEFORE UPDATE and BEFORE DELETE triggers refuse, as observations does for UPDATE. + +ALTER TABLE watches ADD COLUMN retired_at DATETIME; -- sync sets this; it never deletes +ALTER TABLE watches ADD COLUMN resolved_at DATETIME; +ALTER TABLE watches ADD COLUMN outcome TEXT CHECK (outcome IN ('yes','no')); +ALTER TABLE watches ADD COLUMN resolution_note TEXT; + +-- One row per brief rendered. Default `since` of the next brief is the last row before today. +CREATE TABLE briefs ( + id INTEGER PRIMARY KEY, + as_of DATETIME NOT NULL, + since DATETIME NOT NULL, + moved INTEGER NOT NULL, + quiet INTEGER NOT NULL, + rendered_sha TEXT NOT NULL +); +``` + +`watches.belief` becomes the value at registration. Current belief is the latest `watch_beliefs` +row. `sync_watches` writes a `file` row when a watch is added or its file belief changes, and +stops overwriting the column. + +## 4. Commands and modules + +One console script, `insightweaver`. The `estate` script and `src/estate/` from task 026 are +folded in: credentials move to `src/config/credentials.py`, `auth` to `src/cli/auth.py`. + +| command | does | writes | network | model | +|---|---|---|---|---| +| `auth set/status/clear` | keychain | keychain | no | no | +| `sources list/show` | inventory | no | no | no | +| `ingest [--since] [--source]` | every configured source through the adapter path; per-source fetched/inserted/unreachable/went-silent | `articles`, `observations`, `rss_feeds` | yes | no | +| `watch sync/list` | file -> table; retire, never delete | `watches`, `watch_beliefs` | no | no | +| `watch believe ID P --note` | operator belief | `watch_beliefs` | no | no | +| `watch resolve ID --outcome yes/no --note` | operator grading | `watches` | no | no | +| `route [--dry-run] [--rebuild]` | compile triggers, link candidates, report the unrouted clusters | `routes` | no | no | +| `adjudicate [--dry-run] [--limit]` | one structured call per routed pair without a verdict for this prompt version | `adjudications`, `evidence`, audit log | no | yes | +| `replay` | as today, over routed pairs | `evidence` with `--commit` | no | depends | +| `brief [--since] [--as-of] [--format] [--output] [--dry-run]` | the document | `briefs` (not with `--dry-run`) | no | no | +| `run` | ingest, route, adjudicate, brief, in that order | all of the above | yes | yes | + +Modules, each under 300 lines: + +- `src/routing/compile.py`: a watch's trigger clauses to predicates. `terms` and `entities` both + compile through `entity_matcher.term_pattern` with its shouted-term case rule; `sources` is a + case-insensitive exact match on the source name. Within a clause every populated field must + match; any clause fires the watch. There is no alias registry: an entity is a term until a watch + needs aliases, and that is its own task. +- `src/routing/route.py`: evaluate live watches over observations in a window, insert missing + links, report unrouted observations grouped by MinHash cluster and source. +- `src/evidence/claude_adjudicator.py`: the one `ClaudeAdjudicator`, prompt version `claude-v1`, + structured output validated against a pydantic verdict, failures recorded not retried. +- `src/evidence/adjudicate.py`: select pairs, call, write the ledger and evidence, total tokens. +- `src/brief/`: `sections.py` (the data types), `select.py` (the sections as data), `render.py` + (plain text and markdown, no timestamps beyond `as_of` and the data's own dates, deterministic + to the byte). +- `src/cli/{ingest,route,adjudicate,brief,run,auth}.py`: thin. + +The brief, in fixed order, each item citing observation hashes: + +1. **Header.** As of, window, Position reviewed date and days since (a banner past 90 days), each + source's last successful fetch and whether it returned nothing this window. +2. **MOVED.** Watches with new evidence in the window; evidence grouped by near-duplicate cluster + so twelve outlets carrying one story are one item; each item: direction, magnitude, prompt + version, source, date, title, hash. +3. **DUE.** Decisions with a deadline inside the window ahead or already past; watches expiring. +4. **WATCHING.** Every live watch: current belief and its source, decision, days to expiry, + evidence count in window, last evidence date. +5. **QUIET.** Watches with nothing routed for `staleness_alert_days`, with the date of the last + routed observation or "never"; sources that ran and returned nothing; adjudications that + failed. Printed even when every count is zero. + +The adjudication prompt carries the epistemic rules from the deleted `ANALYSIS_RULES.md` that +still apply to a single judgement: direction is two-valued or absent; magnitude is a strength +of bearing, not a probability; a claim the observation does not address is not evidence; no +recommendation, no inference beyond the text. The observation text sent is capped and the cap is +recorded in the audit entry. + +## 5. Delivery order + +Each task is a `backlog/NNN-*.md` with acceptance, out of scope and landmines, one commit each +on `estate/026-phase0-hygiene` (renamed to `monitor/phase1` at the end), reviewed as one PR or +split. `make check` passes at every commit. The user pushes; nothing here pushes. + +| task | size | content | +|---|---|---| +| 027 sweep | small | delete the dead modules and files in section 6; fold `estate` into `insightweaver`; trim `FeedMatcher` to loading; drop the REPL; fix the dead test fixtures | +| 028 ingest and route | medium | `ingest` over every configured feed with bounded concurrency; `routes`; `route --dry-run`; the whole-word regression test (planted matches route, planted substrings do not) | +| 029 adjudicate | medium | `ClaudeAdjudicator`, `adjudications`, `adjudicate --dry-run`, token totals, replay over routed pairs, the no-retry rule tested | +| 030 belief and resolution | small | `watch_beliefs`, `watch believe`, `watch resolve`, `retired_at` on sync | +| 031 brief | medium | the four sections, `briefs`, `run`, golden-file end-to-end test over recorded fixtures with a stub adjudicator | +| 032 onboarding | small | a `.claude/skills/onboard/` skill that interviews for stakes, writes Position and watches to the private directory, and ends by running `watch sync` | +| 033 docs | medium | README, GETTING_STARTED and CONCEPTS rewritten from what exists; SOURCES unchanged | + +Then: run it for three weeks. Task 034 is written after that with the observed numbers. + +## 6. Changes to existing behaviour + +1. **Deleted** (task 027): `src/processors/` (content filter, pairwise deduplicator), `src/utils/ + profile_loader.py`, `src/feed_manager.py`, `src/utils/logging.py`, `src/utils/profiler.py`, + `src/rss/parallel_fetcher.py`, `src/matching/coverage_probe.py` and `CoverageProbe`, the + top-level `migrations/`, `config/user_profile.example.json`, `config/context_modules/`, + `config/probes/`, `main.py`, `src/__main__.py`, the interactive REPL in `src/cli/app.py`, the + `data/forecasts` and `data/newsletters` placeholders, and the `tests/conftest.py` fixtures that + patch deleted modules. Each has no live caller (verified by tree search and by an adversarial + review recorded in the task file). `deduplicator.py` was an "explicit keep" in task 012; it + reads the legacy `articles` table and task 014 recorded why MinHash superseded it. +2. **`src/estate/` folded into `insightweaver`** (task 027). One command. +3. **`sync_watches` retires instead of deleting**, and stops overwriting belief (task 030). +4. **`replay` rebuilds over routed pairs**, not every (observation, watch) product (task 029). + The stub tests route their fixture corpus through the real router. +5. **`ClaudeClient` becomes synchronous.** Its only consumer is a synchronous adjudication loop + inside a click command; the async client was a leftover from the deleted pipeline. +6. **`FeedMatcher` loses profile matching**; it loads `config/feeds/` and nothing else. Every feed + in that directory is ingested. Curation is editing that directory. +7. **`run_adapters` gains bounded concurrency** for RSS (a semaphore of five). Sequential was + right for two API adapters; it is not right for forty feeds with thirty-second timeouts. + +## 7. Decisions on record (2026-09-22) + +- Laptop only; nothing sends anything; tasks 019, 020, 023 superseded, 018 rewritten (Q1). +- PIR = Watch; no threat or indicator types (Q3). +- One belief ledger, file as prior, operator writes, no automatic update (Q5, and the 017 cut). +- Two observation tables would have had a stated rule; there is now one table, because the grid is + deferred (Q4, superseded). +- Package location `src/`, one console script (Q4, revised from `src/estate/`). +- Anthropic key in the keychain, no fallback (Q5). Sonnet 5 adjudicates; Opus 5 is named for + synthesis but synthesis is deferred (Q11). +- Triage starts against an empty corpus on this machine (Q14). +- Docs rewritten from scratch in task 033 (Q12). + +## 8. Deferred, with what would bring each back + +- **The estate graph** (nodes, edges, grid observations, current-state view, recursive CTEs). + Deferred because without a sensor other than the operator, the graph records what the operator + typed and the brief diffs it. Returns in the same task as the first sensor that writes to it, + sized to what that sensor observes. +- **Sensors.** Ranked on 2026-09-22 by whether they reveal what the operator would otherwise miss: + email metadata bound per institution (the notice not opened, and absence: "the insurer has not + written in 400 days"); a finance aggregator (runway against a dated decision); public rate + series (a threshold the operator set, weekly). Calendar, property records and weather were judged + not worth building. Correction to what was said in conversation: the FRED API requires a free + key; the keyless options are the Treasury Fiscal Data API and the Freddie Mac PMMS download. A + numeric series needs a `series` trigger clause evaluated in Tier 1, which is one small task when + a watch needs it. +- **A belief update rule** (task 017's hysteresis and debouncing). The brief already collapses + near-duplicates into one item; whether beliefs should move without the operator is a question to + answer after there are resolved watches to calibrate against. +- **Synthesis** (a second model pass phrasing the world-join section). After a deterministic brief + has been read for three weeks. +- **MCP server.** After the CLI is used. +- **Google and finance integrations.** After a graded watch, one sensor per task, recorded + fixtures, off by default. + +## 9. Assumptions + +- The operator's private repository holds `position.yaml` and `watches.yaml`, at `POSITION_PATH` + and `WATCHES_PATH`, and the professional watches in it are the ones the three-week run uses. +- `config/feeds/` is the operator's curated source list. Some URLs in it are old and will report + unreachable; that is the brief's job to show, not this plan's job to fix. +- Sonnet 5 accepts `output_config.format` structured output; verified against the SDK skill docs, + not against a live call from this machine. diff --git a/docs/RECONCILIATION.md b/docs/RECONCILIATION.md index d2cd15f..c4f7ae6 100644 --- a/docs/RECONCILIATION.md +++ b/docs/RECONCILIATION.md @@ -51,3 +51,19 @@ several genuinely careful pieces of engineering -- the offline render path, the the person-tracking boundary. It was wrong because a document of constant length emitted on a fixed schedule cannot carry information about whether anything happened. That is a property of the shape, not of the implementation quality, which is exactly why better synthesis was never going to fix it. + +## Addendum, 2026-09-22: the decision monitor is the plan + +The monitoring re-architecture above resolved *which product this is* -- a commitment graph, not +a briefing generator -- and built its first three tasks. On 2026-09-22 an estate-brief plan was +written on top of it, reviewed the same afternoon, and cut back: the estate graph and its sensors +are deferred until a sensor other than the operator exists to write to them, and what remains is +the **decision monitor** -- Position, watches, deterministic routing, one adjudication call per +routed pair, a brief run by hand, belief and resolution written only by the operator. + +`docs/PLAN.md` is the plan from here. Its section 2 states the product and the property it must +demonstrate, section 6 lists the changes to existing behaviour, section 7 records the decisions, +and section 8 records what was cut and what would bring each back. Two of those decisions change +this note's own claims: there is no notification path and no deployment -- everything runs on +demand on the operator's laptop and nothing sends anything -- so "the notification is the update +event" above is now "the brief is the update event, run by hand". The graph is still the artifact. diff --git a/main.py b/main.py deleted file mode 100755 index 2b2d4ef..0000000 --- a/main.py +++ /dev/null @@ -1,16 +0,0 @@ -#!/usr/bin/env python3 -""" -InsightWeaver - Main Application Entry Point -Multi-command CLI for intelligent RSS feed analysis and trust verification -""" - -import sys -from pathlib import Path - -# Add src to path if running directly -sys.path.insert(0, str(Path(__file__).parent / "src")) - -from src.cli.app import cli - -if __name__ == "__main__": - cli() diff --git a/migrations/001_optimize_for_context_engineering.py b/migrations/001_optimize_for_context_engineering.py deleted file mode 100644 index 3f51572..0000000 --- a/migrations/001_optimize_for_context_engineering.py +++ /dev/null @@ -1,188 +0,0 @@ -""" -Migration: Optimize Database for Context Engineering - -Changes: -1. Add context-optimized fields to articles table -2. Add context_snapshots table -3. Update narrative_syntheses table -4. Update analysis_runs table -5. Mark trend_analyses and predictions as deprecated (to be removed later) - -Run with: python migrations/001_optimize_for_context_engineering.py -""" - -import sys -from pathlib import Path - -# Add src to path -sys.path.insert(0, str(Path(__file__).parent.parent / "src")) - -from sqlalchemy import text - -from src.database.connection import get_db - - -def migrate_up(): - """Apply migration""" - print("Starting migration: Optimize for Context Engineering") - - with get_db() as session: - # 1. Add new fields to articles table - print(" 1. Adding context-optimized fields to articles table...") - - try: - session.execute( - text(""" - ALTER TABLE articles - ADD COLUMN embedding_summary TEXT, - ADD COLUMN relevance_score REAL, - ADD COLUMN last_included_in_synthesis DATETIME - """) - ) - print(" ✓ Added: embedding_summary, relevance_score, last_included_in_synthesis") - except Exception as e: - print(f" Note: Fields may already exist: {e}") - - # 2. Add indexes for context selection - print(" 2. Adding indexes for context selection...") - - try: - session.execute( - text(""" - CREATE INDEX IF NOT EXISTS idx_relevance_score ON articles(relevance_score) - """) - ) - session.execute( - text(""" - CREATE INDEX IF NOT EXISTS idx_filtered ON articles(filtered) - """) - ) - print(" ✓ Added indexes: idx_relevance_score, idx_filtered") - except Exception as e: - print(f" Note: Indexes may already exist: {e}") - - # 3. Create context_snapshots table - print(" 3. Creating context_snapshots table...") - - try: - session.execute( - text(""" - CREATE TABLE IF NOT EXISTS context_snapshots ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - synthesis_id INTEGER, - article_ids TEXT, - context_size_tokens INTEGER, - user_profile_hash VARCHAR(64), - historical_summaries TEXT, - instructions TEXT, - created_at DATETIME DEFAULT CURRENT_TIMESTAMP - ) - """) - ) - session.execute( - text(""" - CREATE INDEX IF NOT EXISTS idx_context_created_at ON context_snapshots(created_at) - """) - ) - print(" ✓ Created: context_snapshots table") - except Exception as e: - print(f" Note: Table may already exist: {e}") - - # 4. Add new fields to narrative_syntheses - print(" 4. Updating narrative_syntheses table...") - - try: - session.execute( - text(""" - ALTER TABLE narrative_syntheses - ADD COLUMN context_snapshot_id INTEGER REFERENCES context_snapshots(id) - """) - ) - session.execute( - text(""" - CREATE INDEX IF NOT EXISTS idx_narrative_profile_version - ON narrative_syntheses(user_profile_version) - """) - ) - print(" ✓ Added: context_snapshot_id, index on user_profile_version") - except Exception as e: - print(f" Note: Fields may already exist: {e}") - - # 5. Add new fields to analysis_runs - print(" 5. Updating analysis_runs table...") - - try: - session.execute( - text(""" - ALTER TABLE analysis_runs - ADD COLUMN context_token_count INTEGER, - ADD COLUMN claude_model VARCHAR(100) - """) - ) - session.execute( - text(""" - CREATE INDEX IF NOT EXISTS idx_run_started_at ON analysis_runs(started_at) - """) - ) - print(" ✓ Added: context_token_count, claude_model") - except Exception as e: - print(f" Note: Fields may already exist: {e}") - - # 6. Initialize relevance_score for existing articles (recency-based) - print(" 6. Initializing relevance_score for existing articles...") - - try: - session.execute( - text(""" - UPDATE articles - SET relevance_score = julianday('now') - julianday(fetched_at) - WHERE relevance_score IS NULL AND fetched_at IS NOT NULL - """) - ) - print(" ✓ Initialized relevance_score based on recency") - except Exception as e: - print(f" Warning: {e}") - - session.commit() - - print("\n✅ Migration complete!") - print("\nNext steps:") - print(" - Old tables (trend_analyses, predictions) are marked deprecated") - print(" - They can be dropped after verifying synthesis data contains all needed info") - print(" - Old article fields (priority_score, priority_metadata, trend_metadata)") - print(" can be dropped in a future migration after verifying they're unused") - - -def migrate_down(): - """Rollback migration (if needed)""" - print("Rolling back migration: Optimize for Context Engineering") - - with get_db() as session: - # Remove new fields and tables in reverse order - print(" Removing context_snapshots table...") - try: - session.execute(text("DROP TABLE IF EXISTS context_snapshots")) - except Exception as e: - print(f" Warning: {e}") - - print(" Removing new fields from articles...") - # Note: SQLite doesn't support DROP COLUMN easily - # Would need to recreate table to remove columns - print(" Note: Column removal requires table recreation in SQLite") - - session.commit() - - print("✅ Rollback complete!") - - -if __name__ == "__main__": - import argparse - - parser = argparse.ArgumentParser(description="Database migration for context engineering") - parser.add_argument("--down", action="store_true", help="Rollback migration") - args = parser.parse_args() - - if args.down: - migrate_down() - else: - migrate_up() diff --git a/migrations/002_cleanup_deprecated_fields.py b/migrations/002_cleanup_deprecated_fields.py deleted file mode 100644 index ffe6115..0000000 --- a/migrations/002_cleanup_deprecated_fields.py +++ /dev/null @@ -1,163 +0,0 @@ -""" -Migration: Cleanup Deprecated Fields (Phase 2) - -This migration should be run AFTER verifying that: -1. Synthesis data contains all trend/prediction information -2. Old agent fields (priority_score, etc.) are no longer referenced in code - -Changes: -1. Drop deprecated tables: trend_analyses, predictions -2. Remove deprecated fields from articles: priority_score, priority_metadata, trend_metadata -3. Remove trends_analyzed from narrative_syntheses - -DO NOT RUN THIS IMMEDIATELY - Run after validation period -""" - -import sys -from pathlib import Path - -sys.path.insert(0, str(Path(__file__).parent.parent / "src")) - -from sqlalchemy import text - -from src.database.connection import get_db - - -def migrate_up(): - """Apply cleanup migration""" - print("⚠️ WARNING: This migration removes deprecated tables and fields") - print(" Make sure you have verified that:") - print(" 1. Synthesis data contains all needed trend/prediction info") - print(" 2. Code no longer references old agent fields") - print("") - - response = input("Continue with cleanup? (yes/no): ") - if response.lower() != "yes": - print("Migration cancelled") - return - - print("\nStarting cleanup migration...") - - with get_db() as session: - # 1. Drop deprecated tables - print(" 1. Dropping deprecated tables...") - - try: - session.execute(text("DROP TABLE IF EXISTS predictions")) - print(" ✓ Dropped: predictions") - except Exception as e: - print(f" Error: {e}") - - try: - session.execute(text("DROP TABLE IF EXISTS trend_analyses")) - print(" ✓ Dropped: trend_analyses") - except Exception as e: - print(f" Error: {e}") - - # 2. Remove deprecated fields from articles - # SQLite requires recreating the table to drop columns - print(" 2. Removing deprecated fields from articles...") - print(" Note: Requires table recreation in SQLite") - - try: - # Create new articles table without deprecated fields - session.execute( - text(""" - CREATE TABLE articles_new ( - id INTEGER PRIMARY KEY, - feed_id INTEGER, - guid VARCHAR(500) NOT NULL, - url VARCHAR(500), - title VARCHAR(500), - description TEXT, - content TEXT, - published_date DATETIME, - author VARCHAR(200), - categories TEXT, - normalized_content TEXT, - word_count INTEGER, - language VARCHAR(10), - entities TEXT, - embedding_summary TEXT, - relevance_score REAL, - last_included_in_synthesis DATETIME, - filtered BOOLEAN DEFAULT 0, - filter_reason VARCHAR(200), - fetched_at DATETIME, - created_at DATETIME, - FOREIGN KEY (feed_id) REFERENCES rss_feeds(id), - UNIQUE(feed_id, guid) - ) - """) - ) - - # Copy data - session.execute( - text(""" - INSERT INTO articles_new - SELECT - id, feed_id, guid, url, title, description, content, - published_date, author, categories, normalized_content, - word_count, language, entities, embedding_summary, - relevance_score, last_included_in_synthesis, filtered, - filter_reason, fetched_at, created_at - FROM articles - """) - ) - - # Drop old table and rename - session.execute(text("DROP TABLE articles")) - session.execute(text("ALTER TABLE articles_new RENAME TO articles")) - - # Recreate indexes - session.execute( - text(""" - CREATE INDEX idx_published_date ON articles(published_date) - """) - ) - session.execute( - text(""" - CREATE INDEX idx_fetched_at ON articles(fetched_at) - """) - ) - session.execute( - text(""" - CREATE INDEX idx_relevance_score ON articles(relevance_score) - """) - ) - session.execute( - text(""" - CREATE INDEX idx_filtered ON articles(filtered) - """) - ) - - print(" ✓ Removed: priority_score, priority_metadata, trend_metadata") - - except Exception as e: - print(f" Error: {e}") - print(" You may need to manually recreate the articles table") - - # 3. Remove trends_analyzed from narrative_syntheses - print(" 3. Updating narrative_syntheses table...") - print(" Note: SQLite limitation - keeping trends_analyzed field") - print(" (Can be ignored, will always be 0)") - - session.commit() - - print("\n✅ Cleanup migration complete!") - print("\nDatabase is now fully optimized for context engineering") - - -if __name__ == "__main__": - print("=" * 60) - print("PHASE 2 CLEANUP MIGRATION") - print("=" * 60) - print("\nThis is a destructive migration that removes:") - print(" - trend_analyses table") - print(" - predictions table") - print(" - priority_score, priority_metadata, trend_metadata from articles") - print("\nOnly run this after validating Phase 1 migration works correctly") - print("=" * 60) - print("") - - migrate_up() diff --git a/migrations/README.md b/migrations/README.md deleted file mode 100644 index 18ec6b5..0000000 --- a/migrations/README.md +++ /dev/null @@ -1,43 +0,0 @@ -# Database Migrations for Context Engineering - -## Overview -These migrations optimize the InsightWeaver database for the context engineering approach, removing agent-specific fields and adding context curation capabilities. - -## Migration Strategy - -### Phase 1: Add New Fields (SAFE - Run Now) -**File:** `001_optimize_for_context_engineering.py` - -**What it does:** -- Adds new fields to `articles` table for context engineering -- Creates `context_snapshots` table for reproducibility -- Updates `narrative_syntheses` and `analysis_runs` tables -- **Does NOT remove any existing data** - -**Run with:** -```bash -python migrations/001_optimize_for_context_engineering.py -``` - -### Phase 2: Cleanup Deprecated Fields (Run After Validation) -**File:** `002_cleanup_deprecated_fields.py` - -**What it does:** -- Removes deprecated tables: `trend_analyses`, `predictions` -- Removes deprecated fields from `articles` -- **This is destructive - only run after validating Phase 1 works** - -## Testing - -```bash -# Backup database -cp data/insightweaver.db data/insightweaver.db.backup - -# Run Phase 1 -python migrations/001_optimize_for_context_engineering.py - -# Test system -python main.py -``` - -See file for full documentation. diff --git a/pyproject.toml b/pyproject.toml index 514cf4a..e7ae208 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,19 +23,20 @@ classifiers = [ ] dependencies = [ - "anthropic>=0.39.0", - "aiohttp>=3.10.11", + # 1.x: output_config is a named parameter and messages.parse() exists, + # which Tier 2's structured output needs (2026-09-22, backlog task 026). + "anthropic>=1.7,<2", "feedparser>=6.0.11", "python-dotenv>=1.0.1", "pyyaml>=6.0.2", - "rich>=13.9.4", "httpx>=0.28.1", - "requests>=2.32.3", "beautifulsoup4>=4.12.3", - "lxml>=5.3.0", "sqlalchemy>=2.0.0", "pydantic-settings>=2.0.0", + "pydantic>=2.0", "click>=8.0.0", + # Credentials live in the OS keychain (src/config/credentials.py). + "keyring>=25.0", ] [project.optional-dependencies] @@ -44,20 +45,24 @@ dev = [ "pytest-asyncio>=0.23.0", "pytest-mock>=3.12.0", "pytest-cov>=4.1.0", - "aioresponses>=0.7.6", "ruff>=0.8.4", "mypy>=1.13.0", "pre-commit>=4.0.1", "pip-tools>=7.4.1", + # Secret scanning, in pre-commit and CI (2026-09-22, backlog task 026). + "detect-secrets>=1.5.0", + # `make typecheck` needs the PyYAML stubs; pre-commit already installed them + # for its own mypy hook, so the gate passed there and failed in a plain venv. + "types-PyYAML", ] [project.scripts] insightweaver = "src.cli.app:cli" [project.urls] -Homepage = "https://github.com/yourusername/insightweaver" -Repository = "https://github.com/yourusername/insightweaver" -Issues = "https://github.com/yourusername/insightweaver/issues" +Homepage = "https://github.com/sam-aydlette/InsightWeaver" +Repository = "https://github.com/sam-aydlette/InsightWeaver" +Issues = "https://github.com/sam-aydlette/InsightWeaver/issues" [tool.setuptools.packages.find] where = ["."] @@ -79,11 +84,6 @@ addopts = [ "--cov-report=term-missing", "--cov-report=html", ] -markers = [ - "slow: marks tests as slow (deselect with '-m \"not slow\"')", - "integration: marks tests as integration tests", - "unit: marks tests as unit tests", -] [tool.coverage.run] source = ["src"] @@ -181,11 +181,9 @@ ignore_errors = true # descriptors mypy reads as their column type, which predates this task. [[tool.mypy.overrides]] module = [ - "src.processors.*", "src.rss.*", "src.matching.*", "src.llm.*", - "src.feed_manager", ] ignore_errors = true @@ -194,6 +192,5 @@ module = [ "src.cli.*", "src.utils.*", "src.config.*", - "src.__main__", ] ignore_errors = true diff --git a/requirements-dev.txt b/requirements-dev.txt index 51e4629..8a4dd06 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,33 +1,20 @@ # -# This file is autogenerated by pip-compile with Python 3.13 +# This file is autogenerated by pip-compile with Python 3.14 # by the following command: # # pip-compile --extra=dev --output-file=requirements-dev.txt pyproject.toml # -aiohappyeyeballs==2.6.1 - # via aiohttp -aiohttp==3.13.2 - # via - # aioresponses - # insightweaver (pyproject.toml) -aioresponses==0.7.8 - # via insightweaver (pyproject.toml) -aiosignal==1.4.0 - # via aiohttp annotated-types==0.7.0 # via pydantic -anthropic==0.75.0 +anthropic==1.7.0 # via insightweaver (pyproject.toml) anyio==4.12.0 # via # anthropic # httpx -attrs==25.4.0 - # via aiohttp + # httpx2 beautifulsoup4==4.14.3 - # via - # insightweaver (pyproject.toml) - # markdownify + # via insightweaver (pyproject.toml) build==1.3.0 # via pip-tools certifi==2025.11.12 @@ -35,85 +22,86 @@ certifi==2025.11.12 # httpcore # httpx # requests +cffi==2.1.1 + # via cryptography cfgv==3.5.0 # via pre-commit charset-normalizer==3.4.4 # via requests click==8.3.1 # via - # nltk + # insightweaver (pyproject.toml) # pip-tools coverage[toml]==7.13.1 # via pytest-cov +cryptography==50.0.1 + # via secretstorage +detect-secrets==1.5.0 + # via insightweaver (pyproject.toml) distlib==0.4.0 # via virtualenv -distro==1.9.0 - # via anthropic docstring-parser==0.17.0 # via anthropic feedparser==6.0.12 # via insightweaver (pyproject.toml) filelock==3.20.1 # via virtualenv -frozenlist==1.8.0 - # via - # aiohttp - # aiosignal greenlet==3.3.0 # via sqlalchemy h11==0.16.0 - # via httpcore + # via + # httpcore + # httpcore2 httpcore==1.0.9 # via httpx +httpcore2==2.3.0 + # via httpx2 httpx==0.28.1 - # via - # anthropic - # insightweaver (pyproject.toml) + # via insightweaver (pyproject.toml) +httpx2==2.3.0 + # via anthropic identify==2.6.15 # via pre-commit idna==3.11 # via # anyio # httpx + # httpx2 # requests - # yarl iniconfig==2.3.0 # via pytest +jaraco-classes==3.4.0 + # via keyring +jaraco-context==6.1.2 + # via keyring +jaraco-functools==4.6.0 + # via keyring +jeepney==0.9.0 + # via + # keyring + # secretstorage jiter==0.12.0 # via anthropic -joblib==1.5.3 - # via nltk +keyring==25.7.0 + # via insightweaver (pyproject.toml) librt==0.7.5 # via mypy -lxml==6.0.2 - # via insightweaver (pyproject.toml) -markdown-it-py==4.0.0 - # via rich -markdownify==1.2.2 - # via insightweaver (pyproject.toml) -mdurl==0.1.2 - # via markdown-it-py -multidict==6.7.0 +more-itertools==11.1.0 # via - # aiohttp - # yarl + # jaraco-classes + # jaraco-functools mypy==1.19.1 # via insightweaver (pyproject.toml) mypy-extensions==1.1.0 # via mypy -nltk==3.9.2 - # via textblob nodeenv==1.10.0 # via pre-commit packaging==25.0 # via - # aioresponses # build # pytest pathspec==0.12.1 # via mypy -pillow==12.0.0 - # via insightweaver (pyproject.toml) pip-tools==7.5.2 # via insightweaver (pyproject.toml) platformdirs==4.5.1 @@ -124,22 +112,19 @@ pluggy==1.6.0 # pytest-cov pre-commit==4.5.1 # via insightweaver (pyproject.toml) -propcache==0.4.1 - # via - # aiohttp - # yarl +pycparser==3.0 + # via cffi pydantic==2.12.5 # via # anthropic + # insightweaver (pyproject.toml) # pydantic-settings pydantic-core==2.41.5 # via pydantic pydantic-settings==2.12.0 # via insightweaver (pyproject.toml) pygments==2.19.2 - # via - # pytest - # rich + # via pytest pyproject-hooks==1.2.0 # via # build @@ -162,30 +147,29 @@ python-dotenv==1.2.1 # pydantic-settings pyyaml==6.0.3 # via + # detect-secrets # insightweaver (pyproject.toml) # pre-commit -regex==2025.11.3 - # via nltk requests==2.32.5 - # via insightweaver (pyproject.toml) -rich==14.2.0 - # via insightweaver (pyproject.toml) + # via detect-secrets ruff==0.14.10 # via insightweaver (pyproject.toml) +secretstorage==3.5.0 + # via keyring sgmllib3k==1.0.0 # via feedparser -six==1.17.0 - # via markdownify sniffio==1.3.1 # via anthropic soupsieve==2.8.1 # via beautifulsoup4 sqlalchemy==2.0.45 # via insightweaver (pyproject.toml) -textblob==0.19.0 +truststore==0.10.4 + # via + # httpcore2 + # httpx2 +types-pyyaml==6.0.12.20260906 # via insightweaver (pyproject.toml) -tqdm==4.67.1 - # via nltk typing-extensions==4.15.0 # via # anthropic @@ -205,8 +189,6 @@ virtualenv==20.35.4 # via pre-commit wheel==0.45.1 # via pip-tools -yarl==1.22.0 - # via aiohttp # The following packages are considered to be unsafe in a requirements file: # pip diff --git a/requirements.txt b/requirements.txt index 39ba7cc..cfeedf7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,96 +1,90 @@ # -# This file is autogenerated by pip-compile with Python 3.13 +# This file is autogenerated by pip-compile with Python 3.14 # by the following command: # # pip-compile --output-file=requirements.txt pyproject.toml # -aiohappyeyeballs==2.6.1 - # via aiohttp -aiohttp==3.13.2 - # via insightweaver (pyproject.toml) -aiosignal==1.4.0 - # via aiohttp annotated-types==0.7.0 # via pydantic -anthropic==0.75.0 +anthropic==1.7.0 # via insightweaver (pyproject.toml) anyio==4.12.0 # via # anthropic # httpx -attrs==25.4.0 - # via aiohttp + # httpx2 beautifulsoup4==4.12.3 # via insightweaver (pyproject.toml) certifi==2025.11.12 # via # httpcore # httpx - # requests -charset-normalizer==3.4.4 - # via requests +cffi==2.1.1 + # via cryptography click==8.3.1 # via insightweaver (pyproject.toml) -distro==1.9.0 +cryptography==50.0.1 + # via secretstorage +docstring-parser==0.18.0 # via anthropic feedparser==6.0.11 # via insightweaver (pyproject.toml) -frozenlist==1.8.0 - # via - # aiohttp - # aiosignal greenlet==3.3.0 # via sqlalchemy h11==0.16.0 - # via httpcore + # via + # httpcore + # httpcore2 httpcore==1.0.9 # via httpx +httpcore2==2.3.0 + # via httpx2 httpx==0.28.1 - # via - # anthropic - # insightweaver (pyproject.toml) + # via insightweaver (pyproject.toml) +httpx2==2.3.0 + # via anthropic idna==3.11 # via # anyio # httpx - # requests - # yarl + # httpx2 +jaraco-classes==3.4.0 + # via keyring +jaraco-context==6.1.2 + # via keyring +jaraco-functools==4.6.0 + # via keyring +jeepney==0.9.0 + # via + # keyring + # secretstorage jiter==0.12.0 # via anthropic -lxml==6.0.2 +keyring==25.7.0 # via insightweaver (pyproject.toml) -markdown-it-py==4.0.0 - # via rich -mdurl==0.1.2 - # via markdown-it-py -multidict==6.7.0 +more-itertools==11.1.0 # via - # aiohttp - # yarl -propcache==0.4.1 - # via - # aiohttp - # yarl + # jaraco-classes + # jaraco-functools +pycparser==3.0 + # via cffi pydantic==2.12.5 # via # anthropic + # insightweaver (pyproject.toml) # pydantic-settings pydantic-core==2.41.5 # via pydantic pydantic-settings==2.12.0 # via insightweaver (pyproject.toml) -pygments==2.19.2 - # via rich python-dotenv==1.0.1 # via # insightweaver (pyproject.toml) # pydantic-settings pyyaml==6.0.2 # via insightweaver (pyproject.toml) -requests==2.32.5 - # via insightweaver (pyproject.toml) -rich==14.2.0 - # via insightweaver (pyproject.toml) +secretstorage==3.5.0 + # via keyring sgmllib3k==1.0.0 # via feedparser sniffio==1.3.1 @@ -99,6 +93,10 @@ soupsieve==2.8.1 # via beautifulsoup4 sqlalchemy==2.0.45 # via insightweaver (pyproject.toml) +truststore==0.10.4 + # via + # httpcore2 + # httpx2 typing-extensions==4.15.0 # via # anthropic @@ -110,7 +108,3 @@ typing-inspection==0.4.2 # via # pydantic # pydantic-settings -urllib3==2.6.2 - # via requests -yarl==1.22.0 - # via aiohttp diff --git a/src/__main__.py b/src/__main__.py deleted file mode 100644 index 1506be9..0000000 --- a/src/__main__.py +++ /dev/null @@ -1,15 +0,0 @@ -""" -InsightWeaver package main module -Allows running as: python -m src -""" - -import sys -from pathlib import Path - -# Add parent to path to import main -sys.path.insert(0, str(Path(__file__).parent.parent)) - -from main import main - -if __name__ == "__main__": - main() diff --git a/src/brief/__init__.py b/src/brief/__init__.py new file mode 100644 index 0000000..223d6c3 --- /dev/null +++ b/src/brief/__init__.py @@ -0,0 +1,16 @@ +""" +The brief: what moved, what is due, what is watched, what went quiet. + +Two modules. :mod:`select` reads the database and the Position into plain +data, pure in ``(db, as_of, since, position)``; :mod:`render` turns that data +into text and adds nothing. No model call happens on this path, and nothing +here reads a clock: ``as_of`` is an argument, so the same inputs give the +same bytes, which a test asserts by rendering twice. + +Added 2026-09-22 for backlog task 031. +""" + +from .render import render +from .select import HORIZON_DAYS, REVIEW_BANNER_DAYS, Brief, select_brief + +__all__ = ["HORIZON_DAYS", "REVIEW_BANNER_DAYS", "Brief", "render", "select_brief"] diff --git a/src/brief/render.py b/src/brief/render.py new file mode 100644 index 0000000..0afe3ad --- /dev/null +++ b/src/brief/render.py @@ -0,0 +1,216 @@ +""" +The brief as text, deterministic to the byte, in two flavours that differ only +in headings: plain terminal text and markdown. + +No wall-clock read, no colour codes, no row ids: everything printed comes from +the :class:`~src.brief.sections.Brief` it is handed, and the same brief renders +the same bytes forever. Every citation carries the observation hash it rests +on, shortened to a prefix long enough to be unique in any corpus this tool will +hold and short enough to read; ``sources show`` and the audit log take the +full hash. Every heading is printed, with a zero, when its section is empty: +a brief that looks the same when nothing happened and when the pipeline is +broken is the failure this design exists to prevent. + +**The source header is compact by default** (``verbose=False``): a source +that answered, whatever it returned, is folded into the summary counts. A +source whose last attempt *failed* is never folded -- it is printed in full, +every time, because that is the one line invariant 5 exists to guarantee. +``--verbose`` on the CLI prints every source individually, as the header +always did before 2026-09-24. + +Added 2026-09-22 for backlog task 031; reworked 2026-09-23 after its review; +the compact header added 2026-09-24 at the operator's request, after a first +real run showed a ~70-source header burying the four sections worth reading +daily. +""" + +from __future__ import annotations + +from datetime import datetime + +from .sections import Brief, Citation + +__all__ = ["HASH_CHARS", "render", "short"] + +# Hex characters of a content hash printed after ``sha256:``. Twelve is 48 +# bits; a collision needs on the order of sixteen million observations. +HASH_CHARS = 12 + + +def short(content_hash: str) -> str: + return content_hash[: len("sha256:") + HASH_CHARS] + + +def _stamp(when: datetime) -> str: + return when.strftime("%Y-%m-%d %H:%M") + + +class _Doc: + def __init__(self, markdown: bool) -> None: + self.markdown = markdown + self.lines: list[str] = [] + + def title(self, text: str) -> None: + self.lines.append(f"# {text}" if self.markdown else text.upper()) + + def section(self, text: str) -> None: + self.lines.append("") + self.lines.append(f"## {text}" if self.markdown else text) + if not self.markdown: + self.lines.append("-" * len(text)) + + def line(self, text: str = "") -> None: + self.lines.append(text) + + def bullet(self, text: str, depth: int = 0) -> None: + self.lines.append(" " * depth + ("- " if self.markdown else "* ") + text) + + def text(self) -> str: + return "\n".join(self.lines).rstrip() + "\n" + + +def _cite(c: Citation) -> str: + return ( + f"{c.direction} {c.magnitude:.2f} {c.published} {c.source}: {c.title} " + f"[{short(c.content_hash)}, {c.prompt_version}]" + ) + + +def _source_line(s) -> str: + if s.last_attempt is None: + when = "never fetched" + elif s.last_error: + when = f"LAST ATTEMPT FAILED {_stamp(s.last_attempt)}: {s.last_error}" + else: + when = f"fetched {_stamp(s.last_attempt)}" + return f"{s.name}: {when}; {s.items_in_window} in window" + + +def _header(doc: _Doc, brief: Brief, verbose: bool) -> None: + h = brief.header + doc.title(f"Brief as of {_stamp(h.as_of)}") + doc.line(f"window: since {_stamp(h.since)}") + if h.position_problem: + first, *rest = h.position_problem.splitlines() or [""] + doc.line(f"POSITION NOT READ: {first}") + for line in rest: + doc.line(f" {line.strip()}") + elif h.reviewed is None: + doc.line("position: never reviewed (no `reviewed` date in the file)") + else: + doc.line(f"position: reviewed {h.reviewed.isoformat()} ({h.days_since_review} days ago)") + if h.review_banner: + doc.line( + "REVIEW OVERDUE: every item below was judged against a Position last reviewed more " + "than 90 days ago, or never. The items still stand; the frame may not." + ) + if not h.sources: + doc.line("sources: none registered; nothing has been ingested") + return + if verbose: + doc.line("sources:") + for s in h.sources: + doc.bullet(_source_line(s)) + return + failed = [s for s in h.sources if s.last_error is not None] + fetched = [s for s in h.sources if s.last_attempt is not None and s.last_error is None] + never = [s for s in h.sources if s.last_attempt is None] + doc.line( + f"sources: {len(h.sources)} configured, {len(fetched)} fetched, {len(failed)} failed, " + f"{len(never)} never fetched (--verbose for every source)" + ) + for s in failed: + doc.bullet(_source_line(s)) + + +def _moved(doc: _Doc, brief: Brief) -> None: + doc.section("MOVED") + if not brief.moved: + doc.line("nothing: no watch gained evidence in the window") + for watch in brief.moved: + state = f" [{watch.state}]" if watch.state else "" + doc.bullet(f"{watch.watch_id}{state}: {watch.claim}") + for cluster in watch.clusters: + # Distinct observations, not citations: one observation judged + # under two prompt versions is two citations of one story. + others = len({c.content_hash for c in cluster}) - 1 + also = f" (+{others} near-duplicate{'s' if others != 1 else ''})" if others else "" + doc.bullet(_cite(cluster[0]) + also, depth=1) + for c in cluster[1:]: + doc.bullet(f"also {_cite(c)}", depth=2) + + +def _due(doc: _Doc, brief: Brief) -> None: + doc.section("DUE") + if not brief.position_read: + doc.line("decisions: POSITION NOT READ (see the header); watches only below") + if not brief.due_decisions and not brief.due_watches: + doc.line("nothing inside the horizon") + for d in brief.due_decisions: + when = ( + f"{d.deadline.isoformat()}, {d.days_left} days" + if d.days_left >= 0 + else f"{d.deadline.isoformat()}, {-d.days_left} days PAST" + ) + doc.bullet(f"decision {d.key}: {d.name} ({when})") + if d.stake: + doc.bullet(f"stake: {d.stake.strip()}", depth=1) + for w in brief.due_watches: + when = ( + f"expires {w.expires.isoformat()}, {w.days_left} days" + if w.days_left >= 0 + else f"EXPIRED {w.expires.isoformat()}, {-w.days_left} days ago, unresolved" + ) + doc.bullet(f"watch {w.watch_id}: {w.claim} ({when})") + + +def _watching(doc: _Doc, brief: Brief) -> None: + doc.section("WATCHING") + if not brief.watching: + doc.line("no live watches") + for r in brief.watching: + last = r.last_evidence.isoformat() if r.last_evidence else "never" + doc.bullet( + f"{r.watch_id}: belief {r.belief:.2f} ({r.belief_source}, " + f"{r.belief_date.isoformat()}); serves {r.decision_key}; expires in " + f"{r.days_to_expiry} days; evidence in window {r.evidence_in_window}, last {last}" + ) + doc.bullet(r.claim, depth=1) + + +def _quiet(doc: _Doc, brief: Brief) -> None: + doc.section("QUIET") + doc.line( + f"watches with nothing routed inside their staleness window: {len(brief.quiet_watches)}" + ) + for q in brief.quiet_watches: + last = ( + f"nothing routed since {q.last_routed.isoformat()}" if q.last_routed else "never routed" + ) + doc.bullet(f"{q.watch_id}: {last} (alert after {q.staleness_alert_days} days)") + doc.line(f"sources that ran in the window and returned nothing: {len(brief.silent_sources)}") + for s in brief.silent_sources: + note = "HAS PRODUCED BEFORE; check the source" if s.produced_before else "never produced" + doc.bullet(f"{s.name} ({note})") + pairs = sum(p.pairs for p in brief.pending) + doc.line(f"routed pairs no adjudication has answered: {pairs}") + for p in brief.pending: + doc.bullet(f"{p.watch_id}: {p.pairs}") + doc.line(f"failed adjudications in the window: {len(brief.failed)}") + for f in brief.failed: + doc.bullet(f"{short(f.content_hash)} / {f.watch_id} [{f.prompt_version}]: {f.error}") + + +def render(brief: Brief, *, markdown: bool = False, verbose: bool = False) -> str: + """ + The whole document: header first, then the four sections in fixed order. + + ``verbose`` controls only the header's source list (see the module + docstring); the other four sections never summarise, because they are + already the compact view over their own data. + """ + doc = _Doc(markdown) + _header(doc, brief, verbose) + for part in (_moved, _due, _watching, _quiet): + part(doc, brief) + return doc.text() diff --git a/src/brief/sections.py b/src/brief/sections.py new file mode 100644 index 0000000..0fd59aa --- /dev/null +++ b/src/brief/sections.py @@ -0,0 +1,142 @@ +""" +The brief's sections as plain data: what :mod:`select` produces and +:mod:`render` prints. Frozen where a row is a record; ``Brief`` itself is +mutable only so the selector can fill it section by section. + +Added 2026-09-22 for backlog task 031. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from datetime import date, datetime + +__all__ = [ + "Brief", + "Citation", + "DueDecision", + "DueWatch", + "FailedAdjudication", + "Header", + "MovedWatch", + "PendingWatch", + "QuietWatch", + "SilentSource", + "SourceState", + "WatchingRow", +] + + +@dataclass(frozen=True) +class SourceState: + name: str + last_attempt: datetime | None # rss_feeds.last_fetched: the last attempt, success or not + last_error: str | None # the error of that attempt, None when it succeeded + items_in_window: int + + +@dataclass(frozen=True) +class Header: + as_of: datetime + since: datetime + position_problem: str | None # the loader's whole message when the Position was not read + reviewed: date | None + days_since_review: int | None + review_banner: bool + sources: tuple[SourceState, ...] + + +@dataclass(frozen=True) +class Citation: + content_hash: str + title: str + source: str + published: str + direction: str + magnitude: float + prompt_version: str + + +@dataclass(frozen=True) +class MovedWatch: + watch_id: str + claim: str + # None while the watch is live; otherwise why it is not ("expired 2026-08-22, + # unresolved", "resolved yes", "retired"). Evidence that arrived in the + # window is shown whatever the watch's state, because grading needs it. + state: str | None + # One entry per near-duplicate cluster, earliest cluster first; within a + # cluster the earliest citation first. One citation per evidence row, so + # an observation judged under two prompt versions is two citations. + clusters: tuple[tuple[Citation, ...], ...] + + +@dataclass(frozen=True) +class DueDecision: + key: str + name: str + deadline: date + days_left: int # negative when the deadline has passed + stake: str | None + + +@dataclass(frozen=True) +class DueWatch: + watch_id: str + claim: str + expires: date + days_left: int # negative when already expired + + +@dataclass(frozen=True) +class WatchingRow: + watch_id: str + claim: str + belief: float + belief_source: str + belief_date: date + decision_key: str + days_to_expiry: int + evidence_in_window: int + last_evidence: date | None + + +@dataclass(frozen=True) +class QuietWatch: + watch_id: str + staleness_alert_days: int + last_routed: date | None # the day routing last linked something to it + + +@dataclass(frozen=True) +class SilentSource: + name: str + produced_before: bool # the runner's "went silent" versus "never produced" + + +@dataclass(frozen=True) +class PendingWatch: + watch_id: str + pairs: int # routed pairs with no adjudication under any prompt version + + +@dataclass(frozen=True) +class FailedAdjudication: + content_hash: str + watch_id: str + prompt_version: str + error: str + + +@dataclass +class Brief: + header: Header + position_read: bool = True + moved: list[MovedWatch] = field(default_factory=list) + due_decisions: list[DueDecision] = field(default_factory=list) + due_watches: list[DueWatch] = field(default_factory=list) + watching: list[WatchingRow] = field(default_factory=list) + quiet_watches: list[QuietWatch] = field(default_factory=list) + silent_sources: list[SilentSource] = field(default_factory=list) + pending: list[PendingWatch] = field(default_factory=list) + failed: list[FailedAdjudication] = field(default_factory=list) diff --git a/src/brief/select.py b/src/brief/select.py new file mode 100644 index 0000000..3cb267a --- /dev/null +++ b/src/brief/select.py @@ -0,0 +1,292 @@ +""" +The brief's sections as data, selected from the database and the Position. + +Pure in ``(db, as_of, since, position)``: no wall-clock read, no unordered +iteration, every list sorted by a total key, every query bounded by ``as_of``. +:mod:`src.brief.sections` documents each section's fields; the rules that +need stating live beside the code that applies them: + +* MOVED shows every watch with evidence in the window, live or not, labelled + with its state, because grading an expired watch needs that evidence. +* QUIET's staleness is tested on when routing last linked something, not on + the item's publication date; a backfilled document routed yesterday is not + silence. Pending pairs are routed pairs no prompt version has answered. +* The header's source line carries the last attempt, and the render labels a + failed attempt as one; the row keeps no separate time of the last success. + +Added 2026-09-22 for backlog task 031; reworked 2026-09-23 after its review. +""" + +from __future__ import annotations + +from datetime import date, datetime, timedelta +from typing import Any + +from sqlalchemy import exists, func +from sqlalchemy.orm import Session + +from ..config.settings import settings +from ..database.models import Adjudication, Evidence, Observation, Route, RSSFeed, Watch +from ..position.ledger import current_beliefs, live_clause, open_clause +from ..position.position import Position +from ..sources.minhash import group_near_duplicates +from .sections import ( + Brief, + Citation, + DueDecision, + DueWatch, + FailedAdjudication, + Header, + MovedWatch, + PendingWatch, + QuietWatch, + SilentSource, + SourceState, + WatchingRow, +) + +__all__ = ["HORIZON_DAYS", "REVIEW_BANNER_DAYS", "Brief", "select_brief", "watch_state"] + +# Past this many days since the Position was reviewed, every brief carries a +# banner: visible degradation, never suppression. A Position never reviewed, +# or not read at all, carries it from the first brief. +REVIEW_BANNER_DAYS = 90 + +# DUE looks this far ahead. Chosen 2026-09-22; neither the task file nor +# docs/PLAN.md gives a number ("inside the horizon", "the window ahead"), so +# this is the one setting in the brief that is an assumption. Change it here. +HORIZON_DAYS = 30 + + +def _observed(obs: Any) -> datetime: + """When an observation happened: published if known, else when it was seen.""" + return obs.published_date or obs.observed_at + + +def _by_key(rows: Any) -> dict[Any, Any]: + """A two-column result as a dict; untyped because the models use pre-2.0 ``Column()``.""" + return {row[0]: row[1] for row in rows} + + +def watch_state(w: Any, today: date) -> str | None: + """None while live; otherwise the one phrase the brief prints beside the watch.""" + if w.retired_at is not None: + return "retired" + if w.resolved_at is not None: + return f"resolved {w.outcome}" + if w.expires < today: + return f"expired {w.expires.isoformat()}, unresolved" + return None + + +def _header( + db: Session, as_of: datetime, since: datetime, position: Position | None, problem: str | None +) -> Header: + counts = _by_key( + db.query(Observation.source_id, func.count(Observation.content_hash)) + .filter(Observation.observed_at >= since, Observation.observed_at <= as_of) + .group_by(Observation.source_id) + .all() + ) + sources = tuple( + SourceState( + name=str(f.name), + last_attempt=f.last_fetched, # type: ignore[arg-type] + last_error=f.last_error, # type: ignore[arg-type] + items_in_window=int(counts.get(f.id, 0)), + ) + for f in db.query(RSSFeed).order_by(RSSFeed.name, RSSFeed.id).all() + ) + reviewed = position.reviewed if position is not None else None + days = (as_of.date() - reviewed).days if reviewed is not None else None + return Header( + as_of=as_of, + since=since, + position_problem=problem, + reviewed=reviewed, + days_since_review=days, + review_banner=days is None or days > REVIEW_BANNER_DAYS, + sources=sources, + ) + + +def _moved(db: Session, since: datetime, as_of: datetime, today: date) -> list[MovedWatch]: + rows = ( + db.query(Evidence, Observation, RSSFeed.name, Watch) + .join(Observation, Observation.content_hash == Evidence.observation_hash) + .join(RSSFeed, RSSFeed.id == Observation.source_id) + .join(Watch, Watch.id == Evidence.watch_id) + .filter(Evidence.created_at >= since, Evidence.created_at <= as_of) + .order_by(Evidence.watch_id, Observation.content_hash, Evidence.prompt_version) + .all() + ) + by_watch: dict[str, list[tuple[Any, Any, str]]] = {} + watches: dict[str, Any] = {} + for evidence, obs, source_name, watch in rows: + watch_id = str(evidence.watch_id) + watches[watch_id] = watch + by_watch.setdefault(watch_id, []).append((evidence, obs, str(source_name))) + + moved: list[MovedWatch] = [] + for watch_id in sorted(by_watch): + entries = by_watch[watch_id] + signatures = {str(obs.content_hash): tuple(obs.minhash) for _e, obs, _s in entries} + clusters: list[tuple[Citation, ...]] = [] + for group in group_near_duplicates(signatures, settings.near_duplicate_threshold): + in_group = [(e, o, s) for e, o, s in entries if str(o.content_hash) in group] + in_group.sort( + key=lambda t: (_observed(t[1]), str(t[1].content_hash), str(t[0].prompt_version)) + ) + clusters.append( + tuple( + Citation( + content_hash=str(obs.content_hash), + title=str(obs.payload.get("title") or "(untitled)"), + source=source, + published=_observed(obs).date().isoformat(), + direction=str(evidence.direction), + magnitude=float(evidence.magnitude), + prompt_version=str(evidence.prompt_version), + ) + for evidence, obs, source in in_group + ) + ) + clusters.sort(key=lambda c: (c[0].published, c[0].content_hash)) + w = watches[watch_id] + moved.append(MovedWatch(watch_id, str(w.claim), watch_state(w, today), tuple(clusters))) + return moved + + +def _due(position: Position | None, db: Session, today: date, horizon: date) -> tuple[list, list]: + decisions = ( + sorted( + ( + DueDecision(d.key, d.name, d.deadline, (d.deadline - today).days, d.stake) + for d in position.decisions + if d.deadline <= horizon + ), + key=lambda d: (d.deadline, d.key), + ) + if position is not None + else [] + ) + watches = sorted( + ( + DueWatch(str(w.id), str(w.claim), w.expires, (w.expires - today).days) # type: ignore[arg-type] + for w in db.query(Watch).filter(open_clause()).all() + if w.expires <= horizon + ), + key=lambda d: (d.expires, d.watch_id), + ) + return decisions, watches + + +def _pending(db: Session) -> list[PendingWatch]: + """Routed pairs on open watches that no prompt version has answered.""" + answered = exists().where( + Adjudication.observation_hash == Route.observation_hash, + Adjudication.watch_id == Route.watch_id, + ) + with_evidence = exists().where( + Evidence.observation_hash == Route.observation_hash, Evidence.watch_id == Route.watch_id + ) + rows = ( + db.query(Route.watch_id, func.count(Route.id)) + .join(Watch, Watch.id == Route.watch_id) + .filter(open_clause(), ~answered, ~with_evidence) + .group_by(Route.watch_id) + .order_by(Route.watch_id) + .all() + ) + return [PendingWatch(str(watch_id), int(count)) for watch_id, count in rows] + + +def select_brief( + db: Session, + *, + as_of: datetime, + since: datetime, + position: Position | None, + position_problem: str | None = None, + horizon_days: int = HORIZON_DAYS, +) -> Brief: + """Every section, as data. Pure in ``(db, as_of, since, position)``.""" + today = as_of.date() + horizon = today + timedelta(days=horizon_days) + live = {str(w.id): w for w in db.query(Watch).filter(live_clause(today)).order_by(Watch.id)} + beliefs = current_beliefs(db, as_of=as_of) + + brief = Brief( + header=_header(db, as_of, since, position, position_problem), + position_read=position is not None, + ) + brief.moved = _moved(db, since, as_of, today) + brief.due_decisions, brief.due_watches = _due(position, db, today, horizon) + + evidence_in_window = _by_key( + db.query(Evidence.watch_id, func.count(Evidence.id)) + .filter(Evidence.created_at >= since, Evidence.created_at <= as_of) + .group_by(Evidence.watch_id) + .all() + ) + last_evidence = _by_key( + db.query(Evidence.watch_id, func.max(Evidence.created_at)) + .filter(Evidence.created_at <= as_of) + .group_by(Evidence.watch_id) + .all() + ) + last_routed = _by_key( + db.query(Route.watch_id, func.max(Route.routed_at)) + .filter(Route.routed_at <= as_of) + .group_by(Route.watch_id) + .all() + ) + for watch_id, w in live.items(): + belief = beliefs[watch_id] + latest = last_evidence.get(watch_id) + brief.watching.append( + WatchingRow( + watch_id=watch_id, + claim=str(w.claim), + belief=belief.belief, + belief_source=belief.source, + belief_date=belief.observed_at.date(), + decision_key=str(w.decision_key), + days_to_expiry=(w.expires - today).days, + evidence_in_window=int(evidence_in_window.get(watch_id, 0)), + last_evidence=latest.date() if latest is not None else None, + ) + ) + routed = last_routed.get(watch_id) + if routed is None or routed < as_of - timedelta(days=int(w.staleness_alert_days)): + brief.quiet_watches.append( + QuietWatch(watch_id, int(w.staleness_alert_days), routed.date() if routed else None) + ) + + ever_produced = { + int(source_id) + for (source_id,) in db.query(Observation.source_id) + .filter(Observation.observed_at <= as_of) + .distinct() + } + ids = _by_key(db.query(RSSFeed.name, RSSFeed.id).all()) + brief.silent_sources = [ + SilentSource(s.name, ids[s.name] in ever_produced) + for s in brief.header.sources + if s.last_attempt is not None + and since <= s.last_attempt <= as_of + and s.last_error is None + and s.items_in_window == 0 + ] + brief.pending = _pending(db) + brief.failed = [ + FailedAdjudication( + str(a.observation_hash), str(a.watch_id), str(a.prompt_version), str(a.error or "") + ) + for a in db.query(Adjudication) + .filter(Adjudication.outcome == "failed") + .filter(Adjudication.created_at >= since, Adjudication.created_at <= as_of) + .order_by(Adjudication.observation_hash, Adjudication.watch_id, Adjudication.prompt_version) + .all() + ] + return brief diff --git a/src/cli/adjudicate.py b/src/cli/adjudicate.py new file mode 100644 index 0000000..391888a --- /dev/null +++ b/src/cli/adjudicate.py @@ -0,0 +1,96 @@ +""" +Adjudicate command - one structured model call per routed pair, every outcome recorded. + +``adjudicate`` asks about every routed pair on a live watch that the current +prompt version has not answered, records each answer in ``adjudications`` and +each piece of evidence in ``evidence``, and prints the totals. Run again, it +asks nothing. ``--dry-run`` prints the exact text the first pairs would send +and a character-based token estimate, and never constructs a client, so it +needs no keychain entry. + +A failed call is printed and left in the ledger; it is not retried and it does +not fail the command, because the brief's QUIET section is where a failure is +meant to be read. Exit is non-zero only when the command itself could not run. + +Added 2026-09-22 for backlog task 029. +""" + +import click +from keyring.errors import KeyringError + +from ..config.credentials import MissingCredential +from ..database.connection import get_db +from ..evidence import resolve +from ..evidence.adjudicate import dry_run, run +from ..evidence.claude_adjudicator import PROMPT_VERSION, ClaudeAdjudicator +from ..llm.claude_client import ModelCallFailed +from .colors import accent, error, header, muted, warning + + +@click.command(name="adjudicate") +@click.option( + "--dry-run", + "dry_run_flag", + is_flag=True, + default=False, + help="Print what would be sent; call nothing.", +) +@click.option("--limit", type=click.IntRange(min=1), default=None, help="At most this many pairs.") +def adjudicate_command(dry_run_flag: bool, limit: int | None) -> None: + """Ask the model whether each routed observation is evidence for its watch.""" + if dry_run_flag: + with get_db() as session: + previews = dry_run(session, PROMPT_VERSION, limit=limit if limit is not None else 3) + click.echo(header("ADJUDICATE --dry-run")) + if not previews: + click.echo(muted("No pending pairs: everything routed has been adjudicated.")) + return + for pair, system, user, estimate in previews: + click.echo(accent(f"--- {pair.view.content_hash} / {pair.watch.id}")) + click.echo(muted("[system]")) + click.echo(system) + click.echo(muted("[user]")) + click.echo(user) + click.echo(muted(f"~{estimate} input tokens (character estimate, not a count)")) + click.echo() + click.echo(muted("Nothing was sent.")) + return + + adjudicator = resolve(PROMPT_VERSION) + assert isinstance(adjudicator, ClaudeAdjudicator) + try: + with get_db() as session: + result = run(session, adjudicator, limit=limit) + except MissingCredential as exc: + raise click.ClickException(str(exc)) + except KeyringError as exc: + raise click.ClickException( + f"the OS keychain could not be read ({type(exc).__name__}: {exc}); the key is " + f"stored there by 'insightweaver auth set anthropic'" + ) + except ModelCallFailed as exc: + # Only a rejected or unavailable call reaches here; an answered failure + # is recorded per pair. + what = ( + "the API rejected the request" + if exc.outcome == "rejected" + else "the API was unavailable" + ) + raise click.ClickException( + f"{what}, so the run stopped with nothing recorded for the pair it hit and later " + f"pairs; earlier answers are kept: {exc}" + ) + + click.echo(header("ADJUDICATE")) + click.echo(f"prompt version: {result.prompt_version}") + click.echo( + f"asked {result.asked}: evidence {result.evidence}, none {result.none}, " + f"failed {result.failed}" + ) + click.echo(muted(f"tokens: {result.input_tokens} in, {result.output_tokens} out")) + if result.asked == 0: + click.echo(muted("No pending pairs: everything routed has been adjudicated.")) + for content_hash, watch_id, why in result.failures: + click.echo(f"{error('FAILED')} {content_hash} / {watch_id}: {why}") + if result.failed: + click.echo(warning(f"{result.failed} failed adjudication(s) are recorded, not retried.")) diff --git a/src/cli/app.py b/src/cli/app.py index baccb7f..62143d6 100644 --- a/src/cli/app.py +++ b/src/cli/app.py @@ -3,180 +3,36 @@ Backlog task 012 deleted the briefing product, and with it every command that generated, rendered, or reasoned over a brief: brief, frames, diet, questions, -predictions, forecast, decisions, beat, stake and scope. What is left is the -source layer, which the rewrite keeps. - -The command table is deliberately short. It is not a placeholder for the new -pipeline -- building that is a separate task -- and nothing here should grow a -command back by habit. +predictions, forecast, decisions, beat, stake and scope. What was left was the +source layer, which the rewrite kept. ``brief`` came back on 2026-09-22 (task +031) as a different thing: a derived view over the monitor's tables with no +model call in it. + +The REPL (an ASCII-art banner, a 2.5-second sleep, and a prefix dispatcher over +a raw input loop) was removed on 2026-09-22 (backlog task 027): a scripted, +idempotent command has no use for a banner, a sleep or a prefix dispatcher. +Invoking ``insightweaver`` with no subcommand now prints the group's help and +exits. + +The command table grows one task at a time as the decision monitor lands +(``docs/PLAN.md`` section 4): ``ingest`` and ``route`` on 2026-09-22 (backlog +task 028), ``adjudicate`` the same day (task 029), ``brief`` and ``run`` the +same day (task 031). Nothing here should grow a command back by habit. """ -import contextlib -import shlex -import time - import click -from .colors import accent, header, muted +from .adjudicate import adjudicate_command +from .auth import auth +from .brief import brief_command +from .ingest import ingest_command from .output import set_debug_mode from .replay import replay_command +from .route import route_command +from .run import run_command from .sources import sources_command from .watch import watch_command -# Maps command prefix to its Click command object. -# -# Order used to matter here: "predictions" had to precede "predict", since the -# shorter name is a prefix of the longer one (2026-08-27, backlog task 011). -# Both commands are gone, but the startswith() dispatch below is unchanged, so -# the ordering constraint still applies to whatever is added next. -COMMAND_DISPATCH = { - "sources": sources_command, - "watch": watch_command, - "replay": replay_command, -} - - -def print_command_refresher(): - """Print a short refresher of available commands.""" - click.echo( - f"\n{header('Commands:')} {accent('sources')} | {accent('watch')} | " - f"{accent('replay')} | help | exit\n" - ) - - -def print_help(): - """Print full help text for interactive mode.""" - click.echo(header("Available commands:")) - click.echo(f" {accent('sources')} - Inspect configured feeds and what they hold") - click.echo( - f" {accent('watch')} - Pre-registered watches and the decisions they serve" - ) - click.echo( - f" {accent('replay')} - Rebuild Evidence from Observations and diff it" - ) - click.echo(f" {accent('help')} - Show this help message") - click.echo(f" {accent('exit')} - Exit InsightWeaver") - click.echo() - click.echo(header("Sources command:")) - click.echo(f" {accent('sources list')} - All feeds with stored-article counts") - click.echo(f" {accent('sources show')} - Detailed view for one feed") - click.echo() - click.echo(header("Watch command:")) - click.echo( - f" {accent('watch list')} - Each watch, belief, decision, days to expiry" - ) - click.echo( - f" {accent('watch sync')} - Load the hand-authored Position and watch files" - ) - click.echo( - muted(" Watches are only ever created from those files -- there is no 'watch add'.") - ) - click.echo() - click.echo(header("Replay command:")) - click.echo(f" {accent('replay --prompt-version X')} - Rebuild Evidence for prompt version X") - click.echo( - muted(" Prints the diff against stored Evidence and writes nothing. --commit persists.") - ) - click.echo() - click.echo(muted("Tip: Add --debug to any command to see detailed logs")) - click.echo() - - -def _dispatch_command(command: str) -> bool: - """ - Dispatch a user command to the appropriate Click command. - - Returns True if a command was matched, False otherwise. - - Argument splitting is quote-aware (shlex) as of 2026-08-27: an option that - takes prose needs its value delivered as one argument, and a plain - whitespace split would hand Click several instead. - """ - for prefix, click_cmd in COMMAND_DISPATCH.items(): - if command.startswith(prefix): - try: - args = shlex.split(command)[1:] - except ValueError as exc: - from .colors import error as err_style - - click.echo(err_style(f"Could not read that command: {exc}")) - print_command_refresher() - return True - with contextlib.suppress(SystemExit): - try: - click_cmd.main(args, standalone_mode=False) - except click.ClickException as exc: - # standalone_mode=False re-raises instead of printing, so - # the rejection has to be shown here to reach the operator. - exc.show() - print_command_refresher() - return True - return False - - -ASCII_ART = r""" - ╔══════════════════════════════════════════════════════════╗ - ║ ║ - ║ ██╗███╗ ██╗███████╗██╗ ██████╗ ██╗ ██╗████████╗ ║ - ║ ██║████╗ ██║██╔════╝██║██╔════╝ ██║ ██║╚══██╔══╝ ║ - ║ ██║██╔██╗ ██║███████╗██║██║ ███╗███████║ ██║ ║ - ║ ██║██║╚██╗██║╚════██║██║██║ ██║██╔══██║ ██║ ║ - ║ ██║██║ ╚████║███████║██║╚██████╔╝██║ ██║ ██║ ║ - ║ ╚═╝╚═╝ ╚═══╝╚══════╝╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ ║ - ║ ║ - ║ ██╗ ██╗███████╗ █████╗ ██╗ ██╗███████╗██████╗ ║ - ║ ██║ ██║██╔════╝██╔══██╗██║ ██║██╔════╝██╔══██╗ ║ - ║ ██║ █╗ ██║█████╗ ███████║██║ ██║█████╗ ██████╔╝ ║ - ║ ██║███╗██║██╔══╝ ██╔══██║╚██╗ ██╔╝██╔══╝ ██╔══██╗ ║ - ║ ╚███╔███╔╝███████╗██║ ██║ ╚████╔╝ ███████╗██║ ██║ ║ - ║ ╚══╝╚══╝ ╚══════╝╚═╝ ╚═╝ ╚═══╝ ╚══════╝╚═╝ ╚═╝ ║ - ║ ║ - ║ ~ Transform Data Into Trustworthy Insight ~ ║ - ║ ║ - ║ ║ - ╚══════════════════════════════════════════════════════════╝ -""" - - -def interactive_mode(): - """Run InsightWeaver in interactive mode.""" - click.echo(accent(ASCII_ART)) - click.echo() - click.echo(header("Welcome to InsightWeaver") + " - Transform Data Into Trustworthy Insight.") - click.echo() - - # Pause to let user see the ASCII art and slogan - time.sleep(2.5) - - print_help() - - while True: - try: - command = click.prompt("insightweaver", type=str, prompt_suffix=" > ") - command = command.strip() - - if command in ("exit", "quit", "q"): - click.echo("Thank you for using InsightWeaver!") - break - elif command in ("help", "?"): - click.echo() - print_help() - elif command == "": - continue - elif not _dispatch_command(command): - from .colors import error as err_style - from .colors import warning as warn_style - - click.echo(err_style(f"Unknown command: {command}")) - click.echo(warn_style("Type 'help' for available commands or 'exit' to quit.")) - except (KeyboardInterrupt, EOFError): - click.echo(accent("\nThank you for using InsightWeaver!")) - break - except Exception as e: - from .colors import error as err_style - - click.echo(err_style(f"Error: {str(e)}")) - @click.group(invoke_without_command=True) @click.pass_context @@ -186,20 +42,29 @@ def cli(ctx, debug): """ InsightWeaver - monitoring against pre-registered watches. - The briefing product was removed in backlog task 012. What remains is - ingestion, the source layer, and the Position/Watch units added by task 013. + Ingest sources, route observations to pre-registered watches, ask the + model whether each routed pair is evidence, and render the brief: what + moved, what is due, what is watched, what went quiet. """ set_debug_mode(debug) ctx.ensure_object(dict) ctx.obj["DEBUG"] = debug if ctx.invoked_subcommand is None: - interactive_mode() - - -# Register commands -for name, cmd in COMMAND_DISPATCH.items(): - cli.add_command(cmd, name=name) + click.echo(ctx.get_help()) + ctx.exit(0) + + +# Register commands, in the order a morning runs them. +cli.add_command(auth, name="auth") +cli.add_command(sources_command, name="sources") +cli.add_command(ingest_command, name="ingest") +cli.add_command(watch_command, name="watch") +cli.add_command(route_command, name="route") +cli.add_command(adjudicate_command, name="adjudicate") +cli.add_command(replay_command, name="replay") +cli.add_command(brief_command, name="brief") +cli.add_command(run_command, name="run") if __name__ == "__main__": diff --git a/src/cli/auth.py b/src/cli/auth.py new file mode 100644 index 0000000..7566458 --- /dev/null +++ b/src/cli/auth.py @@ -0,0 +1,55 @@ +""" +The auth command: credentials in the OS keychain. + +Moved from the removed `estate` script on 2026-09-22 (backlog task 027): one +console script. +""" + +from __future__ import annotations + +import click + +from ..config import credentials + + +@click.group(name="auth") +def auth() -> None: + """Credentials in the OS keychain. A stored value is never printed.""" + + +@auth.command(name="set") +@click.argument("name", type=click.Choice(sorted(credentials.KNOWN))) +@click.option( + "--value", + prompt="Value", + hide_input=True, + help="The credential. Prompted for, hidden, if not given -- prefer the prompt, so the " + "value stays out of your shell history.", +) +def set_credential(name: str, value: str) -> None: + """Store a credential. Overwrites any existing value under NAME.""" + username = credentials.KNOWN[name] + try: + credentials.write(username, value) + except ValueError as exc: + raise click.ClickException(str(exc)) + click.echo(f"stored '{name}' as keychain entry '{username}'") + + +@auth.command(name="status") +def status() -> None: + """Which known credentials are set. Values are not shown.""" + for name, username in sorted(credentials.KNOWN.items()): + state = "set" if credentials.is_set(username) else "not set" + click.echo(f"{name:<12} {state:<8} ({username})") + + +@auth.command(name="clear") +@click.argument("name", type=click.Choice(sorted(credentials.KNOWN))) +def clear_credential(name: str) -> None: + """Remove a credential from the keychain.""" + try: + credentials.delete(credentials.KNOWN[name]) + except credentials.MissingCredential as exc: + raise click.ClickException(str(exc)) + click.echo(f"removed '{name}'") diff --git a/src/cli/brief.py b/src/cli/brief.py new file mode 100644 index 0000000..9d25853 --- /dev/null +++ b/src/cli/brief.py @@ -0,0 +1,134 @@ +""" +Brief command - what moved, what is due, what is watched, what went quiet. + +Run by hand. The rendered bytes are a pure function of the database, ``--since`` +and ``--as-of``: the same three give the same bytes, and the suite asserts it +by rendering twice. Each render is recorded in ``briefs`` unless ``--dry-run`` +is given, and the default window opens at the ``as_of`` of the last brief +delivered before the start of today, so a second run the same morning +reproduces the first instead of reporting "nothing since ten minutes ago". + +A Position that cannot be read is printed in the header with every problem the +loader found, DUE says its decisions are missing, the review banner is up, and +the brief still renders: the watches are in the database, and the header's job +is to say what the machinery could not do. Nothing here calls a model. + +The header's source list is compact by default: a source that answered is +folded into a count, a source whose last attempt failed is always printed in +full. ``--verbose`` prints every source individually. + +Added 2026-09-22 for backlog task 031; ``--verbose`` added 2026-09-24. +""" + +from __future__ import annotations + +import hashlib +from datetime import UTC, datetime, timedelta +from pathlib import Path + +import click +from sqlalchemy.orm import Session + +from ..brief import render, select_brief +from ..database.connection import get_db +from ..database.models import BriefRun +from ..position import PositionError, load_position +from ..utils import utcnow +from ..utils.cadence import InvalidCadence, parse_cadence +from .colors import muted + +DEFAULT_WINDOW_DAYS = 7 + + +def default_since(session: Session, as_of: datetime) -> datetime: + """The ``as_of`` of the last brief delivered before today's start, else a week back.""" + day_start = as_of.replace(hour=0, minute=0, second=0, microsecond=0) + previous = ( + session.query(BriefRun.as_of) + .filter(BriefRun.as_of < day_start) + .order_by(BriefRun.as_of.desc(), BriefRun.id.desc()) + .first() + ) + return previous[0] if previous else as_of - timedelta(days=DEFAULT_WINDOW_DAYS) + + +def _parse_as_of(raw: str) -> datetime: + """ISO 8601, to naive UTC, which is what every stored timestamp is.""" + try: + value = datetime.fromisoformat(raw) + except ValueError: + raise click.ClickException(f"--as-of {raw!r} is not an ISO 8601 date-time") + if value.tzinfo is not None: + value = value.astimezone(UTC).replace(tzinfo=None) + return value + + +@click.command(name="brief") +@click.option( + "--since", + "since_raw", + default=None, + help="Window (7d, 2w). Default: since the last brief before today, else 7d.", +) +@click.option( + "--as-of", "as_of_raw", default=None, help="Render as of this ISO 8601 moment. Default: now." +) +@click.option("--format", "fmt", type=click.Choice(["terminal", "md"]), default="terminal") +@click.option( + "--output", + type=click.Path(dir_okay=False, path_type=Path), + default=None, + help="Write the brief here instead of printing it.", +) +@click.option("--dry-run", is_flag=True, default=False, help="Render without recording the brief.") +@click.option( + "--verbose", + is_flag=True, + default=False, + help="List every source in the header, not just the ones that failed.", +) +def brief_command(since_raw, as_of_raw, fmt, output, dry_run, verbose): + """Render the brief: header, MOVED, DUE, WATCHING, QUIET.""" + as_of = _parse_as_of(as_of_raw) if as_of_raw else utcnow() + window = None + if since_raw: + try: + window = parse_cadence(since_raw) + except InvalidCadence as exc: + raise click.ClickException(str(exc)) + + position = None + problem = None + try: + position = load_position(today=as_of.date()) + except (FileNotFoundError, PositionError) as exc: + problem = str(exc) + + with get_db() as session: + since = as_of - window if window is not None else default_since(session, as_of) + brief = select_brief( + session, as_of=as_of, since=since, position=position, position_problem=problem + ) + text = render(brief, markdown=fmt == "md", verbose=verbose) + + # Deliver first, record second: a row for a brief nobody received + # would move the next default window past a week nobody read. + if output is not None: + try: + output.write_text(text, encoding="utf-8") + except OSError as exc: + raise click.ClickException(f"could not write {output}: {exc}") + click.echo(muted(f"wrote {output}")) + else: + click.echo(text, nl=False) + + if not dry_run: + session.add( + BriefRun( + as_of=as_of, + since=since, + moved=len(brief.moved), + quiet=len(brief.quiet_watches), + rendered_sha=hashlib.sha256(text.encode("utf-8")).hexdigest(), + ) + ) diff --git a/src/cli/colors.py b/src/cli/colors.py index f390e8a..065239d 100644 --- a/src/cli/colors.py +++ b/src/cli/colors.py @@ -1,49 +1,59 @@ """ Terminal color palette - hacker aesthetic -The palette itself now lives in :mod:`src.utils.colors`. It moved out of the -CLI package because ``src/render`` needs it too, and a renderer importing -``src.cli`` inverts the layering: importing ``src.render`` would pull in -``src/cli/__init__.py`` -> ``app`` -> ``brief`` -> back into ``src.render`` -mid-initialization. Renderers are below the CLI, so the palette is below both. - -This module stays as the import site every existing CLI command already uses. +One palette module. It used to be split across this file and +``src/utils/colors.py`` because ``src/render`` needed the palette too, and a +renderer importing ``src.cli`` would have inverted the layering. ``src/render`` +was deleted 2026-08-31 (backlog task 012), so the split had no reason left and +was merged back here 2026-09-22 (backlog task 027). ``success``, ``emphasis``, +``colorize_priority`` and ``colorize_confidence`` were dropped in the same +merge: no caller anywhere in ``src/`` used them. """ -from ..utils.colors import ( - ACCENT, - EMPHASIS, - ERROR, - HEADER, - MUTED, - SUCCESS, - WARNING, - accent, - colorize_confidence, - colorize_priority, - emphasis, - error, - header, - muted, - success, - warning, -) +import click + +# Color constants +ACCENT = "bright_green" +HEADER = "cyan" +WARNING = "yellow" +ERROR = "red" +MUTED = "bright_black" + + +def header(text: str) -> str: + """Style section header (cyan, bold)""" + return click.style(text, fg=HEADER, bold=True) + + +def accent(text: str) -> str: + """Style primary accent text (bright green)""" + return click.style(text, fg=ACCENT) + + +def warning(text: str) -> str: + """Style warning message (yellow)""" + return click.style(text, fg=WARNING) + + +def error(text: str) -> str: + """Style error message (red)""" + return click.style(text, fg=ERROR) + + +def muted(text: str) -> str: + """Style secondary/muted text (gray)""" + return click.style(text, fg=MUTED) + __all__ = [ "ACCENT", - "EMPHASIS", "ERROR", "HEADER", "MUTED", - "SUCCESS", "WARNING", "accent", - "colorize_confidence", - "colorize_priority", - "emphasis", "error", "header", "muted", - "success", "warning", ] diff --git a/src/cli/ingest.py b/src/cli/ingest.py new file mode 100644 index 0000000..75a00ac --- /dev/null +++ b/src/cli/ingest.py @@ -0,0 +1,116 @@ +""" +Ingest command - every configured source through the adapter path. + +One command, all feeds in ``config/feeds/``, one store path. The profile-driven +selection that used to pick a subset went with the profile (backlog task 027); +curation is editing that directory, as ``SOURCES.md`` says. A source row is +registered the first time its adapter runs, so adding a feed to config is +enough -- the "added to config, never reached the database" trap recorded in +tasks 020 and 025 has no path left. + +Three outcomes per source stay distinct, as the runner keeps them: fetched +(with how many were new), unreachable (an error, printed loudly), and went +silent (zero items from a source that has produced items before). None of them +stops the run; the brief carries the state. The exit code is non-zero when the +command cannot run at all (a bad option, no sources, nothing matched) and when +no source could be read, which is a broken machine rather than a quiet morning. + +Added 2026-09-22 for backlog task 028. +""" + +import asyncio +from datetime import timedelta + +import click + +from ..database.connection import get_db +from ..sources.runner import DEFAULT_LOOKBACK_DAYS, build_configured_adapters, run_adapters +from ..utils import utcnow +from ..utils.cadence import InvalidCadence, parse_cadence +from .colors import accent, error, header, muted, warning + +# Five in flight at once. With 78 RSS feeds configured on 2026-09-22 that is +# sixteen batches in the worst case where every feed runs to its timeout; a +# feed that answers normally takes about a second. Few enough to remain a +# polite guest of each host. +CONCURRENCY = 5 + + +def _since(raw: str | None) -> timedelta: + if raw is None: + return timedelta(days=DEFAULT_LOOKBACK_DAYS) + try: + return parse_cadence(raw) + except InvalidCadence as exc: + raise click.ClickException(str(exc)) + + +@click.command(name="ingest") +@click.option( + "--since", + "since_raw", + default=None, + help=f"How far back to ask each source (7d, 2w). Default {DEFAULT_LOOKBACK_DAYS}d.", +) +@click.option( + "--source", + "source_filter", + default=None, + help="Only sources whose name contains this text (case-insensitive).", +) +def ingest_command(since_raw, source_filter): + """Fetch every configured source and store what is new.""" + window_start = utcnow() - _since(since_raw) + + try: + adapters = build_configured_adapters(include_rss=True) + except ValueError as exc: + raise click.ClickException(str(exc)) + if source_filter: + needle = source_filter.lower() + adapters = [a for a in adapters if needle in a.name.lower()] + if not adapters: + raise click.ClickException( + "no sources to ingest: nothing matched" + if source_filter + else "no sources configured under config/feeds/" + ) + + click.echo(header("INGEST")) + click.echo( + muted(f"{len(adapters)} source(s) since {window_start.isoformat(timespec='minutes')}") + ) + click.echo() + + summary = asyncio.run( + run_adapters(adapters, window_start, db_factory=get_db, concurrency=CONCURRENCY) + ) + + for result in summary.results: + if result.error: + click.echo(f"{error('UNREACHABLE')} {result.source}: {result.error}") + elif result.went_silent: + click.echo( + f"{warning('WENT SILENT')} {result.source}: zero items, but it has " + f"produced items before" + ) + else: + click.echo( + f"{accent(result.source)}: fetched {result.fetched}, " + f"inserted {result.inserted}, {result.duplicates} already stored" + ) + + click.echo() + click.echo( + muted( + f"{summary.successful_sources} of {summary.total_sources} source(s) read; " + f"{summary.total_articles} new article(s)" + ) + ) + if summary.alerts: + click.echo() + for line in summary.alerts: + click.echo(warning(f"SOURCE ALERT: {line}")) + + if summary.successful_sources == 0: + raise click.ClickException("no source could be read") diff --git a/src/cli/replay.py b/src/cli/replay.py index 05f640f..543a100 100644 --- a/src/cli/replay.py +++ b/src/cli/replay.py @@ -26,9 +26,11 @@ """ import click +from keyring.errors import KeyringError +from ..config.credentials import MissingCredential from ..database.connection import get_db -from ..database.models import Observation, Watch +from ..database.models import Observation, Route, Watch from ..evidence import ( NondeterministicReplay, UnknownPromptVersion, @@ -40,6 +42,9 @@ resolve, stored_evidence, ) +from ..evidence.claude_adjudicator import AdjudicationFailed +from ..llm.claude_client import ModelCallFailed +from ..position.ledger import open_clause from .colors import accent, header, muted, warning @@ -86,7 +91,12 @@ def _adjudicator_for(prompt_version: str, path: str | None): default=None, help="Load 'module:attr' instead of the registered adjudicator for this version.", ) -@click.option("--limit", type=int, default=None, help="Replay only the first N observations.") +@click.option( + "--limit", + type=click.IntRange(min=1), + default=None, + help="Replay only the first N routed observations (hash order).", +) @click.option( "--commit", "do_commit", @@ -97,11 +107,17 @@ def _adjudicator_for(prompt_version: str, path: str | None): def replay_command(prompt_version, against, adjudicator_path, limit, do_commit): """Rebuild Evidence from Observations and print the diff. Writes only with --commit.""" baseline_version = against or prompt_version + if do_commit and limit is not None: + raise click.ClickException( + "--commit with --limit is refused: commit makes the stored rows equal the replay, " + "and a bounded replay produced rows for only part of the corpus, so every stored " + "row outside the bound would be deleted. Replay the whole corpus to commit." + ) adjudicator = _adjudicator_for(prompt_version, adjudicator_path) with get_db() as session: observations = session.query(Observation).count() - watches = session.query(Watch).count() + watches = session.query(Watch).filter(open_clause()).count() if observations == 0: click.echo( @@ -113,12 +129,25 @@ def replay_command(prompt_version, against, adjudicator_path, limit, do_commit): ) return - replayed = rebuild(session, adjudicator, limit=limit) + pairs = session.query(Route).count() + if pairs == 0 and watches: + raise click.ClickException( + "nothing is routed: a replay over an unrouted corpus judges no pair, and with " + "--commit it would delete this version's stored evidence. Run " + "'insightweaver route' first." + ) + + try: + replayed = rebuild(session, adjudicator, limit=limit) + except (MissingCredential, AdjudicationFailed, KeyringError, ModelCallFailed) as exc: + raise click.ClickException(str(exc)) baseline = stored_evidence(session, baseline_version) result = diff(replayed, baseline) click.echo(header("REPLAY")) - click.echo(format_diff(result, prompt_version, baseline_version, observations, watches)) + click.echo( + format_diff(result, prompt_version, baseline_version, observations, watches, pairs) + ) click.echo() if not do_commit: diff --git a/src/cli/route.py b/src/cli/route.py new file mode 100644 index 0000000..a9f6872 --- /dev/null +++ b/src/cli/route.py @@ -0,0 +1,102 @@ +""" +Route command - link the window's observations to the live watches. + +``route`` writes; ``route --dry-run`` computes the same report and writes +nothing. ``--rebuild`` discards every link for the live watches and routes the +whole corpus again, which is how a changed trigger reaches observations that +were stored before the change. + +The unrouted clusters printed at the end are the point of running this by +hand: an observation that routes to nothing is usually noise, and a story that +several outlets carried and nothing caught is a watch that does not exist yet. + +Added 2026-09-22 for backlog task 028. +""" + +import click + +from ..database.connection import get_db +from ..routing import RoutingReport, TriggerCompileError, route +from ..routing.route import CLUSTER_LIMIT +from ..utils import utcnow +from ..utils.cadence import InvalidCadence, parse_cadence +from .colors import accent, header, muted, warning + +DEFAULT_WINDOW = "7d" + + +def render_report(report: RoutingReport) -> str: + """The routing report as text. Kept as a function so tests can read it.""" + window = ( + "whole corpus (rebuild)" + if report.rebuild + else f"since {report.since.isoformat(timespec='minutes')}" + ) + lines = [ + f"window: {window}", + f"observations: {report.observations}, routed {report.routed}, unrouted {report.unrouted}", + "", + ] + if not report.watches: + lines.append("no live watches") + for w in report.watches: + lines.append(f" {w.watch_id}: {w.new} new, {w.total} in window") + if report.unrouted_by_source: + lines.append("") + lines.append("unrouted by source:") + for source, count in report.unrouted_by_source: + lines.append(f" {count:>5} {source}") + if report.clustering_skipped: + lines.append("") + lines.append( + f"clustering skipped: {report.clustering_skipped} unrouted observations exceed " + f"the {CLUSTER_LIMIT} the pairwise grouper is sized for; narrow --since" + ) + if report.clusters: + lines.append("") + lines.append("unrouted, largest clusters first:") + for c in report.clusters: + sources = ", ".join(c.sources) + lines.append(f" [{c.size}] {c.title[:80] or '(untitled)'} ({sources})") + if report.clusters_omitted: + lines.append(f" ... and {report.clusters_omitted} smaller cluster(s)") + return "\n".join(lines) + + +@click.command(name="route") +@click.option("--since", "since_raw", default=DEFAULT_WINDOW, help="Window (7d, 2w).") +@click.option("--dry-run", is_flag=True, default=False, help="Report only; write nothing.") +@click.option( + "--rebuild", + is_flag=True, + default=False, + help="Discard every link for the live watches and route the whole corpus again.", +) +def route_command(since_raw, dry_run, rebuild): + """Link observations to the watches whose triggers they match.""" + try: + window = parse_cadence(since_raw) + except InvalidCadence as exc: + raise click.ClickException(str(exc)) + # One clock for the window and for liveness: naive UTC, as observed_at is. + now = utcnow() + since = now - window + + with get_db() as session: + try: + report = route( + session, since=since, today=now.date(), write=not dry_run, rebuild=rebuild + ) + except TriggerCompileError as exc: + raise click.ClickException(str(exc)) + + click.echo(header("ROUTE")) + click.echo(render_report(report)) + click.echo() + if dry_run: + click.echo(muted("Nothing was written.")) + else: + written = sum(w.new for w in report.watches) + click.echo(accent(f"{written} link(s) written.")) + if report.watches and report.routed == 0: + click.echo(warning("Nothing routed. Either the window is quiet or no trigger matches.")) diff --git a/src/cli/run.py b/src/cli/run.py new file mode 100644 index 0000000..59a6e20 --- /dev/null +++ b/src/cli/run.py @@ -0,0 +1,41 @@ +""" +Run command - the morning, in order: ingest, route, adjudicate, brief. + +Each step is the same command the operator could run by hand, invoked in +process with its defaults, and the run stops at the first that fails with a +non-zero exit. A step that succeeds while reporting a problem -- an +unreachable source, a failed adjudication -- does not stop the run, because +the brief is where those are read. Nothing here is a scheduler; it is one +command that saves typing four. + +Added 2026-09-22 for backlog task 031. +""" + +from __future__ import annotations + +import click + +from .adjudicate import adjudicate_command +from .brief import brief_command +from .ingest import ingest_command +from .route import route_command + +STEPS = ( + ("ingest", ingest_command), + ("route", route_command), + ("adjudicate", adjudicate_command), + ("brief", brief_command), +) + + +@click.command(name="run") +@click.pass_context +def run_command(ctx: click.Context) -> None: + """Ingest, route, adjudicate and render the brief, stopping at the first failure.""" + for name, command in STEPS: + click.echo(f"==> {name}") + try: + ctx.invoke(command) + except click.ClickException as exc: + raise click.ClickException(f"{name}: {exc.format_message()}") + click.echo() diff --git a/src/cli/watch.py b/src/cli/watch.py index ca68e8e..0931364 100644 --- a/src/cli/watch.py +++ b/src/cli/watch.py @@ -1,14 +1,19 @@ """ Watch command - what is being monitored, and for which decision. -Two subcommands and deliberately no third: +Four subcommands, none of which can author a watch: ``watch sync`` reads the hand-authored Position and watch files and makes the table match them. It takes no arguments describing a watch, because it is not a way to write one -- it is the file's only route into the database. -``watch list`` shows what is stored: each watch, its belief, the decision it -serves, and how long until it expires. +``watch list`` shows what is stored: each watch, its current belief with who +set it and when, the decision it serves, and how long until it expires. + +``watch believe`` and ``watch resolve`` (backlog task 030, 2026-09-22) are the +operator's two writes: a belief row in the append-only ledger, and a one-time +grading. Neither creates a watch, changes its claim or its triggers, or can be +driven by anything but the operator at a terminal. **There is no ``watch add``.** It would satisfy no acceptance criterion in backlog task 013 and it is the seam through which auto-generated watches @@ -27,7 +32,18 @@ from ..database.connection import get_db from ..database.models import Watch as WatchRow -from ..position import PositionError, WatchError, load_position, load_watches, sync_watches +from ..position import ( + OUTCOMES, + LedgerError, + PositionError, + WatchError, + current_beliefs, + load_position, + load_watches, + record_belief, + resolve_watch, + sync_watches, +) from .colors import accent, error, header, muted, warning @@ -86,10 +102,12 @@ def sync_watch_set(): with get_db() as session: summary = sync_watches(session, watches) - for label in ("added", "updated", "removed"): + for label in ("added", "updated", "belief_changed", "retired", "restored", "resolved"): ids = summary[label] if ids: - click.echo(f" {label}: {', '.join(sorted(ids))}") + click.echo(f" {label.replace('_', ' ')}: {', '.join(sorted(ids))}") + if summary["resolved"]: + click.echo(muted(" a resolved watch is updated from the file but never un-resolved by it")) if not any(summary.values()): click.echo(muted(" no change")) click.echo() @@ -114,6 +132,7 @@ def list_watches(): with get_db() as session: rows = session.query(WatchRow).order_by(WatchRow.expires).all() + beliefs = current_beliefs(session) if not rows: click.echo(muted("No watches stored. Run 'watch sync' to load the checked-in files.")) @@ -131,9 +150,25 @@ def list_watches(): click.echo("=" * 80) for row in rows: - click.echo(accent(row.id)) + state = "" + if row.resolved_at is not None: + state = f" [resolved {row.outcome}, {row.resolved_at.date().isoformat()}]" + elif row.retired_at is not None: + state = f" [retired {row.retired_at.date().isoformat()}]" + click.echo(accent(row.id) + muted(state)) click.echo(f" claim: {row.claim}") - click.echo(f" belief: {row.belief:.2f}") + current = beliefs[str(row.id)] + registered = ( + f"; registered {current.registered:.2f}" + if abs(current.registered - current.belief) > 1e-9 + else "" + ) + click.echo( + f" belief: {current.belief:.2f}" + + muted( + f" ({current.source}, {current.observed_at.date().isoformat()}{registered})" + ) + ) decision = names.get(row.decision_key) suffix = f" -- {decision}" if decision else "" click.echo(f" decision: {row.decision_key}{suffix}") @@ -144,3 +179,33 @@ def list_watches(): + muted(f" | {len(row.triggers or [])} trigger clause(s)") ) click.echo() + + +@watch_command.command(name="believe") +@click.argument("watch_id") +@click.argument("belief", type=click.FloatRange(0.0, 1.0)) +@click.option("--note", required=True, help="Why. Written to the ledger beside the value.") +def believe(watch_id: str, belief: float, note: str) -> None: + """Record your current belief in a watch's claim. Append-only; never edits.""" + with get_db() as session: + try: + row = record_belief(session, watch_id, belief, source="principal", note=note) + except LedgerError as exc: + raise click.ClickException(str(exc)) + click.echo(f"{accent(watch_id)}: belief {row.belief:.2f} recorded ({row.note})") + + +@watch_command.command(name="resolve") +@click.argument("watch_id") +@click.option("--outcome", type=click.Choice(OUTCOMES), required=True) +@click.option("--note", required=True, help="What settled it. Written once.") +def resolve(watch_id: str, outcome: str, note: str) -> None: + """Grade a watch: did the claim resolve yes or no. Once, by you, never by the tool.""" + with get_db() as session: + try: + row = resolve_watch(session, watch_id, outcome=outcome, note=note) + except LedgerError as exc: + raise click.ClickException(str(exc)) + click.echo( + f"{accent(watch_id)}: resolved {row.outcome} on {row.resolved_at.date().isoformat()}" + ) diff --git a/src/config/credentials.py b/src/config/credentials.py new file mode 100644 index 0000000..1b1e171 --- /dev/null +++ b/src/config/credentials.py @@ -0,0 +1,90 @@ +""" +Credentials live in the OS keychain, and nowhere else. + +Read through ``keyring``, under one service name (``settings.keyring_service``) +and one username per credential. Nothing here reads an environment variable or +a file, and nothing here falls back to one: a credential that is not in the +keychain raises :class:`MissingCredential` at the point it is needed, with the +command that sets it in the message. ``ANTHROPIC_API_KEY`` in ``.env`` was the +previous home and was removed on 2026-09-22 (backlog task 026) rather than kept +as a fallback, because a fallback is a second place a secret can live and the +whole point of a keychain is that there is one. + +Every credential this system will ever hold is read-only by construction: an +API key that can only submit prompts, an OAuth refresh token minted against +read-only scopes, a finance aggregator access URL for a protocol with no write +operations. Adding a credential here that could move money, send mail or write +to an external service is a change to that property and needs its own task. + +Lookups are lazy. Importing this module touches no keychain; only +:func:`read` does, and the first thing that calls it is the constructor of a +model client. The test suite therefore never needs a keychain, and CI -- which +has none -- runs the same tests as a laptop by installing an in-memory backend. + +Moved here from ``src/estate/credentials.py`` on 2026-09-22 (backlog task 027), +when the ``estate`` console script folded into ``insightweaver`` as one command. +""" + +from __future__ import annotations + +import keyring +from keyring.errors import PasswordDeleteError + +from src.config.settings import settings + +__all__ = [ + "ANTHROPIC", + "KNOWN", + "MissingCredential", + "delete", + "is_set", + "read", + "write", +] + +# The username under which each credential is stored. The short name on the +# left is what the operator types (``insightweaver auth set anthropic``); the +# value on the right is the keychain entry, and it never changes once something +# is stored under it. +ANTHROPIC = "anthropic_api_key" +KNOWN: dict[str, str] = {"anthropic": ANTHROPIC} + + +class MissingCredential(RuntimeError): + """A credential this operation needs is not in the keychain.""" + + def __init__(self, username: str) -> None: + self.username = username + short = next((k for k, v in KNOWN.items() if v == username), username) + super().__init__( + f"no credential '{username}' in the keychain under service " + f"'{settings.keyring_service}'. Set it once with: insightweaver auth set {short}" + ) + + +def read(username: str) -> str: + """The stored value, or :class:`MissingCredential`. Never an empty string.""" + value = keyring.get_password(settings.keyring_service, username) + if not value: + raise MissingCredential(username) + return value + + +def write(username: str, value: str) -> None: + """Store ``value``. A blank value is refused, not stored as an empty secret.""" + if not value or not value.strip(): + raise ValueError(f"refusing to store a blank value for '{username}'") + keyring.set_password(settings.keyring_service, username, value.strip()) + + +def delete(username: str) -> None: + """Remove the entry. Removing one that is absent is an error, not a no-op.""" + try: + keyring.delete_password(settings.keyring_service, username) + except PasswordDeleteError: + raise MissingCredential(username) + + +def is_set(username: str) -> bool: + """Whether a non-empty value is stored. Never returns the value.""" + return bool(keyring.get_password(settings.keyring_service, username)) diff --git a/src/config/feed_matcher.py b/src/config/feed_matcher.py index 8aac553..989afbb 100644 --- a/src/config/feed_matcher.py +++ b/src/config/feed_matcher.py @@ -1,13 +1,17 @@ """ -Feed Matcher - Tag-based Feed Selection System -Matches RSS feeds to user profiles based on applicability tags +Feed loading: reads ``config/feeds/`` and nothing else. + +Profile matching (``match_feeds_to_profile``, ``_calculate_match_score``, +``_get_default_preferences``, ``get_feed_statistics``, ``get_available_tags``) +left with ``src/feed_manager.py`` on 2026-09-22 (backlog task 027): there is no +profile for it to match against. What remains is the loader every adapter run +still needs. """ import json import logging from dataclasses import dataclass from pathlib import Path -from typing import Any logger = logging.getLogger(__name__) @@ -31,7 +35,7 @@ class Feed: class FeedMatcher: - """Matches feeds to user profiles based on tag-based applicability""" + """Loads every feed declared under ``config/feeds/`` and nothing else.""" def __init__(self, feeds_directory: str = "config/feeds"): """ @@ -78,159 +82,3 @@ def _load_all_feeds(self) -> None: logger.error(f"Error loading feeds from {json_file}: {e}") logger.info(f"Loaded {len(self.all_feeds)} total feeds from {self.feeds_dir}") - - def match_feeds_to_profile(self, user_profile) -> list[dict[str, Any]]: - """ - Match feeds to user profile based on tags - - Args: - user_profile: UserProfile instance with feed preferences - - Returns: - List of feed dictionaries sorted by relevance - """ - try: - prefs = user_profile.profile.get("feed_preferences", {}) - except AttributeError: - logger.warning("User profile has no feed_preferences, using defaults") - prefs = self._get_default_preferences() - - matched_feeds = [] - - for feed in self.all_feeds: - score = self._calculate_match_score(feed, prefs) - - if score > 0: - matched_feeds.append( - { - "name": feed.name, - "url": feed.url, - "category": feed.domain_tags[0] if feed.domain_tags else "uncategorized", - "match_score": score, - "source_file": feed.source_file, - } - ) - - # Sort by match score (highest first) - matched_feeds.sort(key=lambda x: x["match_score"], reverse=True) - - logger.info(f"Matched {len(matched_feeds)} feeds to user profile") - return matched_feeds - - def _calculate_match_score(self, feed: Feed, preferences: dict[str, Any]) -> float: - """ - Calculate match score for a feed based on user preferences - - Scoring: - - Scope match (required_scopes): +10 points - - Geographic match: +5 points - - Professional domain match: +3 points - - Specialty interest match: +2 points - - Base relevance_score: +0-10 points - - Excluded topics: 0 points (hard exclude) - - Args: - feed: Feed to score - preferences: User feed preferences - - Returns: - Match score (0 = no match, higher = better match) - """ - score = 0.0 - - # Get preference lists - required_scopes = preferences.get("required_scopes", ["always", "national"]) - geo_interests = preferences.get("geographic_interests", []) - prof_domains = preferences.get("professional_domains", []) - specialty_interests = preferences.get("specialty_interests", []) - excluded_topics = preferences.get("excluded_topics", []) - - # 1. Check for exclusions (hard stop) - for excluded in excluded_topics: - if ( - excluded in feed.domain_tags - or excluded in feed.specialty_tags - or excluded in feed.geo_tags - ): - return 0.0 - - # 2. Scope matching (most important) - if any(scope in feed.scope for scope in required_scopes): - score += 10.0 - - # 3. Geographic matching - if any(geo in feed.geo_tags for geo in geo_interests): - score += 5.0 - - # 4. Professional domain matching - if any(domain in feed.domain_tags for domain in prof_domains): - score += 3.0 - - # 5. Specialty interest matching - if any(spec in feed.specialty_tags for spec in specialty_interests): - score += 2.0 - - # 6. Add base relevance score (0-10 scale) - score += feed.relevance_score * 10 - - return score - - def _get_default_preferences(self) -> dict[str, Any]: - """Get default feed preferences for users without configuration""" - return { - "required_scopes": ["always", "national"], - "geographic_interests": ["usa"], - "professional_domains": [], - "specialty_interests": [], - "excluded_topics": [], - } - - def get_feed_statistics(self) -> dict[str, Any]: - """Get statistics about loaded feeds""" - stats = { - "total_feeds": len(self.all_feeds), - "by_scope": {}, - "by_geo": {}, - "by_domain": {}, - "by_source_file": {}, - } - - for feed in self.all_feeds: - # Count by scope - for scope in feed.scope: - stats["by_scope"][scope] = stats["by_scope"].get(scope, 0) + 1 - - # Count by geography - for geo in feed.geo_tags: - stats["by_geo"][geo] = stats["by_geo"].get(geo, 0) + 1 - - # Count by domain - for domain in feed.domain_tags: - stats["by_domain"][domain] = stats["by_domain"].get(domain, 0) + 1 - - # Count by source file - stats["by_source_file"][feed.source_file] = ( - stats["by_source_file"].get(feed.source_file, 0) + 1 - ) - - return stats - - def get_available_tags(self) -> dict[str, list[str]]: - """Get all available tags for user reference""" - scopes = set() - geo_tags = set() - domain_tags = set() - specialty_tags = set() - - for feed in self.all_feeds: - scopes.update(feed.scope) - geo_tags.update(feed.geo_tags) - domain_tags.update(feed.domain_tags) - specialty_tags.update(feed.specialty_tags) - - return { - "scopes": sorted(scopes), - "geographic_tags": sorted(geo_tags), - "domain_tags": sorted(domain_tags), - "specialty_tags": sorted(specialty_tags), - } diff --git a/src/config/feeds.py b/src/config/feeds.py deleted file mode 100644 index 126999b..0000000 --- a/src/config/feeds.py +++ /dev/null @@ -1,813 +0,0 @@ -""" -RSS Feed Configuration for InsightWeaver -Curated list of 112 reliable, accurate RSS feeds organized by category -Focus: Northern Virginia residents with government, technology, and local news emphasis -Last Updated: September 2025 -""" - -RSS_FEEDS = { - # Government & Political (Verified Working) - "government": [ - { - "name": "Supreme Court Blog", - "url": "https://www.scotusblog.com/feed/", - "category": "judicial", - "description": "Supreme Court decisions and analysis", - }, - { - "name": "Congress.gov - House Floor Updates", - "url": "https://www.congress.gov/rss/house-floor-today.xml", - "category": "legislative", - "description": "House of Representatives floor activity", - }, - { - "name": "Congress.gov - Senate Floor Updates", - "url": "https://www.congress.gov/rss/senate-floor-today.xml", - "category": "legislative", - "description": "Senate floor activity", - }, - { - "name": "Federal Register - Public Inspection", - "url": "https://www.federalregister.gov/documents/feeds/public-inspection.xml", - "category": "federal_government", - "description": "Documents on public inspection at the Office of the Federal Register", - }, - { - "name": "Federal Reserve Press Releases", - "url": "https://www.federalreserve.gov/feeds/press_all.xml", - "category": "monetary_policy", - "description": "Federal Reserve announcements and monetary policy", - }, - { - "name": "SEC Press Releases", - "url": "https://www.sec.gov/news/pressreleases.rss", - "category": "financial_regulation", - "description": "SEC enforcement and regulatory actions", - }, - { - "name": "USAGov Blog", - "url": "https://blog.usa.gov/feed", - "category": "federal_government", - "description": "Official guide to government information and services", - }, - ], - # Virginia State & Local (Verified Working) - "virginia": [ - { - "name": "Virginia Mercury", - "url": "https://www.virginiamercury.com/feed/", - "category": "state_news", - "description": "Virginia government and policy news", - }, - { - "name": "Supreme Court of Virginia Opinions", - "url": "https://www.vacourts.gov/static/rss/rss_scv_opinions.xml", - "category": "state_judicial", - "description": "Virginia Supreme Court opinions", - }, - { - "name": "Virginia Court of Appeals Published Opinions", - "url": "https://www.vacourts.gov/static/rss/rss_cav_p_opinions.xml", - "category": "state_judicial", - "description": "Virginia Court of Appeals published opinions", - }, - { - "name": "WAVY Virginia Politics", - "url": "https://www.wavy.com/news/politics/virginia-politics/feed/", - "category": "state_politics", - "description": "Hampton Roads political coverage", - }, - { - "name": "Blue Virginia", - "url": "https://bluevirginia.us/feed", - "category": "state_politics", - "description": "Progressive Virginia politics blog", - }, - { - "name": "Bacon's Rebellion", - "url": "https://baconsrebellion.com/feed/", - "category": "state_politics", - "description": "Non-aligned Virginia politics and policy analysis", - }, - { - "name": "Cardinal News", - "url": "https://cardinalnews.org/feed/", - "category": "regional_news", - "description": "Southwest Virginia news coverage", - }, - { - "name": "ARLnow", - "url": "https://www.arlnow.com/feed/", - "category": "local_news", - "description": "Arlington County news and events", - }, - { - "name": "National Weather Service - Virginia", - "url": "https://alerts.weather.gov/cap/va.php?x=0", - "category": "weather_alerts", - "description": "Virginia weather alerts and warnings", - }, - { - "name": "Arlington County RSS", - "url": "https://www.arlingtonva.us/Government/News/RSS", - "category": "local_government", - "description": "Arlington County government news", - }, - { - "name": "Alexandria City RSS", - "url": "https://www.alexandriava.gov/news/rss.xml", - "category": "local_government", - "description": "Alexandria city government news", - }, - { - "name": "Loudoun County RSS", - "url": "https://www.loudoun.gov/rss.xml", - "category": "local_government", - "description": "Loudoun County government news", - }, - { - "name": "Prince William County RSS", - "url": "https://www.pwcva.gov/news/rss.xml", - "category": "local_government", - "description": "Prince William County government news", - }, - { - "name": "DC Council RSS", - "url": "https://dccouncil.us/feed/", - "category": "dc_metro", - "description": "DC Council legislative activity", - }, - ], - # Transportation (DC Metro Area) - "transportation": [ - { - "name": "WMATA Service Alerts", - "url": "https://www.wmata.com/rider-tools/service-alerts/rss.cfm", - "category": "transit", - "description": "Washington Metro service alerts and updates", - }, - { - "name": "Virginia Railway Express", - "url": "https://www.vre.org/news/rss.xml", - "category": "transit", - "description": "VRE commuter rail news and updates", - }, - { - "name": "VDOT Northern Virginia", - "url": "https://www.virginiadot.org/news/northern_virginia_rss.xml", - "category": "transportation_infrastructure", - "description": "Northern Virginia transportation projects", - }, - ], - # National & International News (Verified Working) - "news": [ - { - "name": "NPR News", - "url": "https://feeds.npr.org/1001/rss.xml", - "category": "general_news", - "description": "NPR national and international news", - }, - { - "name": "NPR Politics", - "url": "https://feeds.npr.org/1014/rss.xml", - "category": "politics", - "description": "NPR political coverage", - }, - { - "name": "BBC World News", - "url": "https://feeds.bbci.co.uk/news/world/rss.xml", - "category": "world_news", - "description": "BBC international news coverage", - }, - { - "name": "BBC US & Canada", - "url": "https://feeds.bbci.co.uk/news/world/us_and_canada/rss.xml", - "category": "us_news", - "description": "BBC coverage of US and Canadian news", - }, - { - "name": "The Guardian US", - "url": "https://www.theguardian.com/us-news/rss", - "category": "us_news", - "description": "Guardian US news coverage", - }, - { - "name": "The Guardian World", - "url": "https://www.theguardian.com/world/rss", - "category": "world_news", - "description": "Guardian international news", - }, - { - "name": "The Hill", - "url": "https://thehill.com/feed/", - "category": "politics", - "description": "Congressional and political news", - }, - { - "name": "Al Jazeera", - "url": "https://www.aljazeera.com/xml/rss/all.xml", - "category": "world_news", - "description": "International news with Middle East focus", - }, - { - "name": "Deutsche Welle", - "url": "https://rss.dw.com/rdf/rss-en-all", - "category": "world_news", - "description": "German international broadcaster", - }, - { - "name": "CNN Top Stories", - "url": "http://rss.cnn.com/rss/edition.rss", - "category": "general_news", - "description": "CNN breaking news and top stories", - }, - { - "name": "ABC News Top Stories", - "url": "https://feeds.abcnews.com/abcnews/topstories", - "category": "general_news", - "description": "ABC News headlines", - }, - { - "name": "CBS News Top Stories", - "url": "https://www.cbsnews.com/latest/rss/main", - "category": "general_news", - "description": "CBS News latest stories", - }, - { - "name": "NBC News Top Stories", - "url": "https://feeds.nbcnews.com/feeds/topstories", - "category": "general_news", - "description": "NBC News top headlines", - }, - { - "name": "Fox News Latest", - "url": "https://moxie.foxnews.com/google-publisher/latest.xml", - "category": "general_news", - "description": "Fox News latest headlines", - }, - { - "name": "USA Today", - "url": "http://rssfeeds.usatoday.com/usatoday-NewsTopStories", - "category": "general_news", - "description": "USA Today top news", - }, - { - "name": "Washington Post Politics", - "url": "https://feeds.washingtonpost.com/rss/politics", - "category": "politics", - "description": "Washington Post political coverage", - }, - { - "name": "New York Times Homepage", - "url": "https://rss.nytimes.com/services/xml/rss/nyt/HomePage.xml", - "category": "general_news", - "description": "New York Times front page stories", - }, - ], - # Cybersecurity & Technology (Working Alternatives) - "cybersecurity": [ - { - "name": "Krebs on Security", - "url": "https://krebsonsecurity.com/feed/", - "category": "security_news", - "description": "Cybersecurity news and investigation", - }, - { - "name": "Schneier on Security", - "url": "https://www.schneier.com/feed/", - "category": "security_analysis", - "description": "Security analysis and commentary", - }, - { - "name": "The Hacker News", - "url": "https://feeds.feedburner.com/TheHackersNews", - "category": "security_news", - "description": "Latest cybersecurity news and alerts", - }, - { - "name": "Dark Reading", - "url": "https://www.darkreading.com/rss.xml", - "category": "security_news", - "description": "Enterprise security news", - }, - { - "name": "Bleeping Computer", - "url": "https://www.bleepingcomputer.com/feed/", - "category": "security_news", - "description": "Security and technology news", - }, - { - "name": "SANS Internet Storm Center", - "url": "https://isc.sans.edu/rssfeed.xml", - "category": "security_alerts", - "description": "Daily security diary and alerts", - }, - { - "name": "CSO Online", - "url": "https://www.csoonline.com/feed/", - "category": "security_news", - "description": "Security and risk management", - }, - { - "name": "Graham Cluley", - "url": "https://grahamcluley.com/feed/", - "category": "security_analysis", - "description": "Security news and opinion", - }, - { - "name": "Threatpost", - "url": "https://threatpost.com/feed/", - "category": "security_news", - "description": "Information security news", - }, - { - "name": "SecurityWeek", - "url": "https://www.securityweek.com/feed", - "category": "security_news", - "description": "Cybersecurity news and analysis", - }, - ], - # Technology & Innovation (Verified Working) - "technology": [ - { - "name": "TechCrunch", - "url": "https://techcrunch.com/feed/", - "category": "tech_news", - "description": "Technology news and startup coverage", - }, - { - "name": "Ars Technica", - "url": "https://feeds.arstechnica.com/arstechnica/index", - "category": "tech_analysis", - "description": "Technology news and analysis", - }, - { - "name": "The Verge", - "url": "https://www.theverge.com/rss/index.xml", - "category": "tech_news", - "description": "Technology, science, art, and culture", - }, - { - "name": "Wired", - "url": "https://www.wired.com/feed/rss", - "category": "tech_culture", - "description": "Technology and its impact on culture", - }, - { - "name": "MIT Technology Review", - "url": "https://www.technologyreview.com/feed/", - "category": "tech_research", - "description": "Emerging technology insights", - }, - { - "name": "Mashable", - "url": "https://mashable.com/feeds/rss/all", - "category": "tech_culture", - "description": "Digital culture and tech news", - }, - { - "name": "Engadget", - "url": "https://www.engadget.com/rss.xml", - "category": "tech_gadgets", - "description": "Technology and gadget news", - }, - { - "name": "ZDNet", - "url": "https://www.zdnet.com/news/rss.xml", - "category": "tech_enterprise", - "description": "Business technology news", - }, - { - "name": "Slashdot", - "url": "http://rss.slashdot.org/Slashdot/slashdotMain", - "category": "tech_community", - "description": "News for nerds, stuff that matters", - }, - ], - # Economic & Financial (Working Feeds) - "economic": [ - { - "name": "Federal Reserve Press Releases", - "url": "https://www.federalreserve.gov/feeds/press_all.xml", - "category": "monetary_policy", - "description": "Federal Reserve announcements", - }, - { - "name": "SEC Press Releases", - "url": "https://www.sec.gov/news/pressreleases.rss", - "category": "financial_regulation", - "description": "SEC enforcement and regulatory actions", - }, - { - "name": "Bloomberg Markets", - "url": "https://feeds.bloomberg.com/markets/news.rss", - "category": "financial_markets", - "description": "Financial markets news", - }, - { - "name": "MarketWatch Top Stories", - "url": "https://feeds.marketwatch.com/marketwatch/topstories/", - "category": "financial_news", - "description": "Stock market and financial news", - }, - { - "name": "Financial Times", - "url": "https://www.ft.com/?format=rss&edition=international", - "category": "global_finance", - "description": "Global financial news", - }, - { - "name": "CNBC Top News", - "url": "https://search.cnbc.com/rs/search/combinedcms/view.xml?partnerId=wrss01&id=100003114", - "category": "business_news", - "description": "CNBC top business news", - }, - { - "name": "Wall Street Journal Markets", - "url": "https://feeds.a.dj.com/rss/RSSMarketsMain.xml", - "category": "financial_markets", - "description": "WSJ market coverage", - }, - { - "name": "Yahoo Finance", - "url": "https://finance.yahoo.com/news/rssindex", - "category": "financial_news", - "description": "Yahoo Finance top stories", - }, - { - "name": "Washington Business Journal", - "url": "https://www.bizjournals.com/washington/feeds/latest.xml", - "category": "regional_business", - "description": "DC area business news", - }, - { - "name": "Northern Virginia Chamber", - "url": "https://www.nvchamber.org/feed/", - "category": "regional_business", - "description": "Northern Virginia business community", - }, - { - "name": "DC Chamber of Commerce", - "url": "https://www.dcchamber.org/feed/", - "category": "regional_business", - "description": "DC business community news", - }, - ], - # Environmental & Science (Verified Working) - "environmental": [ - { - "name": "NASA Breaking News", - "url": "https://www.nasa.gov/rss/dyn/breaking_news.rss", - "category": "space_science", - "description": "NASA space and science news", - }, - { - "name": "Nature News", - "url": "https://www.nature.com/nature.rss", - "category": "scientific_research", - "description": "Scientific research and discoveries", - }, - { - "name": "Science Magazine", - "url": "https://www.science.org/rss/news_current.xml", - "category": "scientific_research", - "description": "Science news and research", - }, - { - "name": "National Weather Service Alerts - Virginia", - "url": "https://alerts.weather.gov/cap/va.php?x=0", - "category": "weather_alerts", - "description": "Virginia weather alerts and warnings", - }, - { - "name": "Scientific American", - "url": "http://rss.sciam.com/ScientificAmerican-Global", - "category": "popular_science", - "description": "Science news and analysis", - }, - { - "name": "Live Science", - "url": "https://www.livescience.com/feeds/all", - "category": "popular_science", - "description": "Science news and discoveries", - }, - { - "name": "Phys.org", - "url": "https://phys.org/rss-feed/", - "category": "physics_news", - "description": "Physics and technology news", - }, - ], - # International Organizations (Working Alternatives) - "international": [ - { - "name": "United Nations News", - "url": "https://news.un.org/feed/subscribe/en/news/all/rss.xml", - "category": "international_organizations", - "description": "UN news and updates", - }, - { - "name": "IMF News", - "url": "https://www.imf.org/en/News/RSS", - "category": "international_finance", - "description": "International Monetary Fund news", - }, - { - "name": "European Union News", - "url": "https://www.consilium.europa.eu/en/press/rss/", - "category": "european_union", - "description": "EU Council press releases", - }, - ], - # Defense & Military (Working Feeds) - "defense": [ - { - "name": "Department of Defense", - "url": "https://www.defense.gov/DesktopModules/ArticleCS/RSS.ashx?max=10&ContentType=1&Site=945", - "category": "military_news", - "description": "DoD news releases", - }, - { - "name": "Army News", - "url": "https://www.army.mil/rss/233/", - "category": "military_branch", - "description": "US Army news", - }, - { - "name": "Navy News", - "url": "https://www.navy.mil/DesktopModules/ArticleCS/RSS.ashx?ContentType=1&Site=1&max=10", - "category": "military_branch", - "description": "US Navy news", - }, - { - "name": "Air Force News", - "url": "https://www.af.mil/DesktopModules/ArticleCS/RSS.ashx?ContentType=1&Site=1&max=20", - "category": "military_branch", - "description": "US Air Force news", - }, - { - "name": "Military.com News", - "url": "https://www.military.com/rss/", - "category": "military_news", - "description": "Military news and benefits information", - }, - { - "name": "Defense One", - "url": "https://www.defenseone.com/rss/technology/", - "category": "defense_technology", - "description": "Defense technology and innovation news", - }, - { - "name": "C4ISRNET", - "url": "https://www.c4isrnet.com/arc/outboundfeeds/rss/", - "category": "defense_technology", - "description": "Command, control, communications, computers intelligence, surveillance and reconnaissance", - }, - { - "name": "Breaking Defense", - "url": "https://breakingdefense.com/feed/", - "category": "defense_analysis", - "description": "Defense industry analysis and breaking news", - }, - ], - # Federal Contractors & Technology - "federal_contractors": [ - { - "name": "Federal News Network", - "url": "https://federalnewsnetwork.com/feed/", - "category": "federal_contracting", - "description": "Federal government news and contracting", - }, - { - "name": "Washington Technology", - "url": "https://washingtontechnology.com/rss/all.aspx", - "category": "government_technology", - "description": "Government technology and IT contracting", - }, - { - "name": "FCW Federal Computer Week", - "url": "https://fcw.com/rss-feeds/all.aspx", - "category": "government_technology", - "description": "Federal IT and technology news", - }, - { - "name": "FTC Press Releases", - "url": "https://www.ftc.gov/news-events/press-releases/rss", - "category": "federal_regulation", - "description": "Federal Trade Commission press releases", - }, - { - "name": "FCC Daily Digest", - "url": "https://www.fcc.gov/news-events/headlines/rss", - "category": "telecommunications_regulation", - "description": "Federal Communications Commission news", - }, - ], - # Science & Research - "science": [ - { - "name": "NIH News", - "url": "https://www.nih.gov/news-events/news-releases/rss", - "category": "medical_research", - "description": "National Institutes of Health research news", - }, - { - "name": "NSF News", - "url": "https://www.nsf.gov/news/news_feeds.jsp", - "category": "scientific_research", - "description": "National Science Foundation research updates", - }, - { - "name": "Smithsonian Magazine", - "url": "https://www.smithsonianmag.com/rss/latest_articles/", - "category": "science_culture", - "description": "Science, history, and culture from Smithsonian", - }, - ], - # Legal & Regulatory - "legal": [ - { - "name": "Legal Times", - "url": "https://www.law.com/legaltimes/rss/", - "category": "legal_news", - "description": "DC legal community news", - } - ], - # Health & Public Health (Working Alternatives) - "health": [ - { - "name": "CDC Newsroom", - "url": "https://tools.cdc.gov/api/v2/resources/media/316422.rss", - "category": "public_health", - "description": "CDC health alerts and updates", - }, - { - "name": "FDA News Releases", - "url": "https://www.fda.gov/about-fda/contact-fda/stay-informed/rss-feeds/press-releases/rss.xml", - "category": "food_drug_safety", - "description": "FDA regulatory news", - }, - { - "name": "WebMD Health News", - "url": "https://www.webmd.com/rss/health-news.xml", - "category": "health_news", - "description": "Consumer health news", - }, - { - "name": "MedPage Today", - "url": "https://www.medpagetoday.com/rss/headlines.xml", - "category": "medical_news", - "description": "Medical news for healthcare professionals", - }, - { - "name": "New England Journal of Medicine", - "url": "https://www.nejm.org/action/showFeed?jc=nejm&type=etoc&feed=rss", - "category": "medical_journals", - "description": "Medical research and reviews", - }, - ], - # Education & Research (Working Alternatives) - "education": [ - { - "name": "Chronicle of Higher Education", - "url": "https://www.chronicle.com/feed", - "category": "higher_education", - "description": "Higher education news", - }, - { - "name": "Inside Higher Ed", - "url": "https://www.insidehighered.com/rss/feed", - "category": "higher_education", - "description": "College and university news", - }, - { - "name": "EdWeek", - "url": "https://www.edweek.org/feed/", - "category": "k12_education", - "description": "K-12 education news", - }, - { - "name": "THE Campus", - "url": "https://www.timeshighereducation.com/campus/feed", - "category": "higher_education", - "description": "Times Higher Education campus news", - }, - ], - # Additional News Sources (Aggregators and Alternatives) - "news_alternatives": [ - { - "name": "Google News - US", - "url": "https://news.google.com/rss?hl=en-US&gl=US&ceid=US:en", - "category": "aggregator", - "description": "Google News aggregator for US news", - }, - { - "name": "Google News - Virginia", - "url": "https://news.google.com/rss/search?q=Virginia&hl=en-US&gl=US&ceid=US:en", - "category": "virginia_aggregator", - "description": "Google News aggregator for Virginia news", - }, - { - "name": "Reddit - Politics", - "url": "https://www.reddit.com/r/politics/.rss", - "category": "social_news", - "description": "Political discussions from Reddit", - }, - { - "name": "Reddit - News", - "url": "https://www.reddit.com/r/news/.rss", - "category": "social_news", - "description": "News discussions from Reddit", - }, - { - "name": "Hacker News", - "url": "https://news.ycombinator.com/rss", - "category": "tech_community", - "description": "Hacker News front page", - }, - ], -} - - -def get_all_feeds(): - """Return all feeds as a flat list with metadata""" - all_feeds = [] - for category_group, feeds in RSS_FEEDS.items(): - for feed in feeds: - feed_config = feed.copy() - feed_config["category_group"] = category_group - all_feeds.append(feed_config) - return all_feeds - - -def get_feeds_by_category_group(category_group: str): - """Get feeds filtered by category group""" - return RSS_FEEDS.get(category_group, []) - - -def get_feed_count(): - """Get total number of configured feeds""" - return len(get_all_feeds()) - - -def get_feeds_by_category(category: str): - """Get feeds filtered by specific category""" - matching_feeds = [] - for category_group, feeds in RSS_FEEDS.items(): - for feed in feeds: - if feed["category"] == category: - feed_config = feed.copy() - feed_config["category_group"] = category_group - matching_feeds.append(feed_config) - return matching_feeds - - -def get_category_list(): - """Get unique list of all categories""" - categories = set() - for feeds in RSS_FEEDS.values(): - for feed in feeds: - categories.add(feed["category"]) - return sorted(categories) - - -def validate_feeds(): - """Validate feed structure and return any issues""" - issues = [] - required_fields = ["name", "url", "category", "description"] - - for category_group, feeds in RSS_FEEDS.items(): - for i, feed in enumerate(feeds): - for field in required_fields: - if field not in feed: - issues.append(f"{category_group}[{i}]: Missing required field '{field}'") - elif not feed[field]: - issues.append(f"{category_group}[{i}]: Empty value for field '{field}'") - - # Check for duplicate URLs - all_urls = [f["url"] for f in get_all_feeds()] - if all_urls.count(feed["url"]) > 1: - issues.append(f"{category_group}[{i}]: Duplicate URL found: {feed['url']}") - - return issues - - -# Print summary when module is run directly -if __name__ == "__main__": - print("RSS Feed Configuration Summary:") - print(f"Total feeds configured: {get_feed_count()}") - print("\nFeeds by category group:") - for category_group in RSS_FEEDS: - count = len(RSS_FEEDS[category_group]) - print(f" {category_group}: {count} feeds") - - print(f"\nTotal unique categories: {len(get_category_list())}") - - # Validate configuration - issues = validate_feeds() - if issues: - print("\nConfiguration issues found:") - for issue in issues: - print(f" - {issue}") - else: - print("\nConfiguration validated successfully!") diff --git a/src/config/settings.py b/src/config/settings.py index 568d6d4..7983b50 100644 --- a/src/config/settings.py +++ b/src/config/settings.py @@ -10,15 +10,16 @@ class Settings(BaseSettings): database_url: str = os.getenv("DATABASE_URL", "sqlite:///./data/insightweaver.db") - anthropic_api_key: str = os.getenv("ANTHROPIC_API_KEY", "") + # ANTHROPIC_API_KEY is no longer read here. The key lives in the OS keychain + # and is read by src.config.credentials when a model client is built -- + # never at import, so nothing that does not call a model needs a keychain. + # Removed 2026-09-22 (backlog task 026); there is deliberately no fallback. - debug: bool = os.getenv("DEBUG", "False").lower() == "true" - log_level: str = os.getenv("LOG_LEVEL", "INFO") - - enable_smart_rss_fetch: bool = os.getenv("ENABLE_SMART_RSS_FETCH", "True").lower() == "true" - smart_rss_fetch_threshold_minutes: int = int( - os.getenv("SMART_RSS_FETCH_THRESHOLD_MINUTES", "60") - ) + # `debug`, `log_level`, `enable_smart_rss_fetch` and + # `smart_rss_fetch_threshold_minutes` were removed here on 2026-09-22 + # (backlog task 027): none had a reader anywhere in src/. The `--debug` + # flag runs through src/cli/output.py, which keeps its own state and never + # consulted these. # How similar two observations' MinHash signatures must be before they are # treated as the same item published twice. 0.7 was chosen against measured @@ -38,7 +39,23 @@ class Settings(BaseSettings): project_root: Path = Path(__file__).parent.parent.parent data_dir: Path = project_root / "data" - logs_dir: Path = project_root / "src" / "logs" + + # Every outbound model request is written here before it is sent, and its + # usage after (src/llm/audit.py). JSON lines, one file per day, gitignored. + # Overridable so it can be kept out of a cloud-synced checkout. + # (2026-09-22, backlog task 026.) + llm_audit_dir: Path = Path( + os.getenv("LLM_AUDIT_DIR", str(project_root / "data" / "llm-audit")) + ).expanduser() + + # Two named models, one per role, so that no call site picks a model string. + # Decided 2026-09-22 (docs/PLAN.md, Q11): Sonnet 5 adjudicates, + # Opus 5 writes. A retired model is then a one-line change in one place. + llm_triage_model: str = os.getenv("LLM_TRIAGE_MODEL", "claude-sonnet-5") + llm_synthesis_model: str = os.getenv("LLM_SYNTHESIS_MODEL", "claude-opus-5") + + # The keychain service every credential is stored under (src/config/credentials.py). + keyring_service: str = "insightweaver" # Position and the watch set are hand-authored and live in the operator's # *private* repository -- they name real decisions, deadlines and exposures @@ -62,7 +79,6 @@ class Config: def __init__(self, **kwargs): super().__init__(**kwargs) self.data_dir.mkdir(exist_ok=True) - self.logs_dir.mkdir(exist_ok=True) settings = Settings() diff --git a/src/database/connection.py b/src/database/connection.py index 2cf299a..b4e62a5 100644 --- a/src/database/connection.py +++ b/src/database/connection.py @@ -4,17 +4,11 @@ from sqlalchemy.orm import Session, sessionmaker from src.config.settings import settings -from src.database.models import Base engine = create_engine(settings.database_url) SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine) -def create_tables(): - """Create all database tables""" - Base.metadata.create_all(bind=engine) - - @contextmanager def get_db() -> Session: """Database session context manager""" diff --git a/src/database/migrations/add_monitor_tables.py b/src/database/migrations/add_monitor_tables.py new file mode 100644 index 0000000..2098d47 --- /dev/null +++ b/src/database/migrations/add_monitor_tables.py @@ -0,0 +1,160 @@ +""" +Migration: add the decision monitor's tables. + +Additive. Creates whichever of the monitor's tables are absent and touches +nothing that exists. The tables are created from their models, as +``add_watches_table`` and ``add_observations_and_evidence`` do, so the +migration and the models cannot drift; a CHECK constraint on the model is a +CHECK constraint in the database. + +One migration for the monitor rather than one per task, because none of it +has been applied anywhere yet: the tables arrive here as tasks 028 to 031 land +(``routes`` first), and an operator who runs this once gets whatever the tree +holds. Re-running it after a later task creates only what is new. + +``downgrade()`` drops the tables and requires ``--confirm``. ``routes`` is +derived and rebuildable from observations and watches; ``adjudications`` +(task 029) and ``watch_beliefs`` (task 030) are ledgers of what the model was +asked and what the operator believed, and nothing rebuilds them, which the +help text says. ``briefs`` (task 031) records each brief rendered; dropping it +only resets the next brief's default window to seven days. Task 030 also added four lifecycle columns to ``watches``; +``add_watch_columns`` adds whichever an existing table lacks, one ALTER each, +and the way down drops them. + +Added 2026-09-22 for backlog task 028. +""" + +from __future__ import annotations + +import argparse +import sys +from typing import Any + +from sqlalchemy import inspect, text +from sqlalchemy.engine import Engine + +from src.database.connection import engine +from src.database.models import Adjudication, BriefRun, Route, WatchBelief + +__all__ = ["TABLES", "WATCH_COLUMNS", "downgrade", "upgrade"] + +# Creation order. Reversed on the way down. +TABLES = ("routes", "adjudications", "watch_beliefs", "briefs") + +_MODELS: dict[str, Any] = { + "routes": Route, + "adjudications": Adjudication, + "watch_beliefs": WatchBelief, + "briefs": BriefRun, +} + +# Columns task 030 added to `watches`, with the DDL that adds each to an +# existing table. A fresh table gets them from the model; an older table gets +# them here, one ALTER per missing column, so re-running is harmless. +WATCH_COLUMNS: dict[str, str] = { + "retired_at": "DATETIME", + "resolved_at": "DATETIME", + "outcome": ( + "VARCHAR(10) CONSTRAINT ck_watches_outcome " + "CHECK (outcome IS NULL OR outcome IN ('yes', 'no'))" + ), + "resolution_note": "TEXT", +} + +_CONFIRM_HELP = ( + "Dropping the monitor tables discards routing links, the adjudication ledger\n" + "and the belief ledger, and removes the lifecycle columns from watches.\n" + "Routes are derived and `insightweaver route --rebuild` restores them; the\n" + "two ledgers are the record of what the model was asked, what it cost, and\n" + "what you believed when, and nothing restores them. Re-run with --confirm if\n" + "that is what you want:\n\n" + " python -m src.database.migrations.add_monitor_tables --down --confirm\n" +) + + +def _watch_columns_present(target: Engine) -> set[str]: + inspector = inspect(target) + if not inspector.has_table("watches"): + return set() + return {c["name"] for c in inspector.get_columns("watches")} + + +def add_watch_columns(target: Engine | None = None) -> list[str]: + """Add whichever lifecycle columns `watches` lacks. Returns the names added.""" + target = target or engine + present = _watch_columns_present(target) + if not present: + return [] # no watches table yet; add_watches_table creates it with every column + added = [] + with target.begin() as conn: + for name, ddl in WATCH_COLUMNS.items(): + if name in present: + continue + conn.execute(text(f"ALTER TABLE watches ADD COLUMN {name} {ddl}")) + print(f"Added watches.{name}.") + added.append(name) + return added + + +def upgrade(target: Engine | None = None) -> list[str]: + """Create whichever monitor tables are absent and add the watches columns.""" + target = target or engine + inspector = inspect(target) + created = [] + for name in TABLES: + if inspector.has_table(name): + print(f"{name} already exists; nothing to do.") + continue + model = _MODELS[name] + model.__table__.create(bind=target) + print(f"Created {name} ({len(model.__table__.columns)} columns).") + created.append(name) + add_watch_columns(target) + return created + + +def downgrade(target: Engine | None = None, *, confirmed: bool = False) -> list[str]: + """Drop the monitor tables and the watches columns. Requires ``confirmed``.""" + if not confirmed: + raise SystemExit(_CONFIRM_HELP) + target = target or engine + # Columns first, in one transaction: a DROP COLUMN is the step that can be + # refused (a table-level constraint naming the column would refuse it), and + # a refusal must leave the tables in place rather than half a schema. + present = _watch_columns_present(target) + with target.begin() as conn: + for name in reversed(list(WATCH_COLUMNS)): + if name in present: + conn.execute(text(f"ALTER TABLE watches DROP COLUMN {name}")) + print(f"Dropped watches.{name}.") + inspector = inspect(target) + dropped = [] + for name in reversed(TABLES): + if not inspector.has_table(name): + print(f"{name} does not exist; nothing to do.") + continue + _MODELS[name].__table__.drop(bind=target) + print(f"Dropped {name}.") + dropped.append(name) + return dropped + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser( + prog="add_monitor_tables", + description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter, + ) + parser.add_argument("--down", action="store_true", help="drop the tables again") + parser.add_argument("--confirm", action="store_true", help="required by --down") + args = parser.parse_args(argv) + + if args.down: + downgrade(confirmed=args.confirm) + return 0 + upgrade() + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/src/database/migrations/create_schema.py b/src/database/migrations/create_schema.py new file mode 100644 index 0000000..96c3a6f --- /dev/null +++ b/src/database/migrations/create_schema.py @@ -0,0 +1,42 @@ +""" +Migration: create every table the models declare that the database lacks. + +For a fresh database. Before 2026-09-23 nothing created ``rss_feeds`` and +``articles`` on a new install -- the additive migrations cover only the tables +they were written for, and the ``create_all`` call that used to run at startup +went with the deleted pipeline -- so ``ingest`` on a clean checkout failed on +its first insert. This is the one bootstrap: ``Base.metadata.create_all`` over +the declared models, which creates what is absent and touches nothing that +exists. It adds no columns to an existing table; the additive migrations do +that, and re-running them after this is harmless. + +Added 2026-09-23 for backlog task 033, found while writing GETTING_STARTED. +""" + +from __future__ import annotations + +from sqlalchemy import inspect +from sqlalchemy.engine import Engine + +from src.database.connection import engine +from src.database.models import Base + +__all__ = ["upgrade"] + + +def upgrade(target: Engine = engine) -> list[str]: + """Create the absent tables; return their names in creation order.""" + before = set(inspect(target).get_table_names()) + Base.metadata.create_all(bind=target) + after = set(inspect(target).get_table_names()) + created = [name for name in Base.metadata.sorted_tables if name.name in after - before] + return [table.name for table in created] + + +if __name__ == "__main__": + made = upgrade() + if made: + for name in made: + print(f"Created {name}.") + else: + print("Every declared table exists; nothing to do.") diff --git a/src/database/migrations/drop_forecast_tables.py b/src/database/migrations/drop_forecast_tables.py deleted file mode 100644 index f9c1521..0000000 --- a/src/database/migrations/drop_forecast_tables.py +++ /dev/null @@ -1,36 +0,0 @@ -""" -Migration: Drop forecast subsystem tables. - -The standalone forecast subsystem -- a separate Claude pipeline producing -Rumsfeld-bucketed scenarios -- has been replaced by a derived view over the -existing predictions ledger and question graph. Its persistence tables are -no longer populated by any code path. - -One-directional: no downgrade. The forecast subsystem itself has been -deleted; recreating the tables would not bring back the producers. -""" - -from sqlalchemy import text - -from src.database.connection import engine - -FORECAST_TABLES = [ - "causal_chains", - "forecast_scenarios", - "long_term_forecasts", - "forecast_runs", -] - - -def upgrade(): - """Drop forecast tables in FK-safe order.""" - print("Dropping forecast subsystem tables...") - with engine.begin() as conn: - for table in FORECAST_TABLES: - conn.execute(text(f"DROP TABLE IF EXISTS {table}")) - print(f" dropped {table} (if it existed)") - print("Forecast subsystem table drop completed.") - - -if __name__ == "__main__": - upgrade() diff --git a/src/database/migrations/drop_memory_facts.py b/src/database/migrations/drop_memory_facts.py deleted file mode 100644 index 41b4e1a..0000000 --- a/src/database/migrations/drop_memory_facts.py +++ /dev/null @@ -1,28 +0,0 @@ -""" -Migration: Drop the memory_facts table. - -MemoryFact was schema-only -- a subject/predicate/object triple table with a -confidence float and no extractor populating it from synthesis output. The -information it was supposed to capture is already structured in the -situation prompt (actors, power_dynamics, etc.), making the table inert -dead schema. This migration drops it. - -One-directional: there is no downgrade because no production data ever lived -here. -""" - -from sqlalchemy import text - -from src.database.connection import engine - - -def upgrade(): - """Drop memory_facts if present.""" - print("Dropping memory_facts table...") - with engine.begin() as conn: - conn.execute(text("DROP TABLE IF EXISTS memory_facts")) - print("memory_facts dropped (if it existed).") - - -if __name__ == "__main__": - upgrade() diff --git a/src/database/migrations/drop_orphan_tables.py b/src/database/migrations/drop_orphan_tables.py deleted file mode 100644 index 84bb231..0000000 --- a/src/database/migrations/drop_orphan_tables.py +++ /dev/null @@ -1,46 +0,0 @@ -""" -Migration: Drop Orphan Tables -Removes tables left behind by feature versions that were ripped out of the -codebase. None of these have a model class in src/database/models.py, so -SQLAlchemy never touches them -- they just occupy space and, in the case of -`decisions` and `predictions`, collide with names later stages need. - -This migration is intentionally one-directional: there is no downgrade, -because the schemas of these tables were never tracked in version control -and there is nothing meaningful to recreate. -""" - -from sqlalchemy import text - -from src.database.connection import engine - -ORPHAN_TABLES = [ - "api_data_points", - "api_data_sources", - "civic_action_windows", - "decision_conversations", - "decision_dossiers", - "decisions", - "extracted_claims", - "monitored_pages", - "page_changes", - "predictions", - "privacy_captures", - "source_profiles", - "state_vector_observations", - "trend_analyses", -] - - -def upgrade(): - """Drop orphan tables if present.""" - print("Dropping orphan tables...") - with engine.begin() as conn: - for table in ORPHAN_TABLES: - conn.execute(text(f"DROP TABLE IF EXISTS {table}")) - print(f" dropped {table} (if it existed)") - print("\nOrphan table cleanup completed.") - - -if __name__ == "__main__": - upgrade() diff --git a/src/database/models.py b/src/database/models.py deleted file mode 100644 index fd2294b..0000000 --- a/src/database/models.py +++ /dev/null @@ -1,384 +0,0 @@ -""" -Database models. - -Three tables: the feeds we read, the articles we stored from them, and the -watches the operator has pre-registered. - -Everything else was deleted by backlog task 012 along with the briefing product -that owned it -- syntheses, context snapshots, provenance, topic clusters, -narrative frames, questions, predictions, decisions and beats. The tables are -dropped by ``src.database.migrations.drop_briefing_tables``; the models are -removed here so that ``create_tables()`` cannot quietly recreate a concept the -rewrite removed. - -``watches`` is the first table of the rewrite, added 2026-08-31 by backlog task -013. Its CHECK constraints are not decoration -- see the class docstring. - -``observations`` and ``evidence`` are the second and third, added 2026-08-31 by -backlog task 014. - -**The rule for ``articles`` versus ``observations``, decided by task 014 and -written here because this is the file both of them live in.** They coexist, with -one direction of authority and one writer: - -* ``articles`` is the *legacy ingestion table*. It holds the 55,249 rows written - before the rewrite and it stays the row shape the pre-rewrite code reads. It - is not deleted and not migrated. -* ``observations`` is *authoritative for everything the rewrite builds*. A tier - added from task 014 onwards reads ``observations`` and never ``articles``. -* Exactly one code path writes an observation: - ``src.sources.observation.store_observation``, called from - ``src.sources.store.store_items``, which is the store path every adapter in - ``src/sources/`` already goes through. Each new article gets an observation in - the same transaction, and ``observations.article_id`` links the two. -* The 55,249 pre-existing rows have no observation, and neither does anything - the legacy ``src/rss/fetcher.py`` path writes directly. That is a known, - bounded gap, not an ambiguity: the content hash is a pure function of columns - those rows already carry, so a backfill is mechanical and is deliberately left - to its own task rather than run inside this one. - -The one thing that was not acceptable was two corpora with no stated rule. The -rule is: **new tiers read observations; articles is the pre-rewrite archive.** -""" - -from sqlalchemy import ( - DDL, - JSON, - Boolean, - CheckConstraint, - Column, - Date, - DateTime, - Float, - ForeignKey, - Index, - Integer, - String, - Text, - UniqueConstraint, - event, -) -from sqlalchemy.ext.declarative import declarative_base -from sqlalchemy.orm import relationship - -from ..utils import utcnow - -Base = declarative_base() - - -class ObservationIsImmutable(RuntimeError): - """ - Raised when anything tries to change a stored observation. - - Not a warning and not a silently-ignored write. An observation is - content-addressed, so its hash is a claim that the payload beside it is the - payload that produced the hash. A single successful UPDATE turns every - replay run afterwards into a comparison against a corpus that no longer - matches its own identities, and nothing would say so. - """ - - -class RSSFeed(Base): - """RSS feed sources - unchanged""" - - __tablename__ = "rss_feeds" - - id = Column(Integer, primary_key=True) - url = Column(String(500), nullable=False, unique=True) - name = Column(String(200), nullable=False) - category = Column(String(100)) - is_active = Column(Boolean, default=True) - last_fetched = Column(DateTime) - last_error = Column(Text) - error_count = Column(Integer, default=0) - created_at = Column(DateTime, default=utcnow) - updated_at = Column(DateTime, default=utcnow, onupdate=utcnow) - - articles = relationship("Article", back_populates="feed") - - -class Article(Base): - """ - Articles from RSS feeds - Optimized for context engineering - stores raw content and minimal metadata - """ - - __tablename__ = "articles" - - id = Column(Integer, primary_key=True) - feed_id = Column(Integer, ForeignKey("rss_feeds.id")) - guid = Column(String(500), nullable=False) - url = Column(String(500)) - title = Column(String(500)) - description = Column(Text) - content = Column(Text) - published_date = Column(DateTime) - author = Column(String(200)) - categories = Column(JSON) # List of categories/tags from feed - - # Normalized content for context - normalized_content = Column(Text) # Clean text without HTML - word_count = Column(Integer) - language = Column(String(10)) - - # Context engineering fields - entities = Column(JSON) # Extracted entities (people, orgs, locations) - embedding_summary = Column(Text) # AI-generated 2-3 sentence summary - relevance_score = Column(Float) # Simple score: recency + user profile match - last_included_in_synthesis = Column(DateTime) # Track usage in context - - # Priority and deduplication fields - priority_score = Column(Float) # Used for article filtering/sorting - priority_metadata = Column(JSON) # Stores duplicate tracking info - trend_metadata = Column(JSON) # Trend-related metadata - - # Content filtering (user preference based) - filtered = Column(Boolean, default=False) - filter_reason = Column(String(200)) - - # Timestamps - fetched_at = Column(DateTime, default=utcnow) - created_at = Column(DateTime, default=utcnow) - - feed = relationship("RSSFeed", back_populates="articles") - - __table_args__ = ( - UniqueConstraint("feed_id", "guid", name="_feed_guid_uc"), - Index("idx_published_date", "published_date"), - Index("idx_fetched_at", "fetched_at"), - Index("idx_relevance_score", "relevance_score"), # For context selection - Index("idx_filtered", "filtered"), # Quick filtering queries - # Composite indexes for critical query paths - # Both composite indexes were added for briefing-era query paths that - # task 012 deleted (curator.py and content_engine.py). They are kept: - # "recent unfiltered articles" is the shape every tier reads, and - # dropping an index is a separate, measurable decision. - Index("idx_articles_filtered_fetched", "filtered", "fetched_at"), - Index("idx_articles_filtered_published", "filtered", "published_date"), - ) - - -class Watch(Base): - """ - One pre-registered claim, the decision it serves, and what would move it. - - Rows arrive from exactly one place: ``src.position.watches.sync_watches``, - reading the operator's hand-authored file. Nothing else writes here. - Invariant 6 -- the system never authors its own watches -- is a property of - the code paths that exist, so no path exists. - - **The constraints are the enforcement, not a formality.** Invariant 2 says - every Watch must name a decision; the loader rejects a blank ``so_what``, - and ``ck_watches_so_what_present`` rejects it again at the storage layer, so - a row written by hand through ``sqlite3`` fails the same way a bad YAML file - does. The repository's own history is the argument: 25 unfalsifiable - predictions accumulated in the deleted ledger because a missing field was - tolerated by every layer that could have refused it. - - ``triggers`` is JSON, and structured JSON specifically -- a list of clauses - over terms, entities and source allowlists. Tier 1 compiles it into a - deterministic predicate. The column it replaces, ``predictions. - trigger_condition``, was free text; 33 rows were written against it and none - were ever graded, because nothing downstream could evaluate a sentence. - """ - - __tablename__ = "watches" - - # The operator's own id from the file, not a surrogate. It is the name they - # will type and the name an alert will carry, and a watch that is renamed in - # the file is a different watch. - id = Column(String(100), primary_key=True) - - claim = Column(Text, nullable=False) - belief = Column(Float, nullable=False) - - # so_what, split: the key is what makes invariant 2 machine-checkable, the - # prose is what makes it readable. `decision_key` references a decision in - # the Position file, which is not a table -- Position lives in a private - # repo under git, so this is deliberately not a foreign key. - decision_key = Column(String(100), nullable=False) - so_what = Column(Text, nullable=False) - - triggers = Column(JSON, nullable=False) - expires = Column(Date, nullable=False) - staleness_alert_days = Column(Integer, nullable=False) - - created_at = Column(DateTime, default=utcnow) - updated_at = Column(DateTime, default=utcnow, onupdate=utcnow) - - __table_args__ = ( - CheckConstraint("length(trim(so_what)) > 0", name="ck_watches_so_what_present"), - CheckConstraint("length(trim(decision_key)) > 0", name="ck_watches_decision_present"), - CheckConstraint("belief >= 0.0 AND belief <= 1.0", name="ck_watches_belief_range"), - CheckConstraint("staleness_alert_days >= 1", name="ck_watches_staleness_min"), - Index("idx_watches_decision_key", "decision_key"), - Index("idx_watches_expires", "expires"), - ) - - -class Observation(Base): - """ - One thing a source published, keyed by a hash of what it said. - - **The hash is the identity.** There is no surrogate primary key, because a - surrogate key would let the same document be stored twice under two ids and - the duplicate would be invisible. ``content_hash`` is computed by - ``src.sources.observation.observation_hash`` from the fields in - ``OBSERVATION_FIELDS`` and nothing else -- specifically not from - ``observed_at``, not from the source's last-fetch time, and not from - anything else that changes between two fetches of an unchanged document. - That exclusion is the whole invariant, so it is tested directly - (tests/sources/test_observation.py::TestHashIsContentOnly) rather than - inferred from the field list. - - ``observed_at`` is a column precisely *because* it is not in the hash: when - we first saw this content is worth keeping and is not part of what the - content is. It is the one per-fetch value on the row and it lives outside - the payload. - - ``payload`` is the normalized adapter output, verbatim, exactly the values - that were hashed. It is never rewritten -- see - :class:`ObservationIsImmutable` and the BEFORE UPDATE trigger below. - - ``minhash`` is the near-duplicate signature of the item's text, written once - at insert. It is stored rather than recomputed so that a grouping computed - now and a grouping computed after a replay are the same grouping. See - ``src/sources/minhash.py``. - - Added 2026-08-31 for backlog task 014. - """ - - __tablename__ = "observations" - - content_hash = Column(String(80), primary_key=True) - - # Which source published it. The same text from two sources is two - # observations, on purpose: "who said this" is part of what was observed, - # and grouping the pair back together is what the MinHash signature is for. - source_id = Column(Integer, ForeignKey("rss_feeds.id"), nullable=False) - - # The legacy row this observation was written alongside. Nullable because a - # backfill from the pre-rewrite corpus would set it and a future - # observations-only source may not have one. See the module docstring's rule. - article_id = Column(Integer, ForeignKey("articles.id")) - - payload = Column(JSON, nullable=False) - minhash = Column(JSON, nullable=False) - - # A projection of payload["published_date"], written by the same call that - # writes the payload, so that "observations in this window" is an indexed - # query rather than a JSON scan. Immutability is what keeps it honest: it - # cannot drift from the payload because neither can change. - published_date = Column(DateTime) - - observed_at = Column(DateTime, default=utcnow, nullable=False) - - __table_args__ = ( - CheckConstraint("content_hash LIKE 'sha256:%'", name="ck_observations_hash_prefix"), - Index("idx_observations_source", "source_id"), - Index("idx_observations_published", "published_date"), - Index("idx_observations_article", "article_id"), - ) - - -# Immutability, enforced twice on purpose. -# -# 1. The ORM guard below stops a mutation made through a Session, which is how -# application code would do it, and raises a named Python exception. -# 2. The trigger stops an UPDATE issued any other way -- a raw -# `session.execute(text("UPDATE ..."))`, the sqlite3 shell, a future -# migration written in a hurry. A guarantee that only holds for code that -# goes through the ORM is a convention, not a guarantee. -# -# The trigger is attached to the table's after_create, so it exists both when -# `Base.metadata.create_all()` builds a test database and when -# `src.database.migrations.add_observations_and_evidence` creates the real one. -# There is no second copy of the DDL to forget to update. -_OBSERVATIONS_IMMUTABLE_TRIGGER = DDL( - "CREATE TRIGGER observations_are_immutable " - "BEFORE UPDATE ON observations " - "BEGIN " - "SELECT RAISE(ABORT, " - "'observations are immutable: the content hash is the identity, so changing " - "a stored row would leave its hash describing content that is no longer there. " - "Insert a new observation instead.'); " - "END" -) - -event.listen( - Observation.__table__, - "after_create", - _OBSERVATIONS_IMMUTABLE_TRIGGER.execute_if(dialect="sqlite"), -) - - -@event.listens_for(Observation, "before_update", propagate=True) -def _refuse_observation_update(_mapper, _connection, target): - """Refuse an ORM flush that would UPDATE an observation.""" - raise ObservationIsImmutable( - f"refusing to update observation {target.content_hash}: observations are " - f"immutable once written. If the content changed, it is a different " - f"observation with a different hash." - ) - - -class Evidence(Base): - """ - One adjudicated link from an observation to a watch, under a named prompt. - - **``prompt_version`` is on every row, and that is the point of the table.** - Adjudication is the only stochastic tier in the system; the only way to tell - an improvement from a regression is to hold the observations fixed, run a - different prompt version over them, and diff. That requires knowing which - version produced which row, per row -- a version recorded once per run, in a - log, or in a config file is a version that cannot answer "and where did this - row come from" six weeks later. - - The uniqueness constraint ``(observation_hash, watch_id, prompt_version)`` is - what makes replay idempotent: one verdict per observation per watch per - prompt version, so re-running a version either inserts nothing or reveals - that the version is not deterministic. - - ``direction`` is two-valued. There is no 'neutral': an observation that - neither supports nor contradicts a watch produces no row, because a table of - non-evidence is a table nobody can read. - - Evidence is *derived*. It is the one thing here that may be deleted and - rebuilt, and ``insightweaver replay --commit`` does exactly that, scoped to a - single prompt version. - - Added 2026-08-31 for backlog task 014. - """ - - __tablename__ = "evidence" - - id = Column(Integer, primary_key=True) - - observation_hash = Column(String(80), ForeignKey("observations.content_hash"), nullable=False) - watch_id = Column(String(100), ForeignKey("watches.id"), nullable=False) - - direction = Column(String(20), nullable=False) - magnitude = Column(Float, nullable=False) - - prompt_version = Column(String(100), nullable=False) - rationale = Column(Text) - - created_at = Column(DateTime, default=utcnow) - - __table_args__ = ( - UniqueConstraint( - "observation_hash", - "watch_id", - "prompt_version", - name="_evidence_observation_watch_version_uc", - ), - CheckConstraint("direction IN ('supports', 'contradicts')", name="ck_evidence_direction"), - CheckConstraint( - "magnitude >= 0.0 AND magnitude <= 1.0", name="ck_evidence_magnitude_range" - ), - CheckConstraint( - "length(trim(prompt_version)) > 0", name="ck_evidence_prompt_version_present" - ), - Index("idx_evidence_prompt_version", "prompt_version"), - Index("idx_evidence_watch", "watch_id"), - ) diff --git a/src/database/models/__init__.py b/src/database/models/__init__.py new file mode 100644 index 0000000..190b936 --- /dev/null +++ b/src/database/models/__init__.py @@ -0,0 +1,86 @@ +""" +Database models, one module per table family (split 2026-09-22, backlog task 030, +when the single file passed 480 lines; nothing about any table changed): + +* ``sources``: the feeds we read (``rss_feeds``) and the legacy ``articles``. +* ``observations``: the content-addressed corpus and the ``evidence`` derived + from it. +* ``watches``: the operator's pre-registered claims and their belief ledger + (``watch_beliefs``). +* ``monitor``: Tier 1's ``routes`` and Tier 2's ``adjudications`` ledger. + +Everything else was deleted by backlog task 012 along with the briefing product +that owned it -- syntheses, context snapshots, provenance, topic clusters, +narrative frames, questions, predictions, decisions and beats. The tables are +dropped by ``src.database.migrations.drop_briefing_tables``; the models are +removed here so that ``Base.metadata.create_all()`` cannot quietly recreate a +concept the rewrite removed. + +``watches`` is the first table of the rewrite, added 2026-08-31 by backlog task +013. Its CHECK constraints are not decoration -- see the class docstring. + +``observations`` and ``evidence`` are the second and third, added 2026-08-31 by +backlog task 014. + +**The rule for ``articles`` versus ``observations``, decided by task 014 and +written here because this is the file both of them live in.** They coexist, with +one direction of authority and one writer: + +* ``articles`` is the *legacy ingestion table*. It holds the 55,249 rows written + before the rewrite and it stays the row shape the pre-rewrite code reads. It + is not deleted and not migrated. +* ``observations`` is *authoritative for everything the rewrite builds*. A tier + added from task 014 onwards reads ``observations`` and never ``articles``. +* Exactly one code path writes an observation: + ``src.sources.observation.store_observation``, called from + ``src.sources.store.store_items``, which is the store path every adapter in + ``src/sources/`` already goes through. Each new article gets an observation in + the same transaction, and ``observations.article_id`` links the two. +* The 55,249 pre-existing rows have no observation, and neither does anything + the legacy ``src/rss/fetcher.py`` path writes directly. That is a known, + bounded gap, not an ambiguity: the content hash is a pure function of columns + those rows already carry, so a backfill is mechanical and is deliberately left + to its own task rather than run inside this one. + +The one thing that was not acceptable was two corpora with no stated rule. The +rule is: **new tiers read observations; articles is the pre-rewrite archive.** + +``routes`` is Tier 1's output, added 2026-09-22 by backlog task 028: which +observations are candidates for which watch. It is derived and rebuildable, +which is why it may be deleted by ``route --rebuild`` and ``evidence`` may not +be deleted by anything but ``replay --commit``. + +``adjudications`` is Tier 2's run ledger, added 2026-09-22 by backlog task 029: +every pair the model was asked about, whatever it answered, with the tokens it +cost. ``evidence`` keeps holding the verdicts; the ledger is why a pair is not +asked twice and where a failed call is recorded rather than retried. + +``watch_beliefs`` is the belief ledger, added 2026-09-22 by backlog task 030, +append-only and written only from the watch file at sync and by the operator; +the same task gave ``watches`` its lifecycle columns (retired, resolved) so a +watch is never deleted once history hangs off it. + +``briefs`` records each brief rendered, added 2026-09-22 by backlog task 031; +the next brief's default window starts where the last one before today ended. +""" + +from .base import Base, LedgerIsAppendOnly, ObservationIsImmutable +from .monitor import Adjudication, BriefRun, Route +from .observations import Evidence, Observation +from .sources import Article, RSSFeed +from .watches import Watch, WatchBelief + +__all__ = [ + "Adjudication", + "Article", + "Base", + "BriefRun", + "Evidence", + "LedgerIsAppendOnly", + "Observation", + "ObservationIsImmutable", + "RSSFeed", + "Route", + "Watch", + "WatchBelief", +] diff --git a/src/database/models/base.py b/src/database/models/base.py new file mode 100644 index 0000000..40d1f5b --- /dev/null +++ b/src/database/models/base.py @@ -0,0 +1,33 @@ +""" +The declarative base and the exceptions the guards raise. + +Split out of the single ``models.py`` on 2026-09-22 (backlog task 030) when +that file passed 480 lines; one module per table family, nothing about any +table changed. +""" + +from sqlalchemy.ext.declarative import declarative_base + +Base = declarative_base() + + +class ObservationIsImmutable(RuntimeError): + """ + Raised when anything tries to change a stored observation. + + Not a warning and not a silently-ignored write. An observation is + content-addressed, so its hash is a claim that the payload beside it is the + payload that produced the hash. A single successful UPDATE turns every + replay run afterwards into a comparison against a corpus that no longer + matches its own identities, and nothing would say so. + """ + + +class LedgerIsAppendOnly(RuntimeError): + """ + Raised when anything tries to change or delete a belief ledger row. + + Belief history is the calibration record the system exists to accumulate; + a row that can be edited is a history that can be rewritten. Added + 2026-09-22 (backlog task 030). + """ diff --git a/src/database/models/monitor.py b/src/database/models/monitor.py new file mode 100644 index 0000000..ce28b55 --- /dev/null +++ b/src/database/models/monitor.py @@ -0,0 +1,139 @@ +""" +Part of the model split of 2026-09-22 (backlog task 030); see ``__init__``. +""" + +from sqlalchemy import ( + CheckConstraint, + Column, + DateTime, + Float, + ForeignKey, + Index, + Integer, + String, + Text, + UniqueConstraint, +) + +from ...utils import utcnow +from .base import Base + + +class Route(Base): + """ + One observation routed to one watch by a deterministic trigger clause. + + Tier 1's whole job is to keep the model from seeing the bulk of the corpus: + every row here is a candidate pair the adjudicator may be asked about, and + every observation with no row here is one it never sees. ``clause_index`` + records which of the watch's trigger clauses fired first, so a route can be + explained by reading the watch file rather than by re-running the matcher. + + Unique per ``(observation, watch)`` so that routing is idempotent: the same + observation routed twice is one link. Derived from ``observations`` and + ``watches.triggers`` alone, with no model call, so the table can be dropped + and rebuilt (``route --rebuild``) whenever a trigger changes. + + Added 2026-09-22 for backlog task 028. + """ + + __tablename__ = "routes" + + id = Column(Integer, primary_key=True) + observation_hash = Column(String(80), ForeignKey("observations.content_hash"), nullable=False) + watch_id = Column(String(100), ForeignKey("watches.id"), nullable=False) + clause_index = Column(Integer, nullable=False) + routed_at = Column(DateTime, default=utcnow, nullable=False) + + __table_args__ = ( + UniqueConstraint("observation_hash", "watch_id", name="_route_observation_watch_uc"), + CheckConstraint("clause_index >= 0", name="ck_routes_clause_index"), + Index("idx_routes_watch", "watch_id"), + Index("idx_routes_observation", "observation_hash"), + ) + + +class Adjudication(Base): + """ + One model call about one routed pair, whatever it answered. + + ``outcome`` is ``evidence`` (a verdict was written to ``evidence``), + ``none`` (the model judged the item not to bear on the claim) or ``failed`` + (a refusal, an API error, or a response that failed validation; the text + is in ``error``). A failed pair is left here and never retried: a retry + that produced a different answer to the same input would break the replay + determinism that is the only way to review a prompt change. + + Unique per ``(observation, watch, prompt_version)``, which is what makes + ``insightweaver adjudicate`` idempotent: run twice, the second run asks + nothing. ``audit_id`` finds the exact request in the local audit log; + ``input_tokens`` and ``output_tokens`` are what the API reported, so the + cost of a run is a sum over this table and not a guess. ``confidence``, + ``satisfies_clause`` and ``rationale`` keep the rest of a validated + verdict, for 'none' verdicts too, since ``evidence`` holds only evidence. + + Added 2026-09-22 for backlog task 029. + """ + + __tablename__ = "adjudications" + + id = Column(Integer, primary_key=True) + observation_hash = Column(String(80), ForeignKey("observations.content_hash"), nullable=False) + watch_id = Column(String(100), ForeignKey("watches.id"), nullable=False) + prompt_version = Column(String(100), nullable=False) + outcome = Column(String(20), nullable=False) + error = Column(Text) + audit_id = Column(String(40)) + input_tokens = Column(Integer, nullable=False, default=0) + output_tokens = Column(Integer, nullable=False, default=0) + # The parts of a validated verdict that `evidence` does not hold: the + # model's confidence in its reading, the clause it named, and the + # rationale for a 'none' verdict as well as for evidence. Null on failure. + confidence = Column(Float) + satisfies_clause = Column(Integer) + rationale = Column(Text) + created_at = Column(DateTime, default=utcnow, nullable=False) + + __table_args__ = ( + UniqueConstraint( + "observation_hash", + "watch_id", + "prompt_version", + name="_adjudication_pair_version_uc", + ), + CheckConstraint( + "outcome IN ('evidence', 'none', 'failed')", name="ck_adjudications_outcome" + ), + CheckConstraint( + "length(trim(prompt_version)) > 0", name="ck_adjudications_prompt_version_present" + ), + Index("idx_adjudications_version", "prompt_version"), + Index("idx_adjudications_watch", "watch_id"), + ) + + +class BriefRun(Base): + """ + One row per brief rendered, so the next brief knows where the last left off. + + ``brief`` defaults its window to the ``as_of`` of the most recent row + delivered before the start of the day it is rendered on, which is what + makes a second run the same morning reproduce the first instead of + reporting "nothing since ten minutes ago". ``rendered_sha`` is the hash of + the bytes printed, kept so a reader can check that a saved brief is the one + this row records. ``--dry-run`` renders without writing here. + + Added 2026-09-22 for backlog task 031. + """ + + __tablename__ = "briefs" + + id = Column(Integer, primary_key=True) + as_of = Column(DateTime, nullable=False) + since = Column(DateTime, nullable=False) + moved = Column(Integer, nullable=False) + quiet = Column(Integer, nullable=False) + rendered_sha = Column(String(80), nullable=False) + created_at = Column(DateTime, default=utcnow, nullable=False) + + __table_args__ = (Index("idx_briefs_as_of", "as_of"),) diff --git a/src/database/models/observations.py b/src/database/models/observations.py new file mode 100644 index 0000000..c8f7c03 --- /dev/null +++ b/src/database/models/observations.py @@ -0,0 +1,193 @@ +""" +Part of the model split of 2026-09-22 (backlog task 030); see ``__init__``. +""" + +from sqlalchemy import ( + DDL, + JSON, + CheckConstraint, + Column, + DateTime, + Float, + ForeignKey, + Index, + Integer, + String, + Text, + UniqueConstraint, + event, +) + +from ...utils import utcnow +from .base import Base, ObservationIsImmutable + + +class Observation(Base): + """ + One thing a source published, keyed by a hash of what it said. + + **The hash is the identity.** There is no surrogate primary key, because a + surrogate key would let the same document be stored twice under two ids and + the duplicate would be invisible. ``content_hash`` is computed by + ``src.sources.observation.observation_hash`` from the fields in + ``OBSERVATION_FIELDS`` and nothing else -- specifically not from + ``observed_at``, not from the source's last-fetch time, and not from + anything else that changes between two fetches of an unchanged document. + That exclusion is the whole invariant, so it is tested directly + (tests/sources/test_observation.py::TestHashIsContentOnly) rather than + inferred from the field list. + + ``observed_at`` is a column precisely *because* it is not in the hash: when + we first saw this content is worth keeping and is not part of what the + content is. It is the one per-fetch value on the row and it lives outside + the payload. + + ``payload`` is the normalized adapter output, verbatim, exactly the values + that were hashed. It is never rewritten -- see + :class:`ObservationIsImmutable` and the BEFORE UPDATE trigger below. + + ``minhash`` is the near-duplicate signature of the item's text, written once + at insert. It is stored rather than recomputed so that a grouping computed + now and a grouping computed after a replay are the same grouping. See + ``src/sources/minhash.py``. + + Added 2026-08-31 for backlog task 014. + """ + + __tablename__ = "observations" + + content_hash = Column(String(80), primary_key=True) + + # Which source published it. The same text from two sources is two + # observations, on purpose: "who said this" is part of what was observed, + # and grouping the pair back together is what the MinHash signature is for. + source_id = Column(Integer, ForeignKey("rss_feeds.id"), nullable=False) + + # The legacy row this observation was written alongside. Nullable because a + # backfill from the pre-rewrite corpus would set it and a future + # observations-only source may not have one. See the module docstring's rule. + article_id = Column(Integer, ForeignKey("articles.id")) + + payload = Column(JSON, nullable=False) + minhash = Column(JSON, nullable=False) + + # A projection of payload["published_date"], written by the same call that + # writes the payload, so that "observations in this window" is an indexed + # query rather than a JSON scan. Immutability is what keeps it honest: it + # cannot drift from the payload because neither can change. + published_date = Column(DateTime) + + observed_at = Column(DateTime, default=utcnow, nullable=False) + + __table_args__ = ( + CheckConstraint("content_hash LIKE 'sha256:%'", name="ck_observations_hash_prefix"), + Index("idx_observations_source", "source_id"), + Index("idx_observations_published", "published_date"), + Index("idx_observations_article", "article_id"), + ) + + +# Immutability, enforced twice on purpose. +# +# 1. The ORM guard below stops a mutation made through a Session, which is how +# application code would do it, and raises a named Python exception. +# 2. The trigger stops an UPDATE issued any other way -- a raw +# `session.execute(text("UPDATE ..."))`, the sqlite3 shell, a future +# migration written in a hurry. A guarantee that only holds for code that +# goes through the ORM is a convention, not a guarantee. +# +# The trigger is attached to the table's after_create, so it exists both when +# `Base.metadata.create_all()` builds a test database and when +# `src.database.migrations.add_observations_and_evidence` creates the real one. +# There is no second copy of the DDL to forget to update. + + +_OBSERVATIONS_IMMUTABLE_TRIGGER = DDL( + "CREATE TRIGGER observations_are_immutable " + "BEFORE UPDATE ON observations " + "BEGIN " + "SELECT RAISE(ABORT, " + "'observations are immutable: the content hash is the identity, so changing " + "a stored row would leave its hash describing content that is no longer there. " + "Insert a new observation instead.'); " + "END" +) + + +event.listen( + Observation.__table__, + "after_create", + _OBSERVATIONS_IMMUTABLE_TRIGGER.execute_if(dialect="sqlite"), +) + + +@event.listens_for(Observation, "before_update", propagate=True) +def _refuse_observation_update(_mapper, _connection, target): + """Refuse an ORM flush that would UPDATE an observation.""" + raise ObservationIsImmutable( + f"refusing to update observation {target.content_hash}: observations are " + f"immutable once written. If the content changed, it is a different " + f"observation with a different hash." + ) + + +class Evidence(Base): + """ + One adjudicated link from an observation to a watch, under a named prompt. + + **``prompt_version`` is on every row, and that is the point of the table.** + Adjudication is the only stochastic tier in the system; the only way to tell + an improvement from a regression is to hold the observations fixed, run a + different prompt version over them, and diff. That requires knowing which + version produced which row, per row -- a version recorded once per run, in a + log, or in a config file is a version that cannot answer "and where did this + row come from" six weeks later. + + The uniqueness constraint ``(observation_hash, watch_id, prompt_version)`` is + what makes replay idempotent: one verdict per observation per watch per + prompt version, so re-running a version either inserts nothing or reveals + that the version is not deterministic. + + ``direction`` is two-valued. There is no 'neutral': an observation that + neither supports nor contradicts a watch produces no row, because a table of + non-evidence is a table nobody can read. + + Evidence is *derived*. It is the one thing here that may be deleted and + rebuilt, and ``insightweaver replay --commit`` does exactly that, scoped to a + single prompt version. + + Added 2026-08-31 for backlog task 014. + """ + + __tablename__ = "evidence" + + id = Column(Integer, primary_key=True) + + observation_hash = Column(String(80), ForeignKey("observations.content_hash"), nullable=False) + watch_id = Column(String(100), ForeignKey("watches.id"), nullable=False) + + direction = Column(String(20), nullable=False) + magnitude = Column(Float, nullable=False) + + prompt_version = Column(String(100), nullable=False) + rationale = Column(Text) + + created_at = Column(DateTime, default=utcnow) + + __table_args__ = ( + UniqueConstraint( + "observation_hash", + "watch_id", + "prompt_version", + name="_evidence_observation_watch_version_uc", + ), + CheckConstraint("direction IN ('supports', 'contradicts')", name="ck_evidence_direction"), + CheckConstraint( + "magnitude >= 0.0 AND magnitude <= 1.0", name="ck_evidence_magnitude_range" + ), + CheckConstraint( + "length(trim(prompt_version)) > 0", name="ck_evidence_prompt_version_present" + ), + Index("idx_evidence_prompt_version", "prompt_version"), + Index("idx_evidence_watch", "watch_id"), + ) diff --git a/src/database/models/sources.py b/src/database/models/sources.py new file mode 100644 index 0000000..71dfd6c --- /dev/null +++ b/src/database/models/sources.py @@ -0,0 +1,101 @@ +""" +Part of the model split of 2026-09-22 (backlog task 030); see ``__init__``. +""" + +from sqlalchemy import ( + JSON, + Boolean, + Column, + DateTime, + Float, + ForeignKey, + Index, + Integer, + String, + Text, + UniqueConstraint, +) +from sqlalchemy.orm import relationship + +from ...utils import utcnow +from .base import Base + + +class RSSFeed(Base): + """RSS feed sources - unchanged""" + + __tablename__ = "rss_feeds" + + id = Column(Integer, primary_key=True) + url = Column(String(500), nullable=False, unique=True) + name = Column(String(200), nullable=False) + category = Column(String(100)) + is_active = Column(Boolean, default=True) + last_fetched = Column(DateTime) + last_error = Column(Text) + error_count = Column(Integer, default=0) + created_at = Column(DateTime, default=utcnow) + updated_at = Column(DateTime, default=utcnow, onupdate=utcnow) + + articles = relationship("Article", back_populates="feed") + + +class Article(Base): + """ + Articles from RSS feeds + Optimized for context engineering - stores raw content and minimal metadata + """ + + __tablename__ = "articles" + + id = Column(Integer, primary_key=True) + feed_id = Column(Integer, ForeignKey("rss_feeds.id")) + guid = Column(String(500), nullable=False) + url = Column(String(500)) + title = Column(String(500)) + description = Column(Text) + content = Column(Text) + published_date = Column(DateTime) + author = Column(String(200)) + categories = Column(JSON) # List of categories/tags from feed + + # Normalized content for context + normalized_content = Column(Text) # Clean text without HTML + word_count = Column(Integer) + language = Column(String(10)) + + # Context engineering fields + entities = Column(JSON) # Extracted entities (people, orgs, locations) + embedding_summary = Column(Text) # AI-generated 2-3 sentence summary + relevance_score = Column(Float) # Simple score: recency + user profile match + last_included_in_synthesis = Column(DateTime) # Track usage in context + + # Priority and deduplication fields + priority_score = Column(Float) # Used for article filtering/sorting + priority_metadata = Column(JSON) # Stores duplicate tracking info + trend_metadata = Column(JSON) # Trend-related metadata + + # Content filtering (user preference based) + filtered = Column(Boolean, default=False) + filter_reason = Column(String(200)) + + # Timestamps + fetched_at = Column(DateTime, default=utcnow) + created_at = Column(DateTime, default=utcnow) + + feed = relationship("RSSFeed", back_populates="articles") + + __table_args__ = ( + UniqueConstraint("feed_id", "guid", name="_feed_guid_uc"), + Index("idx_published_date", "published_date"), + Index("idx_fetched_at", "fetched_at"), + Index("idx_relevance_score", "relevance_score"), # For context selection + Index("idx_filtered", "filtered"), # Quick filtering queries + # Composite indexes for critical query paths + # Both composite indexes were added for briefing-era query paths that + # task 012 deleted (curator.py and content_engine.py). They are kept: + # "recent unfiltered articles" is the shape every tier reads, and + # dropping an index is a separate, measurable decision. + Index("idx_articles_filtered_fetched", "filtered", "fetched_at"), + Index("idx_articles_filtered_published", "filtered", "published_date"), + ) diff --git a/src/database/models/watches.py b/src/database/models/watches.py new file mode 100644 index 0000000..1dc632f --- /dev/null +++ b/src/database/models/watches.py @@ -0,0 +1,159 @@ +""" +Part of the model split of 2026-09-22 (backlog task 030); see ``__init__``. +""" + +from sqlalchemy import ( + DDL, + JSON, + CheckConstraint, + Column, + Date, + DateTime, + Float, + ForeignKey, + Index, + Integer, + String, + Text, + event, +) + +from ...utils import utcnow +from .base import Base, LedgerIsAppendOnly + + +class Watch(Base): + """ + One pre-registered claim, the decision it serves, and what would move it. + + Rows arrive from exactly one place: ``src.position.watches.sync_watches``, + reading the operator's hand-authored file. Nothing else creates one. + Invariant 6 -- the system never authors its own watches -- is a property of + the code paths that exist, so no path exists. Two other writers touch + existing rows and nothing else (since 2026-09-22, backlog task 030): + sync sets and clears ``retired_at``, and ``src.position.ledger.resolve_watch`` + writes the three resolution columns once, at the operator's command. + + **The constraints are the enforcement, not a formality.** Invariant 2 says + every Watch must name a decision; the loader rejects a blank ``so_what``, + and ``ck_watches_so_what_present`` rejects it again at the storage layer, so + a row written by hand through ``sqlite3`` fails the same way a bad YAML file + does. The repository's own history is the argument: 25 unfalsifiable + predictions accumulated in the deleted ledger because a missing field was + tolerated by every layer that could have refused it. + + ``triggers`` is JSON, and structured JSON specifically -- a list of clauses + over terms, entities and source allowlists. Tier 1 compiles it into a + deterministic predicate. The column it replaces, ``predictions. + trigger_condition``, was free text; 33 rows were written against it and none + were ever graded, because nothing downstream could evaluate a sentence. + """ + + __tablename__ = "watches" + + # The operator's own id from the file, not a surrogate. It is the name they + # will type and the name an alert will carry, and a watch that is renamed in + # the file is a different watch. + id = Column(String(100), primary_key=True) + + claim = Column(Text, nullable=False) + belief = Column(Float, nullable=False) + + # so_what, split: the key is what makes invariant 2 machine-checkable, the + # prose is what makes it readable. `decision_key` references a decision in + # the Position file, which is not a table -- Position lives in a private + # repo under git, so this is deliberately not a foreign key. + decision_key = Column(String(100), nullable=False) + so_what = Column(Text, nullable=False) + + triggers = Column(JSON, nullable=False) + expires = Column(Date, nullable=False) + staleness_alert_days = Column(Integer, nullable=False) + + # Lifecycle, added 2026-09-22 (backlog task 030). `retired_at` is set by + # sync when the watch leaves the file and cleared if it returns; the row + # is never deleted, because the belief ledger hangs off it. `resolved_at`, + # `outcome` and `resolution_note` are written once, by the operator, + # through src.position.ledger.resolve_watch, and by nothing else. + retired_at = Column(DateTime) + resolved_at = Column(DateTime) + # A column-level constraint, not a table-level one: SQLite can DROP a + # column that carries its own CHECK and cannot drop one a table CHECK + # names, and the migration's way down drops these four. + outcome = Column( + String(10), + CheckConstraint("outcome IS NULL OR outcome IN ('yes', 'no')", name="ck_watches_outcome"), + ) + resolution_note = Column(Text) + + created_at = Column(DateTime, default=utcnow) + updated_at = Column(DateTime, default=utcnow, onupdate=utcnow) + + __table_args__ = ( + CheckConstraint("length(trim(so_what)) > 0", name="ck_watches_so_what_present"), + CheckConstraint("length(trim(decision_key)) > 0", name="ck_watches_decision_present"), + CheckConstraint("belief >= 0.0 AND belief <= 1.0", name="ck_watches_belief_range"), + CheckConstraint("staleness_alert_days >= 1", name="ck_watches_staleness_min"), + Index("idx_watches_decision_key", "decision_key"), + Index("idx_watches_expires", "expires"), + ) + + +class WatchBelief(Base): + """ + One belief value for one watch, with who set it and when. Append-only. + + ``watches.belief`` is the value at registration; this table is every value + since, including that first one. ``source`` is ``file`` when + ``sync_watches`` wrote it from the watch file and ``principal`` when the + operator wrote it with ``watch believe``. Nothing else writes here, and + nothing updates or deletes: the ORM guards below refuse a flush, and the + triggers refuse an UPDATE or DELETE from anywhere else, the same two-layer + enforcement ``observations`` has. Belief history is the calibration record + the system exists to accumulate, and a row that can be edited is a history + that can be rewritten. + + Added 2026-09-22 for backlog task 030. + """ + + __tablename__ = "watch_beliefs" + + id = Column(Integer, primary_key=True) + watch_id = Column(String(100), ForeignKey("watches.id"), nullable=False) + belief = Column(Float, nullable=False) + source = Column(String(20), nullable=False) + note = Column(Text) + observed_at = Column(DateTime, nullable=False) + + __table_args__ = ( + CheckConstraint("belief >= 0.0 AND belief <= 1.0", name="ck_watch_beliefs_range"), + CheckConstraint("source IN ('file', 'principal')", name="ck_watch_beliefs_source"), + Index("idx_watch_beliefs_watch_time", "watch_id", "observed_at"), + ) + + +_LEDGER_MESSAGE = ( + "watch_beliefs is append-only: belief history is the calibration record, " + "and a row that can be changed is a history that can be rewritten. " + "Insert a new row instead." +) + +for _verb in ("UPDATE", "DELETE"): + event.listen( + WatchBelief.__table__, + "after_create", + DDL( + f"CREATE TRIGGER watch_beliefs_no_{_verb.lower()} BEFORE {_verb} ON watch_beliefs " + f"BEGIN SELECT RAISE(ABORT, '{_LEDGER_MESSAGE}'); END" + ).execute_if(dialect="sqlite"), + ) + + +@event.listens_for(WatchBelief, "before_update", propagate=True) +def _refuse_belief_update(_mapper, _connection, target): + raise LedgerIsAppendOnly(f"refusing to update belief row {target.id}: {_LEDGER_MESSAGE}") + + +@event.listens_for(WatchBelief, "before_delete", propagate=True) +def _refuse_belief_delete(_mapper, _connection, target): + raise LedgerIsAppendOnly(f"refusing to delete belief row {target.id}: {_LEDGER_MESSAGE}") diff --git a/src/evidence/__init__.py b/src/evidence/__init__.py index 83c3b9a..b865ee3 100644 --- a/src/evidence/__init__.py +++ b/src/evidence/__init__.py @@ -1,10 +1,13 @@ """ Evidence: what an adjudication prompt concluded, and the harness that replays it. -Two modules and a hard line between them. ``adjudicator`` is the seam a prompt -version plugs into; ``replay`` rebuilds evidence from observations through that -seam and diffs the result against what is stored. Neither contains an -adjudication prompt -- that is backlog task 016. +``adjudicator`` is the seam a prompt version plugs into; ``replay`` rebuilds +evidence from routed observations through that seam and diffs the result +against what is stored. ``claude_adjudicator`` is the one prompt version that +calls a model (backlog task 029, 2026-09-22), registered here so that +``resolve("claude-v1")`` works without constructing a client; ``adjudicate`` +is the run loop that asks it about every routed pair once and records every +answer. Added 2026-08-31 for backlog task 014. """ @@ -22,6 +25,8 @@ register, resolve, ) +from .claude_adjudicator import PROMPT_VERSION as CLAUDE_PROMPT_VERSION +from .claude_adjudicator import AdjudicationFailed, AdjudicationVerdict, ClaudeAdjudicator from .replay import ( EvidenceRow, NondeterministicReplay, @@ -33,10 +38,16 @@ stored_evidence, ) +register(CLAUDE_PROMPT_VERSION, ClaudeAdjudicator) + __all__ = [ + "CLAUDE_PROMPT_VERSION", "DIRECTIONS", "NULL_PROMPT_VERSION", + "AdjudicationFailed", + "AdjudicationVerdict", "Adjudicator", + "ClaudeAdjudicator", "EvidenceRow", "NondeterministicReplay", "NullAdjudicator", diff --git a/src/evidence/adjudicate.py b/src/evidence/adjudicate.py new file mode 100644 index 0000000..c776baf --- /dev/null +++ b/src/evidence/adjudicate.py @@ -0,0 +1,162 @@ +""" +The adjudication run: every routed pair without an answer, one call each. + +Reads ``routes`` joined to ``observations`` and the watches, minus the pairs +this prompt version has already answered -- a row in ``adjudications``, or an +``evidence`` row committed by ``replay`` for the same version. Writes one +``adjudications`` row per pair asked, whatever the answer, and an ``evidence`` +row when the answer was evidence. Run twice, the second run asks nothing. A +``replay --commit`` records evidence only, so a pair a replay judged not to be +evidence has no row and is asked once more here; that is the one gap between +the two paths, and it costs one call per such pair. + +**Which pairs.** Every routed pair on an open watch. Expiry is Tier 1's gate: +``route`` links only watches live on the day it runs, so a routed pair is one +that was live when it was routed, and adjudication and replay both read +exactly that set with no date-dependent filter of their own (decided +2026-09-22 after review; the two tiers had briefly disagreed). Retired and +resolved watches are skipped by both (task 030): a state, not a date, and +asking the model about a watch the operator has closed would cost money for +nothing. + +**Progress survives interruption.** Each pair's ledger row is committed as +soon as it is written, so a run interrupted at pair forty keeps thirty-nine +answers and the tokens they cost. The pair in flight at the interruption has +no row: its call may already have been billed, the audit log has the request, +and it will be asked again next run. That single re-ask is the one place the +never-retried rule bends, and it bends only under Ctrl-C. + +Added 2026-09-22 for backlog task 029. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field + +from sqlalchemy.orm import Session + +from ..database.models import Adjudication, Evidence, Observation, Route, Watch +from ..position.ledger import open_clause +from .adjudicator import ObservationView +from .claude_adjudicator import ClaudeAdjudicator +from .prompt import build_messages, estimate_tokens + +__all__ = ["AdjudicationRun", "Pair", "dry_run", "pending_pairs", "run"] + + +@dataclass(frozen=True) +class Pair: + view: ObservationView + watch: Watch + + +@dataclass +class AdjudicationRun: + prompt_version: str + asked: int = 0 + evidence: int = 0 + none: int = 0 + failed: int = 0 + input_tokens: int = 0 + output_tokens: int = 0 + failures: list[tuple[str, str, str]] = field(default_factory=list) # (hash, watch, error) + + +def _answered(db: Session, prompt_version: str) -> set[tuple[str, str]]: + """Pairs this version has already answered, by ledger row or by committed evidence.""" + ledger = db.query(Adjudication.observation_hash, Adjudication.watch_id).filter( + Adjudication.prompt_version == prompt_version + ) + committed = db.query(Evidence.observation_hash, Evidence.watch_id).filter( + Evidence.prompt_version == prompt_version + ) + return {(str(h), str(w)) for h, w in ledger.all()} | { + (str(h), str(w)) for h, w in committed.all() + } + + +def pending_pairs(db: Session, prompt_version: str, *, limit: int | None = None) -> list[Pair]: + """Routed pairs with no answer under this version, in a fixed order.""" + if limit is not None and limit < 1: + raise ValueError(f"limit must be at least 1, got {limit}") + done = _answered(db, prompt_version) + watches = {str(w.id): w for w in db.query(Watch).filter(open_clause()).all()} + rows = ( + db.query(Route.observation_hash, Route.watch_id, Observation.payload) + .join(Observation, Observation.content_hash == Route.observation_hash) + .order_by(Route.observation_hash, Route.watch_id) + .all() + ) + pairs = [] + for content_hash, watch_id, payload in rows: + if str(watch_id) not in watches or (str(content_hash), str(watch_id)) in done: + continue + view = ObservationView(content_hash=str(content_hash), payload=dict(payload)) + pairs.append(Pair(view=view, watch=watches[str(watch_id)])) + if limit is not None and len(pairs) >= limit: + break + return pairs + + +def run( + db: Session, adjudicator: ClaudeAdjudicator, *, limit: int | None = None +) -> AdjudicationRun: + """ + Ask the model about every pending pair and record every outcome. + + The client is built before the first pair, so a missing key raises here + with nothing written. Each pair is committed as it is answered. + """ + adjudicator.client() + result = AdjudicationRun(prompt_version=adjudicator.prompt_version) + for pair in pending_pairs(db, adjudicator.prompt_version, limit=limit): + judgement = adjudicator.judge(pair.view, pair.watch) + verdict = judgement.verdict + result.asked += 1 + result.input_tokens += judgement.input_tokens + result.output_tokens += judgement.output_tokens + db.add( + Adjudication( + observation_hash=pair.view.content_hash, + watch_id=judgement.watch_id, + prompt_version=adjudicator.prompt_version, + outcome=judgement.outcome, + error=judgement.error, + audit_id=judgement.audit_id, + input_tokens=judgement.input_tokens, + output_tokens=judgement.output_tokens, + confidence=verdict.confidence if verdict else None, + satisfies_clause=verdict.satisfies_clause if verdict else None, + rationale=verdict.rationale if verdict else None, + ) + ) + if judgement.error is not None: + result.failed += 1 + result.failures.append((pair.view.content_hash, judgement.watch_id, judgement.error)) + elif verdict is not None and verdict.is_evidence: + result.evidence += 1 + db.add( + Evidence( + observation_hash=pair.view.content_hash, + watch_id=judgement.watch_id, + direction=verdict.direction, + magnitude=verdict.magnitude, + prompt_version=adjudicator.prompt_version, + rationale=verdict.rationale, + ) + ) + else: + result.none += 1 + db.commit() + return result + + +def dry_run( + db: Session, prompt_version: str, *, limit: int = 3 +) -> list[tuple[Pair, str, str, int]]: + """The exact text the first ``limit`` pending pairs would send, with an estimate.""" + out = [] + for pair in pending_pairs(db, prompt_version, limit=limit): + system, user = build_messages(pair.view, pair.watch) + out.append((pair, system, user, estimate_tokens(system, user))) + return out diff --git a/src/evidence/adjudicator.py b/src/evidence/adjudicator.py index 54feeb6..56f4650 100644 --- a/src/evidence/adjudicator.py +++ b/src/evidence/adjudicator.py @@ -4,8 +4,9 @@ Adjudication is the one stochastic tier in this system. Everything either side of it is deterministic and unit-testable; the tier itself can only be reviewed by holding its inputs fixed and looking at what a different prompt does to its -outputs. This module is the shape of that seam. **It does not contain the -adjudication prompt** -- that is backlog task 016, and deliberately not here. +outputs. This module is the shape of that seam. The prompt that plugs into it +is :mod:`src.evidence.claude_adjudicator` (backlog task 029, 2026-09-22, which +superseded task 016); this module still knows nothing about it. Three properties are enforced rather than documented: @@ -23,13 +24,13 @@ CHECK constraint several layers later, though the CHECK constraint is there too. -**On the shipped adjudicator.** :class:`NullAdjudicator` returns no verdicts. -It exists so the harness is runnable and testable before task 016 supplies -something real, and it is honest: an adjudicator that guessed a direction from a -keyword match would put fabricated judgements in a table whose entire purpose is -to make judgements reviewable. Registering a real one is -:func:`register`; running an unregistered one for a one-off is -``--adjudicator module:attr`` on the CLI. +**On the null adjudicator.** :class:`NullAdjudicator` returns no verdicts. It +exists so the harness is runnable and testable without the stochastic part, +and it is honest: an adjudicator that guessed a direction from a keyword match +would put fabricated judgements in a table whose entire purpose is to make +judgements reviewable. The model version registers itself through +:func:`register` in the package's ``__init__``; running an unregistered one for +a one-off is ``--adjudicator module:attr`` on the CLI. Added 2026-08-31 for backlog task 014. """ diff --git a/src/evidence/claude_adjudicator.py b/src/evidence/claude_adjudicator.py new file mode 100644 index 0000000..c9635fc --- /dev/null +++ b/src/evidence/claude_adjudicator.py @@ -0,0 +1,292 @@ +""" +The one model adjudicator: one structured call per routed pair, nothing retried. + +This is the single stochastic component in the system (invariant 4), and the +only module that constructs a :class:`~src.llm.claude_client.ClaudeClient`, +asserted against the tree by tests/evidence/test_claude_adjudicator.py. It +judges one observation against one pre-registered claim and returns a verdict +the schema below validates, or a recorded failure. It never returns a guess. + +**Why the prompt is fingerprinted.** Every evidence row carries +``prompt_version``, and replay compares versions. A prompt edited without a +version bump would label two different judges with one name, which is the +mislabelled-corpus failure task 014 was built to prevent. So the prompt text, +the effort, the caps and the response schema are hashed into +:data:`PROMPT_FINGERPRINT`, and a test pins that hash to +:data:`PROMPT_VERSION`; change any of them and the test says to bump the +version. + +**Why failures are recorded and not retried.** A retry that produces a +different answer to the same input breaks replay determinism, the only +mechanism for reviewing a prompt change. A refusal, an API error, a reply cut +off at ``max_tokens``, or a reply that fails validation becomes an +``adjudications`` row with ``outcome='failed'`` and the error text, with the +audit id and the tokens the failed call still cost. The SDK's own transport +retries (a 429 or a 5xx answered by an identical resend) are below this rule +and are noted in ``src/llm/claude_client.py``. + +**What is not a failure of the model.** A missing keychain entry, or any +other error constructing the client, is raised before any pair is asked. A +request the API rejects outright (a 400 for a malformed schema, a 401, a 404 +for a retired model) and an API that is unavailable (a connection error, a +timeout, a 429, a 5xx) are raised from the pair they hit, with that pair left +pending. None of these is an answer about the pair, and recording any of them +as a verdict would burn the pending backlog into permanent "failed" rows +without a single answer having been given -- an outage would do it to every +pair at once. Only an answered call can fail a pair: a refusal, a reply cut +off at ``max_tokens``, an invalid reply, or a request the API found too large. + +**Why the schema uses sentinels.** The task file wrote ``direction`` and +``satisfies_clause`` as nullable. The API's structured-output grammar takes a +flat enum and an integer with no union, so ``direction`` is three-valued with +``"none"`` and ``satisfies_clause`` is ``-1`` for no clause; the pydantic +validator enforces the same rule the nullable form would have (evidence must +carry a direction). Recorded 2026-09-22. + +**What the model sees.** The watch's claim, the decision it serves, its +trigger clauses with indices, and the observation's source, date, title and +text, the text capped at :data:`~src.evidence.prompt.TEXT_CAP` characters with +the cap stated in the message so the audit log records that it applied. +Nothing else: no other watches, no Position, no belief. + +Added 2026-09-22 for backlog task 029. +""" + +from __future__ import annotations + +import hashlib +import json +from collections.abc import Sequence +from dataclasses import dataclass +from typing import Any, Literal + +from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator + +from ..llm.claude_client import ClaudeClient, ModelCallFailed +from .adjudicator import ObservationView, Verdict +from .prompt import EFFORT, MAX_TOKENS, SYSTEM_PROMPT, TEXT_CAP, USER_TEMPLATE, build_messages + +__all__ = [ + "PROMPT_FINGERPRINT", + "PROMPT_VERSION", + "SCHEMA", + "AdjudicationFailed", + "AdjudicationVerdict", + "ClaudeAdjudicator", + "Judgement", + "api_schema", +] + +PROMPT_VERSION = "claude-v1" + +# JSON Schema keywords the structured-output grammar does not accept. The +# ranges they expressed are enforced by pydantic on receipt and stated in the +# field descriptions the model reads. (2026-09-22, backlog task 029.) +_UNSUPPORTED_KEYS = frozenset( + {"minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "minLength", "title"} +) + + +class AdjudicationVerdict(BaseModel): + """ + The structured answer. Validated on receipt; a bad one is a failure, not a + default. + + ``magnitude`` is the strength of bearing on the claim, not a probability + that the claim is true. ``confidence`` is the model's confidence in its own + reading of the text. Both are recorded on the ``adjudications`` row, with + ``satisfies_clause`` and the rationale; neither moves belief. + """ + + model_config = ConfigDict(extra="forbid") + + is_evidence: bool = Field(description="Whether the item bears on the claim at all.") + direction: Literal["supports", "contradicts", "none"] = Field( + description='"supports" or "contradicts" when is_evidence is true; "none" otherwise.' + ) + magnitude: float = Field( + ge=0.0, le=1.0, description="Strength of bearing, 0 to 1. Not a probability." + ) + satisfies_clause: int = Field( + ge=-1, description="Index of the trigger clause the item satisfies, or -1." + ) + confidence: float = Field( + ge=0.0, le=1.0, description="Confidence in your reading of the text, 0 to 1." + ) + rationale: str = Field( + min_length=1, description="One or two sentences quoting the words the verdict rests on." + ) + + @model_validator(mode="after") + def _evidence_has_a_direction(self) -> AdjudicationVerdict: + if self.is_evidence and self.direction == "none": + raise ValueError("a verdict that is evidence must carry a direction") + if not self.is_evidence and self.direction != "none": + raise ValueError("a verdict that is not evidence carries no direction") + return self + + +def api_schema(model: type[BaseModel]) -> dict[str, Any]: + """The model's JSON schema with the keywords the API rejects removed.""" + + def strip(node: Any) -> Any: + if isinstance(node, dict): + return {k: strip(v) for k, v in node.items() if k not in _UNSUPPORTED_KEYS} + if isinstance(node, list): + return [strip(item) for item in node] + return node + + schema = strip(model.model_json_schema()) + schema["additionalProperties"] = False + return schema + + +SCHEMA: dict[str, Any] = api_schema(AdjudicationVerdict) + + +def _fingerprint() -> str: + """ + The version's identity: what is sent (prompt, effort, caps, the schema the + API sees) and what is accepted back (the model's own schema, bounds + included, which pydantic enforces on receipt). The model id is not part of + it -- the audit log records the model per call, and a version names the + judge's instructions, not the engine that ran them. + """ + material = json.dumps( + { + "system": SYSTEM_PROMPT, + "user": USER_TEMPLATE, + "effort": EFFORT, + "schema": SCHEMA, + "accepts": AdjudicationVerdict.model_json_schema(), + "text_cap": TEXT_CAP, + "max_tokens": MAX_TOKENS, + }, + sort_keys=True, + ) + return hashlib.sha256(material.encode("utf-8")).hexdigest() + + +PROMPT_FINGERPRINT = _fingerprint() + + +class AdjudicationFailed(RuntimeError): + """Raised by the replay-harness path when a pair cannot be judged.""" + + +@dataclass(frozen=True) +class Judgement: + """What one call produced: a verdict, or the error that stands in for one.""" + + watch_id: str + verdict: AdjudicationVerdict | None + error: str | None + audit_id: str | None + input_tokens: int + output_tokens: int + + @property + def outcome(self) -> str: + if self.error is not None: + return "failed" + assert self.verdict is not None + return "evidence" if self.verdict.is_evidence else "none" + + +class ClaudeAdjudicator: + """ + Prompt version ``claude-v1``. + + The client is built on first use, not at construction, so registering the + adjudicator, listing versions and ``--dry-run`` never touch the keychain. + """ + + prompt_version = PROMPT_VERSION + + def __init__(self, client: ClaudeClient | None = None) -> None: + self._client = client + + def client(self) -> ClaudeClient: + """The client, built on first use. A missing key raises here, loudly.""" + if self._client is None: + self._client = ClaudeClient("triage") + return self._client + + def judge(self, observation: ObservationView, watch: Any) -> Judgement: + """ + One call, one recorded outcome. + + Model-side failures (refusal, API error, truncation, an invalid reply) + come back as a :class:`Judgement` with ``error`` set and the call's + audit id and cost kept. A client that cannot be built raises before + any call is made. + """ + client = self.client() + system, user = build_messages(observation, watch) + watch_id = str(watch.id) + try: + response = client.analyze( + system, user, effort=EFFORT, max_tokens=MAX_TOKENS, output_schema=SCHEMA + ) + except ModelCallFailed as exc: + if exc.outcome != "answered": + # Rejected (a bad schema, a bad key, a retired model) or + # unavailable (an outage, a rate limit, a timeout): neither is + # an answer about this pair. Recording it per pair would mark + # every pending pair failed with no verdict ever given, so the + # run stops here with the pair left pending. + raise + message = str(exc) + if exc.stop_reason == "max_tokens": + message = f"reply cut off at max_tokens={MAX_TOKENS} (no text block): {message}" + return Judgement( + watch_id, None, message, exc.audit_id, exc.input_tokens, exc.output_tokens + ) + cost = (response.audit_id, response.input_tokens, response.output_tokens) + if response.stop_reason == "max_tokens": + return Judgement(watch_id, None, f"reply cut off at max_tokens={MAX_TOKENS}", *cost) + try: + verdict = AdjudicationVerdict.model_validate_json(response.text) + except ValidationError as exc: + return Judgement( + watch_id, None, f"invalid verdict: {exc.error_count()} error(s): {exc}", *cost + ) + clause_count = len(watch.triggers or ()) + if verdict.satisfies_clause >= clause_count: + return Judgement( + watch_id, + None, + f"invalid verdict: satisfies_clause {verdict.satisfies_clause} names a clause " + f"the watch does not have ({clause_count} clause(s))", + *cost, + ) + return Judgement(watch_id, verdict, None, *cost) + + def adjudicate(self, observation: ObservationView, watches: Sequence[Any]) -> list[Verdict]: + """ + The replay-harness protocol: verdicts for the watches given. + + A failed call raises :class:`AdjudicationFailed` here rather than being + swallowed, because replay has no ledger to record it in and a silently + missing row would read as "not evidence". One failure ends the replay; + ``insightweaver adjudicate`` is the path that records and continues. + """ + verdicts = [] + for watch in watches: + judgement = self.judge(observation, watch) + if judgement.error is not None: + raise AdjudicationFailed( + f"adjudication of {observation.content_hash} against {watch.id} failed: " + f"{judgement.error}" + ) + assert judgement.verdict is not None + if judgement.verdict.is_evidence: + verdicts.append( + Verdict( + watch_id=str(watch.id), + direction=judgement.verdict.direction, + magnitude=judgement.verdict.magnitude, + rationale=judgement.verdict.rationale, + ) + ) + return verdicts diff --git a/src/evidence/prompt.py b/src/evidence/prompt.py new file mode 100644 index 0000000..07afc4a --- /dev/null +++ b/src/evidence/prompt.py @@ -0,0 +1,110 @@ +""" +The adjudication prompt: text, effort, caps, and the message builder. + +Kept apart from the adjudicator so the prompt can be read as prose and so the +adjudicator module stays inside the repository's size rule. Everything here is +part of the prompt version's identity: :mod:`src.evidence.claude_adjudicator` +hashes these constants together with the response schema into the fingerprint +a test pins to ``PROMPT_VERSION``. + +Added 2026-09-22 for backlog task 029. +""" + +from __future__ import annotations + +from typing import Any + +from .adjudicator import ObservationView + +__all__ = [ + "EFFORT", + "MAX_TOKENS", + "SYSTEM_PROMPT", + "TEXT_CAP", + "USER_TEMPLATE", + "build_messages", + "estimate_tokens", +] + +# Reasoning depth for one judgement-shaped call. Part of the version identity: +# a different effort is a different judge. (2026-09-22, backlog task 029.) +EFFORT = "medium" + +# Characters of observation text sent. Longer documents are truncated and the +# user message says so, which puts the fact in the audit log beside the text. +# (2026-09-22, backlog task 029.) +TEXT_CAP = 6000 + +# max_tokens caps thinking and the answer together, and the model thinks by +# default (see src/llm/claude_client.py). A low ceiling ends a call with no +# text block, which the adjudicator records as a failure. 16000 is the SDK +# guidance for a non-streaming call; what a call actually costs is what the +# API reports, not this ceiling. (2026-09-22, backlog task 029.) +MAX_TOKENS = 16000 + +SYSTEM_PROMPT = """You judge whether one published item bears on one pre-registered claim. You are not asked whether the claim is true, and you do not recommend anything. + +Rules, in order of precedence: + +1. Judge only what the text says. Do not infer what an author probably meant, what will likely follow, or what a reasonable reader would conclude beyond the words. +2. A claim the text does not address is not evidence. Most items are not evidence for most claims; say so. +3. When two readings are possible, take the weaker one: not evidence over evidence, a smaller magnitude over a larger one. +4. Direction is "supports" when what the text reports, taken at face value, would make the claim more likely to be true; "contradicts" when less likely; "none" when the item is not evidence. Evidence always has a direction; a non-evidence verdict always has direction "none". +5. Magnitude is the strength of bearing, from 0 (none) to 1 (the text directly reports the claim's resolution). It is not a probability that the claim is true. Confidence is your confidence in your own reading of the text. +6. If the item matches one of the claim's trigger clauses, name the clause index in satisfies_clause; otherwise -1. +7. The rationale is one or two sentences that quote or closely paraphrase the words the verdict rests on. No emotional language, no urgency, no advice. + +Answer with the JSON object the schema describes and nothing else.""" + +USER_TEMPLATE = """CLAIM (watch {watch_id}): +{claim} + +THE DECISION THIS CLAIM SERVES ({decision_key}), as the operator recorded it: +{so_what} + +TRIGGER CLAUSES (index: clause): +{triggers} + +ITEM +source: {source} +published: {published} +title: {title} +text ({text_note}): +{text}""" + + +def _clauses(triggers: Any) -> str: + lines = [] + for index, clause in enumerate(triggers or ()): + parts = [f"{key}: {', '.join(str(v) for v in values)}" for key, values in clause.items()] + lines.append(f" {index}: " + "; ".join(parts)) + return "\n".join(lines) or " (none)" + + +def build_messages(observation: ObservationView, watch: Any) -> tuple[str, str]: + """The exact system and user text for one pair. Pure; used by --dry-run.""" + text = observation.text + if len(text) > TEXT_CAP: + note = f"{len(text)} characters, truncated to {TEXT_CAP}" + text = text[:TEXT_CAP] + else: + note = f"{len(text)} characters" + payload = observation.payload + user = USER_TEMPLATE.format( + watch_id=watch.id, + claim=watch.claim, + decision_key=watch.decision_key, + so_what=watch.so_what, + triggers=_clauses(watch.triggers), + source=payload.get("source_url") or "(unknown source)", + published=payload.get("published_date") or "(undated)", + title=observation.title or "(untitled)", + text_note=note, + text=text or "(no text)", + ) + return SYSTEM_PROMPT, user + + +def estimate_tokens(system: str, user: str) -> int: + """A character-count estimate, labelled as such wherever it is printed.""" + return (len(system) + len(user)) // 4 diff --git a/src/evidence/replay.py b/src/evidence/replay.py index 4b8f88d..c56736a 100644 --- a/src/evidence/replay.py +++ b/src/evidence/replay.py @@ -35,7 +35,8 @@ from sqlalchemy.orm import Session -from ..database.models import Evidence, Observation, Watch +from ..database.models import Evidence, Observation, Route, Watch +from ..position.ledger import open_clause from .adjudicator import Adjudicator, ObservationView logger = logging.getLogger(__name__) @@ -108,23 +109,45 @@ def rebuild( limit: int | None = None, ) -> list[EvidenceRow]: """ - Run ``adjudicator`` over the stored observations and return what it produced. - - Reads observations and watches. Writes nothing, ever -- committing is + Run ``adjudicator`` over the routed pairs and return what it produced. + + Reads observations, watches and ``routes``: the adjudicator sees, per + observation, only the watches Tier 1 routed it to, which is exactly the + pair set ``insightweaver adjudicate`` asks about (changed 2026-09-22, + backlog task 029; before that every observation was judged against every + watch). Retired and resolved watches are skipped, as ``adjudicate`` skips + them; expired ones are not, because expiry is routing's gate and a + date-dependent filter here would make a replay depend on the day it ran + (task 030; the rule is stated in ``src/position/ledger.py``). ``limit`` + counts routed observations, in hash order, so a bounded replay of a model + version judges at least one pair. Writes nothing, ever -- committing is :func:`commit`, and keeping them separate is what makes a diff safe to run against a corpus you care about. """ - watches = db.query(Watch).order_by(Watch.id).all() - query = db.query(Observation.content_hash, Observation.payload).order_by( - Observation.content_hash + watches = {str(w.id): w for w in db.query(Watch).filter(open_clause()).order_by(Watch.id).all()} + routed: dict[str, list[str]] = {} + for content_hash, watch_id in ( + db.query(Route.observation_hash, Route.watch_id) + .order_by(Route.observation_hash, Route.watch_id) + .all() + ): + routed.setdefault(str(content_hash), []).append(str(watch_id)) + + query = ( + db.query(Observation.content_hash, Observation.payload) + .filter(Observation.content_hash.in_(list(routed))) + .order_by(Observation.content_hash) ) if limit is not None: query = query.limit(limit) rows: list[EvidenceRow] = [] for content_hash, payload in query.all(): + routed_watches = [watches[w] for w in routed.get(content_hash, ()) if w in watches] + if not routed_watches: + continue # every route on this observation is to a retired or resolved watch view = ObservationView(content_hash=content_hash, payload=dict(payload or {})) - for verdict in adjudicator.adjudicate(view, watches): + for verdict in adjudicator.adjudicate(view, routed_watches): rows.append( EvidenceRow( observation_hash=content_hash, @@ -137,19 +160,27 @@ def rebuild( return sorted(rows) -def stored_evidence(db: Session, prompt_version: str) -> list[EvidenceRow]: - """The evidence already stored for one prompt version, in the same order.""" - rows = ( - db.query( - Evidence.observation_hash, - Evidence.watch_id, - Evidence.direction, - Evidence.magnitude, - Evidence.rationale, - ) - .filter(Evidence.prompt_version == prompt_version) - .all() - ) +def stored_evidence( + db: Session, prompt_version: str, *, open_only: bool = True +) -> list[EvidenceRow]: + """ + The evidence already stored for one prompt version, in the same order. + + ``open_only`` (the default since backlog task 030) restricts the rows to + watches that are neither retired nor resolved, which is the set a replay + judges; without it a replay would read a closed watch's rows as removed + and ``commit`` would delete them. + """ + query = db.query( + Evidence.observation_hash, + Evidence.watch_id, + Evidence.direction, + Evidence.magnitude, + Evidence.rationale, + ).filter(Evidence.prompt_version == prompt_version) + if open_only: + query = query.join(Watch, Watch.id == Evidence.watch_id).filter(open_clause()) + rows = query.all() return sorted(EvidenceRow(row[0], row[1], row[2], float(row[3]), row[4] or "") for row in rows) @@ -191,9 +222,11 @@ def commit( nothing here can touch one. Refuses, before writing anything, if a key exists for this version with a - different verdict. See :class:`NondeterministicReplay`. + different verdict. See :class:`NondeterministicReplay`. Rows belonging to + retired or resolved watches are outside the comparison and are never + deleted here: the replay did not judge them (task 030). """ - current = stored_evidence(db, prompt_version) + current = stored_evidence(db, prompt_version, open_only=True) against_self = diff(replayed, current) if against_self.changed: @@ -249,6 +282,7 @@ def format_diff( baseline_version: str, observations: int, watches: int, + pairs: int | None = None, ) -> str: """ The diff as text, deterministic to the byte. @@ -259,7 +293,8 @@ def format_diff( """ lines = [ f"replay: prompt-version={prompt_version} against={baseline_version}", - f"corpus: {observations} observation(s), {watches} watch(es)", + f"corpus: {observations} observation(s), {watches} open watch(es)" + + (f", {pairs} routed pair(s)" if pairs is not None else ""), ( f"diff: {result.counts['added']} added, " f"{result.counts['removed']} removed, " diff --git a/src/feed_manager.py b/src/feed_manager.py deleted file mode 100644 index ee567e7..0000000 --- a/src/feed_manager.py +++ /dev/null @@ -1,153 +0,0 @@ -""" -Feed Management System for InsightWeaver -Handles loading, updating, and managing RSS feeds from configuration -Uses tag-based feed matching to user profiles -""" - -import logging - -from src.config.feed_matcher import FeedMatcher -from src.database.connection import get_db -from src.database.models import RSSFeed -from src.utils.profile_loader import UserProfile, get_user_profile - -logger = logging.getLogger(__name__) - - -class FeedManager: - """Manages RSS feed configuration and database operations with modular feed matching""" - - def __init__(self, user_profile: UserProfile | None = None): - """ - Initialize feed manager with user profile for personalized feed selection - - Args: - user_profile: UserProfile instance (defaults to global profile) - """ - self.user_profile = user_profile or get_user_profile() - self.feed_matcher = FeedMatcher() - self.configured_feeds = self.feed_matcher.match_feeds_to_profile(self.user_profile) - - def load_feeds_to_database(self) -> tuple[int, int, int]: - """ - Load all configured feeds into the database - Returns: (added_count, updated_count, total_count) - """ - added_count = 0 - updated_count = 0 - - with get_db() as db: - for feed_config in self.configured_feeds: - existing_feed = db.query(RSSFeed).filter(RSSFeed.url == feed_config["url"]).first() - - if existing_feed: - # Update existing feed metadata - existing_feed.name = feed_config["name"] - existing_feed.category = feed_config["category"] - existing_feed.is_active = True - updated_count += 1 - logger.debug(f"Updated feed: {feed_config['name']}") - else: - # Create new feed - new_feed = RSSFeed( - name=feed_config["name"], - url=feed_config["url"], - category=feed_config["category"], - is_active=True, - ) - db.add(new_feed) - added_count += 1 - logger.debug(f"Added feed: {feed_config['name']}") - - total_count = db.query(RSSFeed).filter(RSSFeed.is_active.is_(True)).count() - - logger.info( - f"Feed loading complete: {added_count} added, {updated_count} updated, {total_count} total active" - ) - return added_count, updated_count, total_count - - def get_active_feeds(self) -> list[RSSFeed]: - """Get all active feeds from database""" - with get_db() as db: - return db.query(RSSFeed).filter(RSSFeed.is_active.is_(True)).all() - - def deactivate_failed_feeds(self, error_threshold: int = 5) -> int: - """ - Deactivate feeds that have exceeded error threshold - Returns: number of feeds deactivated - """ - deactivated_count = 0 - - with get_db() as db: - failed_feeds = ( - db.query(RSSFeed) - .filter(RSSFeed.error_count >= error_threshold, RSSFeed.is_active.is_(True)) - .all() - ) - - for feed in failed_feeds: - feed.is_active = False - deactivated_count += 1 - logger.warning( - f"Deactivated feed due to errors: {feed.name} ({feed.error_count} errors)" - ) - - return deactivated_count - - def get_feed_statistics(self) -> dict: - """Get statistics about feeds in the database and matcher""" - with get_db() as db: - total_feeds = db.query(RSSFeed).count() - active_feeds = db.query(RSSFeed).filter(RSSFeed.is_active.is_(True)).count() - failed_feeds = db.query(RSSFeed).filter(RSSFeed.error_count > 0).count() - - # Get category breakdown - categories = {} - for feed in db.query(RSSFeed).filter(RSSFeed.is_active.is_(True)).all(): - category = feed.category or "uncategorized" - categories[category] = categories.get(category, 0) + 1 - - # Get matcher statistics - matcher_stats = self.feed_matcher.get_feed_statistics() - - return { - "database": { - "total_feeds": total_feeds, - "active_feeds": active_feeds, - "inactive_feeds": total_feeds - active_feeds, - "feeds_with_errors": failed_feeds, - "categories": categories, - }, - "configured": { - "matched_to_user": len(self.configured_feeds), - "total_available": matcher_stats["total_feeds"], - "by_scope": matcher_stats["by_scope"], - "by_domain": matcher_stats["by_domain"], - }, - } - - def reset_error_counts(self) -> int: - """Reset error counts for all feeds (useful for troubleshooting)""" - reset_count = 0 - - with get_db() as db: - feeds_with_errors = db.query(RSSFeed).filter(RSSFeed.error_count > 0).all() - - for feed in feeds_with_errors: - feed.error_count = 0 - feed.last_error = None - reset_count += 1 - - logger.info(f"Reset error counts for {reset_count} feeds") - return reset_count - - -def setup_feeds(): - """Initialize feeds in database from configuration""" - logger.info("Setting up RSS feeds from configuration...") - - feed_manager = FeedManager() - added, updated, total = feed_manager.load_feeds_to_database() - - logger.info(f"Feed setup complete: {total} active feeds ready for processing") - return feed_manager diff --git a/src/llm/__init__.py b/src/llm/__init__.py index d692158..a8f10e9 100644 --- a/src/llm/__init__.py +++ b/src/llm/__init__.py @@ -1,12 +1,23 @@ """ -The Claude API boundary. +LLM access. One client, one audited send path. -One client, one response parser. Ported out of the deleted ``src/context/`` -package by backlog task 012 for Tier 2 adjudication; the synthesis product that -used to call it is gone, the call path is not. +``parse_claude_json`` survives from the briefing product because a fenced-JSON +reply is a property of the API, not of the product that was reading it. Note +that it returns ``{}`` on a parse failure: that is a silent default, and Tier 2 +adjudication (backlog task 016) must not use it -- a response that fails +validation is recorded as a failed adjudication, never coerced. Noted +2026-09-22 (task 026). """ from ._json import parse_claude_json -from .claude_client import ClaudeClient +from .audit import record_error, record_request, record_response +from .claude_client import ClaudeClient, ModelResponse -__all__ = ["ClaudeClient", "parse_claude_json"] +__all__ = [ + "ClaudeClient", + "ModelResponse", + "parse_claude_json", + "record_error", + "record_request", + "record_response", +] diff --git a/src/llm/audit.py b/src/llm/audit.py new file mode 100644 index 0000000..69979b1 --- /dev/null +++ b/src/llm/audit.py @@ -0,0 +1,97 @@ +""" +The local audit log of everything that leaves this machine for a model. + +One rule: **a request is written here before it is sent, and there is no way to +send one without writing it.** :class:`~src.llm.claude_client.ClaudeClient` is +the only module that constructs a model request, and its send path calls +:func:`record_request` first. The operator can therefore answer "what left my +machine, when, and what came back" by reading a file, without trusting the +code that sent it. + +Format: JSON lines under ``settings.llm_audit_dir``, one file per UTC day. +Three event kinds share an ``id``: + +* ``request`` -- the full request body as sent (model, system, messages, + ``output_config``, ``max_tokens``), plus a SHA-256 of its canonical JSON so + two runs can be compared without diffing prose. +* ``response`` -- the usage block, stop reason and model the API reported. Not + the response text: that is the caller's to store, and the log is about what + was *sent*. +* ``error`` -- the exception, when the send failed after the request was + written. A request with no response and no error line is one that was + written while the process died; that is visible, which is the point. + +The log is not a cache and not a replay input. Evidence replay reads +``observations``; this file is for the operator's eyes. + +Added 2026-09-22 for backlog task 026 (Phase 0 of ``docs/PLAN.md``). +""" + +from __future__ import annotations + +import hashlib +import json +import secrets +from datetime import UTC, datetime +from pathlib import Path +from typing import Any + +from ..config.settings import settings + +__all__ = ["record_error", "record_request", "record_response"] + + +def _now() -> datetime: + return datetime.now(UTC) + + +def _path(when: datetime) -> Path: + directory = Path(settings.llm_audit_dir) + directory.mkdir(parents=True, exist_ok=True) + return directory / f"{when.date().isoformat()}.jsonl" + + +def _append(event: dict[str, Any]) -> None: + when = _now() + event = {"at": when.isoformat(timespec="seconds"), **event} + with _path(when).open("a", encoding="utf-8") as handle: + handle.write(json.dumps(event, sort_keys=True, default=str) + "\n") + handle.flush() + + +def _canonical(request: dict[str, Any]) -> str: + return json.dumps(request, sort_keys=True, separators=(",", ":"), default=str) + + +def record_request(role: str, request: dict[str, Any]) -> str: + """Write the request body as it will be sent. Returns the entry id.""" + entry_id = secrets.token_hex(8) + body = _canonical(request) + _append( + { + "id": entry_id, + "event": "request", + "role": role, + "payload_sha256": hashlib.sha256(body.encode("utf-8")).hexdigest(), + "request": request, + } + ) + return entry_id + + +def record_response(entry_id: str, *, model: str, stop_reason: str | None, usage: dict) -> None: + """Write what the API reported about the request: usage and stop reason.""" + _append( + { + "id": entry_id, + "event": "response", + "model": model, + "stop_reason": stop_reason, + "usage": usage, + } + ) + + +def record_error(entry_id: str, error: BaseException) -> None: + """Write that the send failed. The request line above it still stands.""" + _append({"id": entry_id, "event": "error", "error": f"{type(error).__name__}: {error}"}) diff --git a/src/llm/claude_client.py b/src/llm/claude_client.py index 7ab03ae..fa6f1c5 100644 --- a/src/llm/claude_client.py +++ b/src/llm/claude_client.py @@ -1,22 +1,141 @@ """ -Minimal Claude API client. +Minimal Claude API client: the one place a model request is constructed. Moved here from ``src/context/`` by backlog task 012 for Tier 2 adjudication. -The synthesis product that used to call it is deleted; this file is not, -because it encodes two outages that cost live runs and that a rewrite from a -blank file would reintroduce -- see :data:`DEFAULT_MODEL` and -:func:`_response_text` below. +Rewritten 2026-09-22 by task 026 (Phase 0 of ``docs/PLAN.md``) with three +changes and two outages kept, made synchronous by task 029 the same day, and +given a failure classification by 029's verification follow-up. + +**Changes.** + +1. **Every request is audited before it is sent** (:mod:`src.llm.audit`), and + the usage the API reports is audited after. There is no argument that turns + this off. The repository had no token accounting at all before this; the + cost claims in the monitoring plan were unfalsifiable. +2. **The key comes from the OS keychain** (:mod:`src.config.credentials`), read + when the client is constructed, never at import. A missing key is + :class:`~src.config.credentials.MissingCredential`, raised where the request + would have been built, with the command that fixes it. +3. **The model is chosen by role, not at the call site.** ``role="triage"`` + reads ``settings.llm_triage_model``; ``role="synthesis"`` reads + ``settings.llm_synthesis_model``. Decided 2026-09-22: Sonnet 5 adjudicates, + Opus 5 writes. ``effort`` is the ``output_config`` named parameter, and a + structured-output schema goes beside it as ``output_config.format`` -- a + request parameter, not a parsing convention. + +**Failures are classified, because the caller's right response differs.** +:class:`ModelCallFailed.outcome` is one of three words. ``answered``: the API +answered and the answer is unusable (a refusal, a reply cut off at +``max_tokens``, no text block) or it rejected this one request as too large; +that is a fact about the pair and a caller may record it. ``rejected``: the +API rejected the request itself (400, 401, 403, 404) -- a bad schema, a bad +key, a retired model -- which is the operator's problem. ``unavailable``: a +connection error, a timeout, a 429, a 5xx or an overload; asking again later +is the right response. Only the SDK's own ``APIError`` family is classified; +any other exception is audited and re-raised untouched, because a ``TypeError`` +from a kwarg the SDK no longer accepts is a bug, not a verdict. + +**Synchronous** (task 029): the only caller is the adjudication loop inside a +click command, one pair at a time. + +**Outages kept**, because a rewrite from a blank file reintroduces them: see +:data:`_response_text` (the ``ThinkingBlock`` shape change and the refusal +rule) and the model note in ``__init__`` (a retired model that failed silently +for ten weeks). """ -import logging -from typing import Any - -from anthropic import AsyncAnthropic +from __future__ import annotations +import logging +from dataclasses import dataclass +from typing import Any, Literal + +from anthropic import ( + Anthropic, + APIError, + AuthenticationError, + BadRequestError, + NotFoundError, + PermissionDeniedError, + RequestTooLargeError, +) + +from ..config import credentials from ..config.settings import settings +from . import audit logger = logging.getLogger(__name__) +__all__ = ["EFFORT_LEVELS", "ROLES", "ClaudeClient", "ModelCallFailed", "ModelResponse"] + +EFFORT_LEVELS = ("low", "medium", "high", "xhigh", "max") + +# role -> the settings attribute naming its model. Two roles, two settings, no +# model string anywhere else. +ROLES: dict[str, str] = { + "triage": "llm_triage_model", + "synthesis": "llm_synthesis_model", +} + +Outcome = Literal["answered", "rejected", "unavailable"] + +# The API errors that mean the request, not the answer, is wrong. +_REQUEST_ERRORS = (BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError) + + +class ModelCallFailed(RuntimeError): + """ + An audited call that yielded no usable text. See the module docstring for + the three outcomes. Carries the audit id the request was logged under and + the usage the API reported (zeros when it never answered), so a caller + recording the failure can cite the log entry and the cost. + + Added 2026-09-22 (backlog task 029). + """ + + def __init__( + self, + message: str, + *, + audit_id: str, + outcome: Outcome, + input_tokens: int = 0, + output_tokens: int = 0, + stop_reason: str | None = None, + ) -> None: + super().__init__(message) + self.audit_id = audit_id + self.outcome: Outcome = outcome + self.input_tokens = input_tokens + self.output_tokens = output_tokens + self.stop_reason = stop_reason + + @property + def misconfigured(self) -> bool: + return self.outcome == "rejected" + + +def _classify(exc: APIError) -> Outcome: + if isinstance(exc, _REQUEST_ERRORS): + return "rejected" + if isinstance(exc, RequestTooLargeError): + return "answered" # this one request is too large; that is a fact about the pair + return "unavailable" + + +@dataclass(frozen=True) +class ModelResponse: + """What a call returned, and what it cost. ``audit_id`` finds it in the log.""" + + text: str + model: str + stop_reason: str | None + input_tokens: int + output_tokens: int + cache_read_input_tokens: int + cache_creation_input_tokens: int + audit_id: str + def _response_text(response) -> str: """Pull the assistant's text out of a response. @@ -43,175 +162,136 @@ def _response_text(response) -> str: return "".join(parts) +def _usage(response) -> dict[str, int]: + """The four token counts, as plain ints, zero when the API omits one.""" + usage = getattr(response, "usage", None) + return { + name: int(getattr(usage, name, None) or 0) + for name in ( + "input_tokens", + "output_tokens", + "cache_read_input_tokens", + "cache_creation_input_tokens", + ) + } + + class ClaudeClient: - """Minimal Claude API client for context-driven analysis""" + """One role, one model, one audited send path.""" - def __init__(self, api_key: str | None = None, model: str | None = None): + def __init__( + self, role: str = "triage", *, api_key: str | None = None, model: str | None = None + ): """ - Initialize Claude client - Args: - api_key: Anthropic API key (defaults to settings.anthropic_api_key) - model: Model id to use; defaults to Sonnet for synthesis workloads. - Pass a Haiku id for cheap classification / matching calls. + role: ``triage`` or ``synthesis``; picks the model from settings. + api_key: Only for tests. Everything else reads the keychain. + model: Only for tests. Everything else reads the role's setting. """ - self.api_key = api_key or settings.anthropic_api_key - if not self.api_key: - raise ValueError("ANTHROPIC_API_KEY not configured") - - self.client = AsyncAnthropic(api_key=self.api_key, timeout=300.0) - # Changed 2026-08-26: claude-sonnet-4-20250514 was RETIRED on 2026-06-15 and - # returns 404. Every synthesis run since then has failed at the API call. The - # documented replacement for that model is claude-sonnet-5. - self.model = model or "claude-sonnet-5" - # Raised from 16384 the same day. max_tokens caps thinking AND response text - # together, and this model thinks by default, so the old ceiling would truncate - # a full-length synthesis mid-answer. Its tokenizer also produces more tokens - # for the same text than the retired model's did. + if role not in ROLES: + raise ValueError(f"role must be one of {sorted(ROLES)}, got {role!r}") + self.role = role + self.api_key = api_key or credentials.read(credentials.ANTHROPIC) + # The SDK resends an identical request up to twice on a connection + # error, a 429 or a 5xx. That is a transport retry of the same request, + # not a second question, and the adjudicator's never-retried rule sits + # above it; the audit log records the request once. (2026-09-22.) + self.client = Anthropic(api_key=self.api_key, timeout=300.0) + # 2026-08-26: claude-sonnet-4-20250514 was RETIRED on 2026-06-15 and returned + # 404 for ten weeks while the CLI printed a duration and exited 0. The model + # is a setting now so that the next retirement is a one-line change in one + # place, and the audit log records which model actually served each call. + self.model = model or str(getattr(settings, ROLES[role])) + # max_tokens caps thinking AND response text together, and these models + # think by default, so a low ceiling truncates a full answer mid-sentence. self.max_tokens = 32000 - async def analyze( + def analyze( self, system_prompt: str, user_message: str, effort: str = "high", max_tokens: int | None = None, - ) -> str: - """ - Send analysis request to Claude - - Args: - system_prompt: System context and instructions - user_message: User query/request - effort: Reasoning depth -- "low" | "medium" | "high" | "xhigh" | "max" - max_tokens: Maximum tokens in response - - Returns: - Claude's response text - """ - try: - response = await self.client.messages.create( - model=self.model, - max_tokens=max_tokens or self.max_tokens, - # Sent via extra_body: the pinned SDK predates output_config as a - # named parameter and raises TypeError on it, but forwards extra_body - # into the request unchanged. Added 2026-08-26 -- once the SDK pin - # moves past that, this becomes output_config={"effort": effort}. - extra_body={"output_config": {"effort": effort}}, - system=system_prompt, - messages=[{"role": "user", "content": user_message}], - ) - - return _response_text(response) - - except Exception as e: - logger.error(f"Claude API error: {e}") - raise - - async def analyze_conversation( + output_schema: dict[str, Any] | None = None, + ) -> ModelResponse: + """One user turn.""" + return self.analyze_conversation( + system_prompt, + [{"role": "user", "content": user_message}], + effort, + max_tokens, + output_schema, + ) + + def analyze_conversation( self, system_prompt: str, - messages: list[dict[str, str]], + messages: list[dict[str, Any]], effort: str = "high", max_tokens: int | None = None, - ) -> str: + output_schema: dict[str, Any] | None = None, + ) -> ModelResponse: """ - Send conversation request to Claude with message history + Send a conversation and return the text with its usage. - Args: - system_prompt: System context and instructions - messages: List of message dicts with 'role' and 'content' keys - Roles must alternate: user, assistant, user, assistant... - effort: Reasoning depth -- "low" | "medium" | "high" | "xhigh" | "max" - max_tokens: Maximum tokens in response - - Returns: - Claude's response text + The request is written to the audit log before the call, the usage after + it, and the exception in between if the call fails. A refusal is + recorded as a response (it is one) and then raised. With + ``output_schema`` the API constrains the reply to that JSON schema; the + caller still validates what comes back. """ + if effort not in EFFORT_LEVELS: + raise ValueError(f"effort must be one of {EFFORT_LEVELS}, got {effort!r}") + + output_config: dict[str, Any] = {"effort": effort} + if output_schema is not None: + output_config["format"] = {"type": "json_schema", "schema": output_schema} + request: dict[str, Any] = { + "model": self.model, + "max_tokens": max_tokens or self.max_tokens, + "system": system_prompt, + "messages": messages, + "output_config": output_config, + } + audit_id = audit.record_request(self.role, request) + try: - response = await self.client.messages.create( - model=self.model, - max_tokens=max_tokens or self.max_tokens, - # Sent via extra_body: the pinned SDK predates output_config as a - # named parameter and raises TypeError on it, but forwards extra_body - # into the request unchanged. Added 2026-08-26 -- once the SDK pin - # moves past that, this becomes output_config={"effort": effort}. - extra_body={"output_config": {"effort": effort}}, - system=system_prompt, - messages=messages, - ) - - return _response_text(response) - - except Exception as e: - logger.error(f"Claude API error: {e}") + response = self.client.messages.create(**request) + except APIError as exc: + audit.record_error(audit_id, exc) + logger.error(f"Claude API error: {exc}") + raise ModelCallFailed( + f"{type(exc).__name__}: {exc}", audit_id=audit_id, outcome=_classify(exc) + ) from exc + except Exception as exc: + # Not an API error: a bug, a version mismatch, an interrupt's cousin. + # Audited so the log shows the request left, then re-raised as-is. + audit.record_error(audit_id, exc) raise - async def analyze_with_context( - self, context: dict[str, Any], task: str, effort: str = "high" - ) -> str: - """ - Analyze using curated context - - Args: - context: Curated context dictionary supplied by the caller - task: Task description/question - effort: Reasoning depth - - Returns: - Claude's response text - """ - system_prompt = self._build_system_prompt(context) - return await self.analyze(system_prompt, task, effort) - - def _build_system_prompt(self, context: dict[str, Any]) -> str: - """ - Build system prompt from curated context with few-shot examples - - Args: - context: Curated context dictionary - - Returns: - Formatted system prompt - """ - parts = [] - - # Add user profile context - if "user_profile" in context: - profile = context["user_profile"] - parts.append("## User Context") - parts.append(f"Location: {profile.get('location', 'Unknown')}") - parts.append( - f"Professional Domains: {', '.join(profile.get('professional_domains', []))}" - ) - parts.append(f"Civic Interests: {', '.join(profile.get('civic_interests', []))}") - parts.append("") - - # Add recent articles context - if "articles" in context: - parts.append(f"## Recent Articles ({len(context['articles'])} total)") - for i, article in enumerate(context["articles"][:20], 1): # Limit to top 20 - parts.append(f"\n### Article {i}") - parts.append(f"**Title:** {article.get('title', 'Untitled')}") - parts.append(f"**Source:** {article.get('source', 'Unknown')}") - if article.get("published_date"): - parts.append(f"**Date:** {article['published_date']}") - if article.get("content"): - parts.append(f"**Content:** {article['content'][:500]}...") - if article.get("entities"): - parts.append(f"**Entities:** {', '.join(article['entities'][:10])}") - parts.append("") - - # Add memory/historical context - if "memory" in context: - parts.append("## Historical Context") - parts.append(context["memory"]) - parts.append("") - - # Add instructions - if "instructions" in context: - parts.append("## Instructions") - parts.append(context["instructions"]) - parts.append("") - - return "\n".join(parts) + usage = _usage(response) + stop_reason = getattr(response, "stop_reason", None) + audit.record_response( + audit_id, + model=str(getattr(response, "model", self.model)), + stop_reason=stop_reason, + usage=usage, + ) + try: + text = _response_text(response) + except RuntimeError as exc: + raise ModelCallFailed( + str(exc), + audit_id=audit_id, + outcome="answered", + input_tokens=usage["input_tokens"], + output_tokens=usage["output_tokens"], + stop_reason=stop_reason, + ) from exc + return ModelResponse( + text=text, + model=str(getattr(response, "model", self.model)), + stop_reason=stop_reason, + audit_id=audit_id, + **usage, + ) diff --git a/src/logs/.gitkeep b/src/logs/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/src/matching/__init__.py b/src/matching/__init__.py index f7562c7..e66aa0a 100644 --- a/src/matching/__init__.py +++ b/src/matching/__init__.py @@ -9,11 +9,12 @@ Ported out of the deleted ``src/context/`` package by backlog task 012: * :mod:`~src.matching.entity_matcher` -- alias matching for Tier 1 routing. -* :mod:`~src.matching.coverage_probe` -- "did anything match this in N days", - which is the staleness check task 018 needs. -* :mod:`~src.matching.terms` -- the value objects both consume. +* :mod:`~src.matching.terms` -- the value object it consumes. + +``coverage_probe.py`` left with backlog task 027 on 2026-09-22; see +``src/matching/terms.py`` for why. """ -from .terms import CoverageEntity, CoverageProbe +from .terms import CoverageEntity -__all__ = ["CoverageEntity", "CoverageProbe"] +__all__ = ["CoverageEntity"] diff --git a/src/matching/coverage_probe.py b/src/matching/coverage_probe.py deleted file mode 100644 index 26ae8ba..0000000 --- a/src/matching/coverage_probe.py +++ /dev/null @@ -1,498 +0,0 @@ -""" -Testing a set of sources against events that actually happened. - -Task 005 asked whether a source list could reach its domain and answered with -document counts: 469 Federal Register documents narrowed to 24, 38 retrieved in -seven days. Both real, both green, and neither able to detect that the sources -were structurally unable to see a personnel change -- because a personnel change -is not a document. The first live run then missed the reinstatement of the -FedRAMP director, the largest event in the declared domain that week. - -**An article count measures whether ingestion is running. It does not measure -whether ingestion reaches the domain.** A coverage probe measures the second -thing, by the only method that cannot be satisfied by ingesting more of what the -sources already carry: - - Name something that actually happened in this domain, then check whether the - sources can see it. - -Nothing here calls a model. A probe either matched a stored article or it did -not, and the answer is reproducible from the same rows forever and debuggable by -reading a regex rather than by re-running a prompt. - -Three rules do the work: - -* **Word boundaries, not substrings.** Measured on this repository's corpus on - 2026-08-27: of 54,044 stored articles, 657 titles contain the substring - ``nist`` -- "administration", "minister", "Afghanistan", "communist", - "sinister", "columnist" -- and exactly 4 are about NIST. A substring matcher - would report 99.4% false coverage on that one term alone. Terms are anchored - at word boundaries by :mod:`src.matching.entity_matcher`, which is the same - code path coverage entities use. -* **Stems are marked, never inferred.** ``reinstat*`` matches "reinstated" and - "reinstatement"; ``reinstat`` matches neither. Inferring the widening would - make every term quietly broader than it reads in the config, which is the - direction that manufactures false confidence. -* **A window with no articles in it is not a failure.** A probe whose window - predates the corpus, or falls in a gap, is ``INCONCLUSIVE`` -- it says nothing - about the sources' reach, because there was nothing to reach with. It stays in - the count regardless, since a probe set that quietly shrinks to the events - still in retention is a green light that means nothing. - -Added 2026-08-27 for backlog task 010. Moved here from ``src/context/`` by task -012 and decoupled from the deleted ``BeatConfig``: the caller now supplies the -probes and the feed URLs directly. "Did anything match this in N days" is the -staleness check task 018 needs, and this is already that engine. -""" - -from __future__ import annotations - -import re -from collections.abc import Iterable, Sequence -from dataclasses import dataclass -from datetime import date, datetime, time - -from sqlalchemy.orm import Session - -from ..database.models import Article, RSSFeed -from .entity_matcher import is_shouted, term_pattern -from .terms import CoverageProbe - -__all__ = [ - "STATUS_INCONCLUSIVE", - "STATUS_MATCHED", - "STATUS_UNMATCHED", - "CompiledProbe", - "CoverageReport", - "ProbeMatch", - "ProbeResult", - "compile_probe", - "run_coverage_probes", -] - -# A probe matched at least one article the selected sources carried. -STATUS_MATCHED = "MATCHED" -# The window held articles from the selected sources and none of them matched. -# This is the finding the feature exists to produce. -STATUS_UNMATCHED = "UNMATCHED" -# The window held nothing to match against, so the probe answers nothing. -STATUS_INCONCLUSIVE = "INCONCLUSIVE" - -# The marker that turns a term into a stem. Trailing only: a leading wildcard -# would drop the left-hand word boundary, which is the boundary that does -# essentially all of the collision filtering. -STEM_MARKER = "*" - -# How many matching articles to keep per probe. The question is "can these -# sources see this", not "how loudly", so a handful of examples is the evidence a -# reader needs and an unbounded list would bury the verdict. -DEFAULT_MATCH_LIMIT = 5 - - -@dataclass(frozen=True) -class CompiledTerm: - """One probe term as written, with its compiled pattern.""" - - raw: str - pattern: re.Pattern[str] - - def found_in(self, text: str) -> bool: - return bool(self.pattern.search(text)) - - -def _compile_term(raw: str) -> CompiledTerm: - """ - Compile one term under the same boundary and case rules as coverage entities. - - A term written entirely in capitals is an acronym and matches - case-sensitively -- ``BOD`` is a directive, ``bod`` is not. Everything else - matches case-insensitively, because ordinary names are case-varied in prose - and long enough not to collide. - """ - stem = raw.endswith(STEM_MARKER) - body = raw[: -len(STEM_MARKER)] if stem else raw - source = term_pattern(body, right_boundary=not stem) - flags = 0 if is_shouted(body) else re.IGNORECASE - return CompiledTerm(raw=raw, pattern=re.compile(source, flags)) - - -@dataclass(frozen=True) -class CompiledProbe: - """ - One probe with every term compiled, ready to be run against many articles. - - ``required`` must all be found in the same article; each group in ``groups`` - contributes one alternative that must be found. An article satisfies the - probe only when both hold. - """ - - probe: CoverageProbe - required: tuple[CompiledTerm, ...] - groups: tuple[tuple[CompiledTerm, ...], ...] - - def matches(self, text: str) -> bool: - """Whether one article's text satisfies every requirement.""" - absent, unsatisfied = self.missing(text) - return not absent and not unsatisfied - - def missing(self, text: str) -> tuple[tuple[str, ...], tuple[tuple[str, ...], ...]]: - """ - What this text failed to supply: absent required terms, then unsatisfied - groups. - - Returned rather than swallowed so an unmatched probe can say *which* - requirement went unmet. An operator reading "FedRAMP absent" fixes a - source; one reading "matched FedRAMP but nothing in (director, - administrator)" fixes the probe. - """ - absent = tuple(term.raw for term in self.required if not term.found_in(text)) - unsatisfied = tuple( - tuple(term.raw for term in group) - for group in self.groups - if not any(term.found_in(text) for term in group) - ) - return absent, unsatisfied - - -def compile_probe(probe: CoverageProbe) -> CompiledProbe: - """Compile one probe's terms once, for reuse across every candidate article.""" - return CompiledProbe( - probe=probe, - required=tuple(_compile_term(term) for term in probe.terms), - groups=tuple(tuple(_compile_term(term) for term in group) for group in probe.any_of), - ) - - -@dataclass(frozen=True) -class ProbeMatch: - """One article that satisfied a probe, and the source that carried it.""" - - article_id: int - title: str - feed_name: str - published_date: datetime | None - in_selected_sources: bool - - @property - def published_day(self) -> str: - return self.published_date.date().isoformat() if self.published_date else "undated" - - -@dataclass(frozen=True) -class ProbeResult: - """ - What one probe found. - - ``elsewhere`` is only populated for a probe the selected sources missed: it - names articles from feeds *outside* that selection which would have - satisfied it. That distinction is the actionable part. "Nobody in the corpus - carried it" and "three feeds you do not subscribe to carried it" are the - same ``UNMATCHED`` verdict and completely different repairs. - """ - - probe: CoverageProbe - status: str - window: tuple[date, date] - articles_in_window: int - matches: tuple[ProbeMatch, ...] = () - match_count: int = 0 - elsewhere: tuple[ProbeMatch, ...] = () - elsewhere_count: int = 0 - reason: str = "" - missing_terms: tuple[str, ...] = () - unsatisfied_groups: tuple[tuple[str, ...], ...] = () - - @property - def matched(self) -> bool: - return self.status == STATUS_MATCHED - - @property - def conclusive(self) -> bool: - return self.status != STATUS_INCONCLUSIVE - - -@dataclass(frozen=True) -class CoverageReport: - """ - Every probe's result for one subject, plus the corpus facts that framed them. - - ``total`` is the number of probes the caller *supplied*, and the passed, - unmatched and inconclusive counts always sum to it. The invariant is the - point: an inconclusive probe is subtracted from neither side, so a probe set - rotting out of retention shows up as a shrinking denominator of *answered* - questions rather than as a clean sweep of the ones that remain. - - ``subject`` is a free-text label for whatever the probe set belongs to. It - was ``beat_name`` until task 012 deleted beats; nothing here interprets it. - """ - - subject: str - results: tuple[ProbeResult, ...] - feed_names: tuple[str, ...] - earliest: datetime | None - latest: datetime | None - - @property - def total(self) -> int: - return len(self.results) - - @property - def matched(self) -> tuple[ProbeResult, ...]: - return tuple(r for r in self.results if r.status == STATUS_MATCHED) - - @property - def unmatched(self) -> tuple[ProbeResult, ...]: - return tuple(r for r in self.results if r.status == STATUS_UNMATCHED) - - @property - def inconclusive(self) -> tuple[ProbeResult, ...]: - return tuple(r for r in self.results if r.status == STATUS_INCONCLUSIVE) - - @property - def conclusive(self) -> tuple[ProbeResult, ...]: - return tuple(r for r in self.results if r.conclusive) - - -def article_text(article: Article) -> str: - """ - The text of one stored article that probe matching reads. - - Title, summary and normalized body. ``author`` is excluded, as it is in - :func:`src.matching.entity_matcher.item_text`: a byline is a person, and a - probe is about whether a source carried an event, never about who wrote it. - """ - parts = [ - article.title or "", - article.description or "", - article.normalized_content or article.content or "", - ] - return "\n".join(part for part in parts if part) - - -def _window_bounds(probe: CoverageProbe) -> tuple[datetime, datetime]: - """The probe's date window as the half-open datetime range SQL compares.""" - start, end = probe.window - return datetime.combine(start, time.min), datetime.combine(end, time.max) - - -def _to_match(article: Article, feed_name: str | None, in_selected_sources: bool) -> ProbeMatch: - return ProbeMatch( - article_id=article.id, - title=article.title or "(untitled)", - feed_name=feed_name or "(unattributed source)", - published_date=article.published_date, - in_selected_sources=in_selected_sources, - ) - - -def _rows_in_window( - session: Session, probe: CoverageProbe, feed_ids: Sequence[int] | None -) -> list[tuple[Article, str | None]]: - """ - Every dated article in the probe's window, with its source name. - - Undated rows are excluded rather than assumed recent: an article with no - ``published_date`` cannot be placed in or out of any window, and counting it - as in-window would let an unplaceable row turn an inconclusive probe into a - failure. - - This is the only database access in the module and it is a SELECT. Nothing - in the coverage path writes -- the corpus is shared, and a read-only - question must not leave a trace in the thing it is asking about. - """ - start, end = _window_bounds(probe) - query = ( - session.query(Article, RSSFeed.name) - .outerjoin(RSSFeed, Article.feed_id == RSSFeed.id) - .filter(Article.published_date.isnot(None)) - .filter(Article.published_date >= start) - .filter(Article.published_date <= end) - ) - if feed_ids is not None: - query = query.filter(Article.feed_id.in_(feed_ids)) - return query.order_by(Article.published_date.asc()).all() - - -@dataclass(frozen=True) -class _Evaluation: - """One probe's outcome over one set of candidate rows.""" - - matches: tuple[ProbeMatch, ...] - match_count: int - missing_terms: tuple[str, ...] - unsatisfied_groups: tuple[tuple[str, ...], ...] - - -def _evaluate( - compiled: CompiledProbe, - rows: Iterable[tuple[Article, str | None]], - in_selected_sources: bool, - limit: int, -) -> _Evaluation: - """ - Run one compiled probe over candidate rows. - - ``match_count`` is every match; ``matches`` is the earliest ``limit`` of - them, kept separate so the display cap can never make a widely-reported - event look like a single lucky hit. - - Also returns the *closest* near miss -- the requirements unmet by whichever - article satisfied the most of them. With no matches that is the diagnostic - an operator acts on; with matches it is discarded by the caller. - """ - matches: list[ProbeMatch] = [] - match_count = 0 - best_absent: tuple[str, ...] = tuple(term.raw for term in compiled.required) - best_groups: tuple[tuple[str, ...], ...] = tuple( - tuple(term.raw for term in group) for group in compiled.groups - ) - best_score = len(best_absent) + len(best_groups) - - for article, feed_name in rows: - absent, unsatisfied = compiled.missing(article_text(article)) - if not absent and not unsatisfied: - match_count += 1 - if len(matches) < limit: - matches.append(_to_match(article, feed_name, in_selected_sources)) - continue - score = len(absent) + len(unsatisfied) - if score < best_score: - best_score, best_absent, best_groups = score, absent, unsatisfied - - return _Evaluation(tuple(matches), match_count, best_absent, best_groups) - - -def run_coverage_probes( - session: Session, - probes: Sequence[CoverageProbe], - feed_urls: Sequence[str], - *, - subject: str = "", - match_limit: int = DEFAULT_MATCH_LIMIT, -) -> CoverageReport: - """ - Run every supplied probe against the corpus, read-only. - - The verdict is scoped to ``feed_urls``: a probe passes when one of *those* - feeds carried the event. An unmatched probe is then re-run across the whole - corpus, and any hit is reported as ``elsewhere`` -- evidence that the event - was reachable and the selected source list is what missed it. - - An empty ``probes`` returns an empty report. That is not a pass, and the - caller is expected to say so: an undeclared probe set is the state the old - beat was already in when it missed the FedRAMP reinstatement. - - Before task 012 this took a ``BeatConfig`` and called ``resolve_feeds()`` - itself. Beats are gone; the caller now names the scope, which is also what - a staleness check wants -- it already knows which feeds it is asking about. - """ - urls = list(feed_urls) - feed_rows = session.query(RSSFeed).filter(RSSFeed.url.in_(urls)).all() if urls else [] - feed_ids = [row.id for row in feed_rows] - feed_names = tuple(sorted(row.name for row in feed_rows)) - - earliest, latest = _corpus_bounds(session, feed_ids) - - results: list[ProbeResult] = [] - for probe in probes: - compiled = compile_probe(probe) - rows = _rows_in_window(session, probe, feed_ids) if feed_ids else [] - found = _evaluate(compiled, rows, True, match_limit) - - if found.match_count: - results.append( - ProbeResult( - probe=probe, - status=STATUS_MATCHED, - window=probe.window, - articles_in_window=len(rows), - matches=found.matches, - match_count=found.match_count, - ) - ) - continue - - if not rows: - results.append( - ProbeResult( - probe=probe, - status=STATUS_INCONCLUSIVE, - window=probe.window, - articles_in_window=0, - reason=_inconclusive_reason(probe, earliest, latest, bool(feed_ids)), - ) - ) - continue - - searched_ids = {article.id for article, _ in rows} - wider = _evaluate(compiled, _rows_in_window(session, probe, None), False, match_limit) - elsewhere = tuple(m for m in wider.matches if m.article_id not in searched_ids) - results.append( - ProbeResult( - probe=probe, - status=STATUS_UNMATCHED, - window=probe.window, - articles_in_window=len(rows), - elsewhere=elsewhere, - elsewhere_count=wider.match_count, - missing_terms=found.missing_terms, - unsatisfied_groups=found.unsatisfied_groups, - ) - ) - - return CoverageReport( - subject=subject, - results=tuple(results), - feed_names=feed_names, - earliest=earliest, - latest=latest, - ) - - -def _corpus_bounds( - session: Session, feed_ids: Sequence[int] -) -> tuple[datetime | None, datetime | None]: - """Oldest and newest dated article carried by the selected sources.""" - if not feed_ids: - return None, None - query = session.query(Article.published_date).filter( - Article.feed_id.in_(feed_ids), Article.published_date.isnot(None) - ) - earliest = query.order_by(Article.published_date.asc()).first() - latest = query.order_by(Article.published_date.desc()).first() - return (earliest[0] if earliest else None), (latest[0] if latest else None) - - -def _inconclusive_reason( - probe: CoverageProbe, - earliest: datetime | None, - latest: datetime | None, - has_feeds: bool, -) -> str: - """ - Why a probe could not be answered, in the terms an operator can act on. - - The three cases are different problems. Predating the corpus means the probe - has aged out and should be replaced. Postdating it means the pipeline has not - run far enough forward yet. A gap in the middle means ingestion was down, and - that is worth knowing on its own. - """ - if not has_feeds: - return "these sources have no rows in the corpus, so nothing was searched" - if earliest is None: - return "these sources have stored no dated articles, so nothing was searched" - start, end = probe.window - if end < earliest.date(): - return ( - f"window ends {end.isoformat()}, before the oldest stored article " - f"({earliest.date().isoformat()}) -- the event predates the corpus" - ) - if latest is not None and start > latest.date(): - return ( - f"window starts {start.isoformat()}, after the newest stored article " - f"({latest.date().isoformat()}) -- the corpus has not reached the event yet" - ) - return ( - "these sources stored no dated articles anywhere in this window -- " - "a gap in the corpus, not a gap in the source list" - ) diff --git a/src/matching/entity_matcher.py b/src/matching/entity_matcher.py index 8bced2b..7015e5d 100644 --- a/src/matching/entity_matcher.py +++ b/src/matching/entity_matcher.py @@ -57,8 +57,9 @@ # Any run of whitespace, including a line wrap, between the words of a term. _WHITESPACE = r"\s+" -# Kept public since backlog task 010: coverage probes match their terms by the -# same rules as coverage entities, and a second boundary definition would be a +# Public on purpose: the routing compiler (backlog task 028) matches trigger +# terms by these rules, and its regression test strips the anchors to prove the +# test would notice their absence. A second boundary definition would be a # second thing to get wrong. @@ -74,21 +75,18 @@ def is_shouted(term: str) -> bool: return bool(letters) and all(char.isupper() for char in letters) -def term_pattern(term: str, right_boundary: bool = True) -> str: +def term_pattern(term: str) -> str: """ - Regex source for one surface form. + Regex source for one surface form, anchored at both word boundaries. Runs of whitespace in the term match any run of whitespace in the text, so a name broken across a line wrap in the source still matches. - ``right_boundary=False`` anchors only the left-hand side, which turns the - term into a stem: it must still begin a word, but the word may continue. - Coverage probes use it for ``reinstat*``; coverage entities never do, - because an entity's surface forms are whole names. + The stem form (``reinstat*``, left-anchored only) left with the coverage + probes on 2026-09-22 (backlog task 027); a trigger term is a whole name. """ body = _WHITESPACE.join(re.escape(token) for token in term.split()) - tail = RIGHT_BOUNDARY if right_boundary else "" - return f"{LEFT_BOUNDARY}(?:{body}){tail}" + return f"{LEFT_BOUNDARY}(?:{body}){RIGHT_BOUNDARY}" @dataclass(frozen=True) diff --git a/src/matching/terms.py b/src/matching/terms.py index a5e6e3c..3e640f4 100644 --- a/src/matching/terms.py +++ b/src/matching/terms.py @@ -1,52 +1,36 @@ """ -What a matcher is pointed at: entities and probes. +What a matcher is pointed at: entities. -These two value objects were lifted verbatim from ``src/config/beats.py`` when -the briefing product was deleted (backlog task 012). The *beat* they used to -belong to is gone -- a beat was a subject with its own source list, and the new -shape tracks one operator's decisions instead. What survives is the pair of -descriptions the deterministic matchers consume: +This value object was lifted verbatim from ``src/config/beats.py`` when the +briefing product was deleted (backlog task 012). The *beat* it used to belong +to is gone -- a beat was a subject with its own source list, and the new shape +tracks one operator's decisions instead. What survives is the description the +deterministic matchers consume: * :class:`CoverageEntity` -- an institution and its surface forms, read by :mod:`src.matching.entity_matcher` (Tier 1 routing). -* :class:`CoverageProbe` -- one thing that actually happened plus the words any - report of it would carry, read by :mod:`src.matching.coverage_probe` (the - staleness check task 018 needs). -They carry no loader. The JSON beat-file parsing and validation that used to -build them died with ``src/config/beats.py``; whatever declares an entity or a -probe in the new shape constructs these directly. +``CoverageProbe`` and its module :mod:`src.matching.coverage_probe` left with +backlog task 027 on 2026-09-22: the staleness check in ``docs/PLAN.md`` is a +query over ``routes`` ("nothing routed for N days"), not a probe match over +``articles``, and no rewritten task names a probe. See ``backlog/027-sweep.md`` +for the record. + +:class:`CoverageEntity` carries no loader. The JSON beat-file parsing and +validation that used to build it died with ``src/config/beats.py``; whatever +declares an entity in the new shape constructs it directly. """ from __future__ import annotations from dataclasses import dataclass -from datetime import date, timedelta __all__ = [ "COVERAGE_KINDS", - "DEFAULT_PROBE_WINDOW_DAYS", "ENTITY_KINDS", - "MIN_PROBE_EVIDENCE", "CoverageEntity", - "CoverageProbe", ] -# How far either side of a probe's date a report of it is still a report of it. -# Symmetric because coverage runs both ways: a rule is trailed before it lands -# and analysed for a week after. Fourteen days is the interval the FedRAMP miss -# was measured over -- "3 incidental mentions and none within two weeks". -DEFAULT_PROBE_WINDOW_DAYS = 14 - -# The least evidence a probe may rest on. A probe is a claim that a match means -# the matcher saw a specific event, and one bare term cannot carry that claim: -# `FedRAMP` alone is matched by an AWS region-launch post. Two independent -# pieces of evidence -- two required terms, or one required term plus one -# `any_of` group -- is the floor. The beat-file loader used to enforce this at -# parse time; with the loader gone it stands here as the documented floor for -# whatever constructs probes next. -MIN_PROBE_EVIDENCE = 2 - # The only three things coverage may track, and the plural config key that used # to declare each. The mapping is closed on purpose: any other key -- `people`, # `officials`, `staff`, anything -- was a validation error rather than a @@ -94,49 +78,3 @@ def terms(self) -> tuple[str, ...]: for term in (self.name, *self.aliases): seen.setdefault(term, None) return tuple(seen) - - -@dataclass(frozen=True) -class CoverageProbe: - """ - One thing that actually happened, used to test whether coverage can see it. - - A probe is not a search. It is a claim of the form "an event of this - description occurred on this date, and any report of it would carry these - words" -- which makes an unmatched probe a statement about the source list - rather than about the phrasing of a query. - - ``terms`` must **all** appear in the same article; each group in ``any_of`` - contributes one alternative that must appear. The two levels exist because - a single distinctive term is too weak to be evidence and a whole headline is - too brittle to survive a second outlet's phrasing. - - A term ending in ``*`` is a stem: ``reinstat*`` matches "reinstated" and - "reinstatement". Without the marker a term matches whole words only. The - marker is explicit rather than implied so that the widening is visible to - whoever has to trust the result -- see :mod:`src.matching.coverage_probe` - for the matching rules themselves. - """ - - date: date - what: str - terms: tuple[str, ...] - any_of: tuple[tuple[str, ...], ...] = () - window_days: int = DEFAULT_PROBE_WINDOW_DAYS - - @property - def window(self) -> tuple[date, date]: - """The inclusive date range in which a report of this event counts.""" - span = timedelta(days=self.window_days) - return self.date - span, self.date + span - - @property - def evidence_count(self) -> int: - """How many independent things this probe requires of an article.""" - return len(self.terms) + len(self.any_of) - - def describe(self) -> str: - """The probe's requirement, written the way it was declared.""" - parts = [" AND ".join(self.terms)] if self.terms else [] - parts.extend("(" + " OR ".join(group) + ")" for group in self.any_of) - return " AND ".join(parts) diff --git a/src/position/__init__.py b/src/position/__init__.py index e8228e8..61599aa 100644 --- a/src/position/__init__.py +++ b/src/position/__init__.py @@ -9,6 +9,17 @@ Added 2026-08-31 for backlog task 013. """ +from .ledger import ( + BELIEF_SOURCES, + OUTCOMES, + CurrentBelief, + LedgerError, + current_beliefs, + live_clause, + open_clause, + record_belief, + resolve_watch, +) from .position import ( MAX_PAGES, POSITION_PAGE_WORDS, @@ -27,16 +38,25 @@ ) __all__ = [ + "BELIEF_SOURCES", "MAX_PAGES", + "OUTCOMES", "POSITION_PAGE_WORDS", "TRIGGER_FIELDS", + "CurrentBelief", "Decision", + "LedgerError", "Position", "PositionError", "TriggerClause", "Watch", "WatchError", + "current_beliefs", + "live_clause", "load_position", "load_watches", + "open_clause", + "record_belief", + "resolve_watch", "sync_watches", ] diff --git a/src/position/ledger.py b/src/position/ledger.py new file mode 100644 index 0000000..afe8408 --- /dev/null +++ b/src/position/ledger.py @@ -0,0 +1,195 @@ +""" +The belief ledger, resolution, and what "live" means -- in one place. + +Three things the rest of the monitor reads from here: + +* **Belief is a ledger, not a column.** ``watches.belief`` is the value at + registration. Every value, including that first one, is a ``watch_beliefs`` + row with a source and a date: ``file`` when the watch file set it at sync, + ``principal`` when the operator wrote it with ``watch believe``. The current + belief is the latest row. Nothing here moves belief on its own; there is no + update rule (decided 2026-09-22, ``backlog/030``), and the ledger's + append-only guards mean the history is reconstructable whatever later tasks + add. +* **Resolution is a human act, once.** ``watch resolve`` sets the outcome and + the date; there is no unresolve, no force, and no path from evidence to + outcome. The 33 predictions graded zero times in the old ledger are the + standing reason grading has to be deliberate. A retired watch can be graded + (a claim often settles after it leaves the file) but takes no new belief. +* **Liveness has one definition.** A watch is live when it is not expired, + not retired (absent from the file at the last sync) and not resolved. + Routing filters through :func:`live_clause`; adjudication and replay, which + read routed pairs, filter through :func:`open_clause` (retired and resolved, + the two state-based conditions), because expiry is Tier 1's gate at routing + time and a date-dependent filter there would make a replay depend on the + day it ran. + +Added 2026-09-22 for backlog task 030. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from datetime import date, datetime + +from sqlalchemy import ColumnElement, and_ +from sqlalchemy.orm import Session + +from src.database.models import Watch, WatchBelief +from src.utils import utcnow + +__all__ = [ + "BELIEF_SOURCES", + "OUTCOMES", + "CurrentBelief", + "LedgerError", + "current_beliefs", + "live_clause", + "open_clause", + "record_belief", + "resolve_watch", +] + +BELIEF_SOURCES = ("file", "principal") +OUTCOMES = ("yes", "no") + + +class LedgerError(ValueError): + """A write the ledger refuses: unknown watch, dead watch, bad value, blank note.""" + + +@dataclass(frozen=True) +class CurrentBelief: + watch_id: str + belief: float + source: str + observed_at: datetime + note: str | None + registered: float # watches.belief, the value at registration + + +def open_clause() -> ColumnElement[bool]: + """Not retired and not resolved: the state-based half of liveness.""" + return and_(Watch.retired_at.is_(None), Watch.resolved_at.is_(None)) + + +def live_clause(today: date) -> ColumnElement[bool]: + """Open and not expired: what routing links to.""" + return and_(open_clause(), Watch.expires >= today) + + +def _watch_for_write(db: Session, watch_id: str, *, allow_retired: bool) -> Watch: + row = db.get(Watch, watch_id) + if row is None: + raise LedgerError(f"no watch '{watch_id}'; run 'watch sync' or check the id") + if row.retired_at is not None and not allow_retired: + raise LedgerError( + f"watch '{watch_id}' was retired on {row.retired_at.date().isoformat()}; put it " + f"back in the file and sync to restore it" + ) + if row.resolved_at is not None: + raise LedgerError( + f"watch '{watch_id}' was resolved '{row.outcome}' on " + f"{row.resolved_at.date().isoformat()}" + ) + return row + + +def record_belief( + db: Session, + watch_id: str, + belief: float, + *, + source: str, + note: str | None, + observed_at: datetime | None = None, +) -> WatchBelief: + """Append one belief row. Refuses rather than defaults, on every field.""" + if source not in BELIEF_SOURCES: + raise LedgerError(f"belief source must be one of {BELIEF_SOURCES}, got {source!r}") + if not isinstance(belief, int | float) or isinstance(belief, bool): + raise LedgerError(f"belief must be a number in [0, 1], got {belief!r}") + if not 0.0 <= belief <= 1.0: + raise LedgerError(f"belief must be in [0, 1], got {belief}") + if source == "principal" and not (note or "").strip(): + raise LedgerError("a belief written by the operator needs a note saying why") + # A retired watch takes no new belief: it is not being held. It can still + # be graded (resolve_watch), because settling a claim after dropping it + # from the file is an ordinary order of events. + _watch_for_write(db, watch_id, allow_retired=False) + row = WatchBelief( + watch_id=watch_id, + belief=float(belief), + source=source, + note=(note or "").strip() or None, + observed_at=observed_at or utcnow(), + ) + db.add(row) + db.flush() + return row + + +def current_beliefs(db: Session, *, as_of: datetime | None = None) -> dict[str, CurrentBelief]: + """ + The latest ledger row per watch, or the latest at or before ``as_of``. + + A watch with no ledger row -- one stored before the ledger existed, or a + row inserted by hand -- reads as its registration belief, labelled + ``file`` and dated by its ``created_at``, which is what that value is. + ``as_of`` is for the brief, which is a pure function of the moment it is + rendered as of (2026-09-23, backlog task 031 review). + """ + registered: dict[str, float] = {} + out: dict[str, CurrentBelief] = {} + for w in db.query(Watch).all(): + watch_id = str(w.id) + registered[watch_id] = float(w.belief) + # Column[...] versus value, as in src/sources/store.py: the models use + # the pre-2.0 Column() style that mypy reads as the column type. + out[watch_id] = CurrentBelief( + watch_id, + float(w.belief), + "file", + w.created_at, # type: ignore[arg-type] + None, + float(w.belief), + ) + query = db.query(WatchBelief) + if as_of is not None: + query = query.filter(WatchBelief.observed_at <= as_of) + rows = query.order_by(WatchBelief.observed_at, WatchBelief.id).all() + for row in rows: + watch_id = str(row.watch_id) + if watch_id not in registered: + # SQLite is not enforcing the foreign key (no PRAGMA), so a hand + # delete of a watch leaves its ledger behind. Say so, by name. + raise LedgerError( + f"watch_beliefs row {row.id} belongs to watch '{watch_id}', which does not " + f"exist; a watch is retired by sync, never deleted, so this row was orphaned " + f"by hand and must be repaired by hand" + ) + out[watch_id] = CurrentBelief( + watch_id=watch_id, + belief=float(row.belief), + source=str(row.source), + observed_at=row.observed_at, # type: ignore[arg-type] + note=row.note, # type: ignore[arg-type] + registered=registered[watch_id], + ) + return out + + +def resolve_watch( + db: Session, watch_id: str, *, outcome: str, note: str, when: datetime | None = None +) -> Watch: + """Grade a watch, once. There is no unresolve and no path from evidence here.""" + if outcome not in OUTCOMES: + raise LedgerError(f"outcome must be one of {OUTCOMES}, got {outcome!r}") + if not (note or "").strip(): + raise LedgerError("a resolution needs a note saying what settled it") + row = _watch_for_write(db, watch_id, allow_retired=True) + row.resolved_at = when or utcnow() # type: ignore[assignment] + row.outcome = outcome # type: ignore[assignment] + row.resolution_note = note.strip() # type: ignore[assignment] + db.flush() + return row diff --git a/src/position/position.py b/src/position/position.py index 96c64f1..b2c3aa9 100644 --- a/src/position/position.py +++ b/src/position/position.py @@ -19,8 +19,8 @@ two pages has drifted into describing interests rather than stakes. A hard limit would enforce a proxy: a three-page Position full of genuine deadlines is better than a one-page Position of vague interests. So the check names the drift and -lets the human judge, the same way ``coverage_probes`` reports INCONCLUSIVE -rather than dropping a probe. Everything that is *structurally* checkable -- +lets the human judge, rather than silently rejecting the file. Everything that +is *structurally* checkable -- a decision with no deadline, a duplicate key, a date that is not a date -- is a hard rejection, because those are not judgement calls. diff --git a/src/position/watches.py b/src/position/watches.py index 3d531a9..321d045 100644 --- a/src/position/watches.py +++ b/src/position/watches.py @@ -180,29 +180,44 @@ def sync_watches(session: Any, watches: list[Watch]) -> dict[str, list[str]]: """ Make the ``watches`` table match the file, and report what moved. - The file is authoritative: a watch removed from it is removed from the - table. That is the whole write path -- there is no other way a row gets into - this table, and there is deliberately no argument by which a caller could - describe a watch that is not in the file. + The file is authoritative for what a watch *is*: claim, decision, triggers, + expiry, staleness. That is the whole write path -- there is no other way a + row gets into this table, and there is deliberately no argument by which a + caller could describe a watch that is not in the file. + + Two things the file does not overwrite, since 2026-09-22 (backlog task 030): + + * **Belief.** ``watches.belief`` is the value at registration. Every value + is a ledger row (``src.position.ledger``); sync writes a ``file`` row + when a watch is first stored and whenever the file's belief differs from + the current one, so a file that is behind the operator's own updates + shows up as a change with a source, not as a silent overwrite. + * **Existence.** A watch absent from the file is *retired*, not deleted: + its belief history is the calibration record and a delete would take it. + A retired id that returns to the file is restored. A resolved watch is + updated but never un-resolved; the file cannot grade or ungrade. Takes already-validated :class:`Watch` values, so an invalid file cannot reach this function at all. - - - Removing a watch from the file deletes its row. That is correct while this - table holds nothing derived -- the file is the source of truth and a watch - you deleted is a watch you stopped holding. **Task 017 hangs belief history - off these rows**, and at that point a delete destroys the record of what you - believed and when, which is the calibration data the system exists to - accumulate. Revisit this before 017 lands: the likely answer is a soft - retire rather than a delete. Noted 2026-08-31 (task 013). """ from src.database.models import Watch as WatchRow + from src.utils import utcnow + + from .ledger import current_beliefs, record_belief incoming = {w.id: w for w in watches} existing = {row.id: row for row in session.query(WatchRow).all()} - - summary: dict[str, list[str]] = {"added": [], "updated": [], "removed": []} + beliefs = current_beliefs(session) + + summary: dict[str, list[str]] = { + "added": [], + "updated": [], + "retired": [], + "restored": [], + "belief_changed": [], + "resolved": [], + } + now = utcnow() for watch_id, watch in incoming.items(): row = existing.get(watch_id) @@ -219,21 +234,55 @@ def sync_watches(session: Any, watches: list[Watch]) -> dict[str, list[str]]: staleness_alert_days=watch.staleness_alert_days, ) ) + session.flush() + record_belief( + session, + watch_id, + watch.belief, + source="file", + note="registered from the watch file", + observed_at=now, + ) summary["added"].append(watch_id) continue - row.claim = watch.claim - row.belief = watch.belief - row.so_what = watch.so_what - row.decision_key = watch.decision_key - row.triggers = watch.triggers_json() - row.expires = watch.expires - row.staleness_alert_days = watch.staleness_alert_days - summary["updated"].append(watch_id) + + if row.retired_at is not None: + row.retired_at = None + summary["restored"].append(watch_id) + definition = { + "claim": watch.claim, + "so_what": watch.so_what, + "decision_key": watch.decision_key, + "triggers": watch.triggers_json(), + "expires": watch.expires, + "staleness_alert_days": watch.staleness_alert_days, + } + changed = {k: v for k, v in definition.items() if getattr(row, k) != v} + for key, value in changed.items(): + setattr(row, key, value) + if changed: + summary["updated"].append(watch_id) + + if row.resolved_at is not None: + summary["resolved"].append(watch_id) + continue + current = beliefs[watch_id].belief + if abs(current - watch.belief) > 1e-9: + session.flush() + record_belief( + session, + watch_id, + watch.belief, + source="file", + note=f"the watch file changed the belief from {current:g}", + observed_at=now, + ) + summary["belief_changed"].append(watch_id) for watch_id, row in existing.items(): - if watch_id not in incoming: - session.delete(row) - summary["removed"].append(watch_id) + if watch_id not in incoming and row.retired_at is None: + row.retired_at = now + summary["retired"].append(watch_id) session.flush() return summary diff --git a/src/processors/content_filter.py b/src/processors/content_filter.py deleted file mode 100644 index e38a389..0000000 --- a/src/processors/content_filter.py +++ /dev/null @@ -1,261 +0,0 @@ -""" -Content Filter for InsightWeaver - -Filters articles based on user preferences (sports, clickbait, etc.) -Uses hybrid approach: keyword matching + NLP heuristics -""" - -import re - - -class ContentFilter: - """Filter articles based on user profile content preferences""" - - # Sports keywords - only highly specific terms with no dual-use - SPORTS_KEYWORDS = { - # League names (highly specific) - "nfl", - "nba", - "mlb", - "nhl", - "mls", - "ncaa", - "fifa", - "uefa", - "premier league", - # Sport names - "football", - "basketball", - "baseball", - "hockey", - "soccer", - "tennis", - "golf", - "nascar", - "formula 1", - # Championship events - "super bowl", - "world series", - "stanley cup", - "playoffs", - "olympics", - # Position-specific terms - "touchdown", - "quarterback", - "pitcher", - "batter", - "goalie", - "striker", - "innings", - # Combat sports - "ufc", - "boxing match", - "wrestling match", - "mma fight", - } - - # Clickbait indicators - only unambiguous phrases - CLICKBAIT_KEYWORDS = { - "you won't believe", - "mind-blowing", - "jaw-dropping", - "goes viral", - "breaks the internet", - "what happens next", - "this one trick", - "doctors hate", - "experts hate", - "literally exploded", - "won the internet", - "everyone is talking about", - } - - # Celebrity/entertainment keywords - remove dual-use terms - ENTERTAINMENT_KEYWORDS = { - "celebrity", - "movie star", - "red carpet", - "oscars", - "grammys", - "emmys", - "kardashian", - "hollywood", - "fashion week", - "tiktok trend", - "instagram model", - "influencer drama", - "celebrity gossip", - "box office", - } - - def __init__(self, user_profile=None): - """ - Initialize content filter - - Args: - user_profile: UserProfile instance with excluded topics - """ - self.user_profile = user_profile - self.excluded_topics = [] - - if user_profile: - self.excluded_topics = [topic.lower() for topic in user_profile.get_excluded_topics()] - - def should_filter( - self, title: str, description: str = "", _content: str = "" - ) -> tuple[bool, str | None]: - """ - Determine if article should be filtered based on content - - Args: - title: Article title - description: Article description/summary - content: Full article content (optional) - - Returns: - Tuple of (should_filter: bool, reason: str) - """ - # Combine text for analysis - text = f"{title} {description}".lower() - - # Check user-specified excluded topics first - for topic in self.excluded_topics: - if topic in text: - return True, f"excluded_topic:{topic}" - - # Check for sports content - if self._is_sports_content(text): - return True, "sports" - - # Check for clickbait - if self._is_clickbait(title): - return True, "clickbait" - - # Check for entertainment/celebrity content - if self._is_entertainment_content(text): - return True, "entertainment" - - return False, None - - def _is_sports_content(self, text: str) -> bool: - """ - Detect sports content using keyword matching - - Args: - text: Lowercased text to analyze - - Returns: - True if sports content detected - """ - # Count sports keyword matches - matches = sum(1 for keyword in self.SPORTS_KEYWORDS if keyword in text) - - # Threshold: 2+ sports keywords = likely sports content - return matches >= 2 - - def _is_clickbait(self, title: str) -> bool: - """ - Detect clickbait using keywords + heuristics - - Args: - title: Article title - - Returns: - True if clickbait detected - """ - title_lower = title.lower() - - # Check for clickbait keywords - for keyword in self.CLICKBAIT_KEYWORDS: - if keyword in title_lower: - return True - - # Heuristic: Excessive punctuation - if title.count("!") >= 2 or title.count("?") >= 2: - return True - - # Heuristic: ALL CAPS words (excluding acronyms) - words = title.split() - all_caps_words = [w for w in words if w.isupper() and len(w) > 3] - if len(all_caps_words) >= 2: - return True - - # Heuristic: Numbers in clickbait patterns - clickbait_number_patterns = [ - r"\d+ (reasons|ways|things|tips|tricks)", - r"number \d+", - r"#\d+ will", - ] - return any(re.search(pattern, title_lower) for pattern in clickbait_number_patterns) - - def _is_entertainment_content(self, text: str) -> bool: - """ - Detect entertainment/celebrity content - - Args: - text: Lowercased text to analyze - - Returns: - True if entertainment content detected - """ - matches = sum(1 for keyword in self.ENTERTAINMENT_KEYWORDS if keyword in text) - - # Threshold: 1+ entertainment keywords = likely entertainment content - return matches >= 1 - - def filter_articles(self, articles: list) -> tuple[list, list]: - """ - Filter a list of articles, marking filtered ones - - Args: - articles: List of Article objects (SQLAlchemy models) - - Returns: - Tuple of (kept_articles, filtered_articles) - """ - kept = [] - filtered = [] - - for article in articles: - title = article.title or "" - description = article.description or "" - content = article.normalized_content or "" - - should_filter, reason = self.should_filter(title, description, content) - - if should_filter: - article.filtered = True - article.filter_reason = reason - filtered.append(article) - else: - kept.append(article) - - return kept, filtered - - def get_filter_stats(self, articles: list) -> dict: - """ - Get statistics about filtered articles - - Args: - articles: List of Article objects - - Returns: - Dict with filtering statistics - """ - total = len(articles) - filtered_count = sum(1 for a in articles if a.filtered) - - # Count by reason - reasons = {} - for article in articles: - if article.filtered and article.filter_reason: - reason = article.filter_reason - reasons[reason] = reasons.get(reason, 0) + 1 - - return { - "total_articles": total, - "filtered_count": filtered_count, - "kept_count": total - filtered_count, - "filter_rate": filtered_count / total if total > 0 else 0, - "reasons": reasons, - } diff --git a/src/processors/deduplicator.py b/src/processors/deduplicator.py deleted file mode 100644 index 698aec4..0000000 --- a/src/processors/deduplicator.py +++ /dev/null @@ -1,433 +0,0 @@ -""" -Article Deduplication System -Identifies and handles duplicate articles across different RSS feeds -""" - -import hashlib -import logging -from datetime import datetime, timedelta - -from sqlalchemy import and_ -from sqlalchemy.orm import Session - -from src.database.connection import get_db -from src.database.models import Article -from src.utils import utcnow - -logger = logging.getLogger(__name__) - - -class ArticleDeduplicator: - """Handles detection and management of duplicate articles""" - - def __init__(self, similarity_threshold: float = 0.85, time_window_hours: int = 72): - self.similarity_threshold = similarity_threshold - self.time_window_hours = time_window_hours - - def generate_content_hash(self, title: str, content: str) -> str: - """Generate a hash for article content for exact duplicate detection""" - if not title or not content: - return "" - - # Normalize content for comparison - normalized_title = self._normalize_text(title) - normalized_content = self._normalize_text(content) - - # Create combined hash - combined_text = f"{normalized_title}|{normalized_content}" - return hashlib.md5(combined_text.encode("utf-8")).hexdigest() - - def generate_title_hash(self, title: str) -> str: - """Generate a hash for article title for near-duplicate detection""" - if not title: - return "" - - normalized_title = self._normalize_text(title) - return hashlib.md5(normalized_title.encode("utf-8")).hexdigest() - - def _normalize_text(self, text: str) -> str: - """Normalize text for comparison (remove punctuation, lowercase, etc.)""" - if not text: - return "" - - # Convert to lowercase and remove extra whitespace - text = text.lower().strip() - - # Remove common punctuation and special characters - import re - - text = re.sub(r"[^\w\s]", "", text) - text = re.sub(r"\s+", " ", text) - - return text - - def find_exact_duplicates(self, article: Article, db: Session) -> list[Article]: - """Find exact duplicates based on content hash""" - if not article.title or not article.normalized_content: - return [] - - content_hash = self.generate_content_hash(article.title, article.normalized_content) - if not content_hash: - return [] - - # Store hash in article for comparison - if not hasattr(article, "_content_hash"): - article._content_hash = content_hash - - # Look for articles with same content hash within time window - time_cutoff = utcnow() - timedelta(hours=self.time_window_hours) - - # Much more efficient: limit the query and only get necessary fields - candidates = ( - db.query(Article.id, Article.title, Article.normalized_content, Article.fetched_at) - .filter( - and_( - Article.id != article.id, - Article.fetched_at >= time_cutoff, - Article.title.isnot(None), - Article.normalized_content.isnot(None), - ) - ) - .limit(1000) - .all() - ) # Reasonable limit to prevent runaway queries - - # Check content hash for each candidate - exact_duplicates = [] - for candidate_data in candidates: - candidate_hash = self.generate_content_hash( - candidate_data.title, candidate_data.normalized_content - ) - if candidate_hash == content_hash: - # Get full article object only for matches - full_candidate = db.query(Article).filter(Article.id == candidate_data.id).first() - if full_candidate: - exact_duplicates.append(full_candidate) - - return exact_duplicates - - def find_near_duplicates(self, article: Article, db: Session) -> list[Article]: - """Find near-duplicates based on title similarity and URL""" - if not article.title: - return [] - - near_duplicates = [] - time_cutoff = utcnow() - timedelta(hours=self.time_window_hours) - - # Find articles with same URL (different feeds might have same URL) - if article.url: - url_duplicates = ( - db.query(Article) - .filter( - and_( - Article.id != article.id, - Article.url == article.url, - Article.fetched_at >= time_cutoff, - ) - ) - .all() - ) - near_duplicates.extend(url_duplicates) - - # Find articles with very similar titles - much more efficient approach - title_hash = self.generate_title_hash(article.title) - if title_hash: - # Only get necessary fields for comparison - candidates = ( - db.query(Article.id, Article.title) - .filter( - and_( - Article.id != article.id, - Article.fetched_at >= time_cutoff, - Article.title.isnot(None), - ) - ) - .limit(500) - .all() - ) # Reasonable limit - - matched_ids = [] - for candidate_data in candidates: - if candidate_data.title: - candidate_hash = self.generate_title_hash(candidate_data.title) - if candidate_hash == title_hash: - matched_ids.append(candidate_data.id) - - # Get full articles only for matches, avoiding duplicates from URL check - if matched_ids: - existing_ids = {dup.id for dup in near_duplicates} - new_matches = ( - db.query(Article) - .filter(and_(Article.id.in_(matched_ids), ~Article.id.in_(existing_ids))) - .all() - ) - near_duplicates.extend(new_matches) - - return near_duplicates - - def mark_as_duplicate( - self, original_article: Article, duplicate_article: Article, _db: Session - ): - """Mark an article as a duplicate of another""" - # Add metadata to track duplication - if not duplicate_article.priority_metadata: - duplicate_article.priority_metadata = {} - - duplicate_article.priority_metadata.update( - { - "is_duplicate": True, - "duplicate_of": original_article.id, - "duplicate_detected_at": utcnow().isoformat(), - "duplicate_type": "exact" - if self._is_exact_duplicate(original_article, duplicate_article) - else "near", - } - ) - - # Lower priority score for duplicates - duplicate_article.priority_score = 0.1 - - logger.debug(f"Marked article {duplicate_article.id} as duplicate of {original_article.id}") - - def _is_exact_duplicate(self, article1: Article, article2: Article) -> bool: - """Check if two articles are exact duplicates""" - if not all( - [ - article1.title, - article1.normalized_content, - article2.title, - article2.normalized_content, - ] - ): - return False - - hash1 = self.generate_content_hash(article1.title, article1.normalized_content) - hash2 = self.generate_content_hash(article2.title, article2.normalized_content) - - return hash1 == hash2 and hash1 != "" - - def _stage1_url_duplicates( - self, db: Session, unprocessed_ids: list[int], _time_cutoff: datetime - ) -> dict[str, int]: - """ - Stage 1: Quick URL duplicate detection - instant wins - Groups articles by URL and marks later ones as duplicates - """ - # Get all articles with URLs in a single query - articles_with_urls = ( - db.query(Article) - .filter( - and_(Article.id.in_(unprocessed_ids), Article.url.isnot(None), Article.url != "") - ) - .order_by(Article.fetched_at.asc()) - .all() - ) - - # Group by URL and mark duplicates - url_groups = {} - for article in articles_with_urls: - if article.url not in url_groups: - url_groups[article.url] = [] - url_groups[article.url].append(article) - - url_duplicates = 0 - for _url, articles in url_groups.items(): - if len(articles) > 1: - # Keep the earliest, mark others as duplicates - original = articles[0] - for duplicate in articles[1:]: - # Skip if already marked as duplicate - if duplicate.priority_metadata and duplicate.priority_metadata.get( - "is_duplicate" - ): - continue - self.mark_as_duplicate(original, duplicate, db) - unprocessed_ids.remove(duplicate.id) # Remove from further processing - url_duplicates += 1 - - return {"url_duplicates": url_duplicates} - - def _stage2_exact_duplicates( - self, db: Session, unprocessed_ids: list[int], _time_cutoff: datetime - ) -> dict[str, int]: - """ - Stage 2: Exact content hash matches - fast hash-based detection - Only processes articles that survived Stage 1 - """ - # Get articles that need content hash comparison - remaining_articles = ( - db.query(Article) - .filter( - and_( - Article.id.in_(unprocessed_ids), - Article.title.isnot(None), - Article.normalized_content.isnot(None), - ) - ) - .order_by(Article.fetched_at.asc()) - .all() - ) - - # Group by content hash - hash_groups = {} - for article in remaining_articles: - # Skip if already marked as duplicate - if article.priority_metadata and article.priority_metadata.get("is_duplicate"): - continue - - content_hash = self.generate_content_hash(article.title, article.normalized_content) - if content_hash: - if content_hash not in hash_groups: - hash_groups[content_hash] = [] - hash_groups[content_hash].append(article) - - exact_duplicates = 0 - for _content_hash, articles in hash_groups.items(): - if len(articles) > 1: - # Keep the earliest, mark others as duplicates - original = articles[0] - for duplicate in articles[1:]: - self.mark_as_duplicate(original, duplicate, db) - if duplicate.id in unprocessed_ids: - unprocessed_ids.remove(duplicate.id) # Remove from further processing - exact_duplicates += 1 - - return {"exact_duplicates": exact_duplicates} - - def _stage3_title_similarity( - self, db: Session, unprocessed_ids: list[int], _time_cutoff: datetime - ) -> dict[str, int]: - """ - Stage 3: Title similarity analysis - slowest but most thorough - Only processes articles that survived Stages 1 & 2 - """ - # Get remaining articles that need title similarity comparison - remaining_articles = ( - db.query(Article) - .filter(and_(Article.id.in_(unprocessed_ids), Article.title.isnot(None))) - .order_by(Article.fetched_at.asc()) - .all() - ) - - # Group by title hash for similarity detection - title_hash_groups = {} - for article in remaining_articles: - # Skip if already marked as duplicate - if article.priority_metadata and article.priority_metadata.get("is_duplicate"): - continue - - title_hash = self.generate_title_hash(article.title) - if title_hash: - if title_hash not in title_hash_groups: - title_hash_groups[title_hash] = [] - title_hash_groups[title_hash].append(article) - - title_duplicates = 0 - for _title_hash, articles in title_hash_groups.items(): - if len(articles) > 1: - # Keep the earliest or most reliable source - original = articles[0] - for duplicate in articles[1:]: - self.mark_as_duplicate(original, duplicate, db) - title_duplicates += 1 - - return {"title_duplicates": title_duplicates} - - def deduplicate_recent_articles(self, hours: int = 24) -> dict[str, int]: - """ - Staged deduplication processing for optimal performance: - Stage 1: Quick URL duplicate detection - Stage 2: Exact content hash matches - Stage 3: Title similarity analysis - """ - time_cutoff = utcnow() - timedelta(hours=hours) - - with get_db() as db: - # Get recent articles that haven't been processed for duplicates - recent_articles_data = ( - db.query(Article.id, Article.priority_metadata) - .filter(Article.fetched_at >= time_cutoff) - .order_by(Article.fetched_at.desc()) - .all() - ) - - # Filter out already processed duplicates in Python - unprocessed_ids = [] - for article_data in recent_articles_data: - if not article_data.priority_metadata or not article_data.priority_metadata.get( - "is_duplicate" - ): - unprocessed_ids.append(article_data.id) - - logger.info(f"Starting staged deduplication of {len(unprocessed_ids)} articles") - - # STAGE 1: Quick URL duplicate detection (instant wins) - stage1_stats = self._stage1_url_duplicates(db, unprocessed_ids, time_cutoff) - logger.info(f"Stage 1 complete: {stage1_stats['url_duplicates']} URL duplicates found") - - # STAGE 2: Exact content hash matches (fast) - stage2_stats = self._stage2_exact_duplicates(db, unprocessed_ids, time_cutoff) - logger.info( - f"Stage 2 complete: {stage2_stats['exact_duplicates']} exact duplicates found" - ) - - # STAGE 3: Title similarity analysis (slower, but fewer candidates) - stage3_stats = self._stage3_title_similarity(db, unprocessed_ids, time_cutoff) - logger.info( - f"Stage 3 complete: {stage3_stats['title_duplicates']} title duplicates found" - ) - - # Final commit - db.commit() - - total_duplicates = ( - stage1_stats["url_duplicates"] - + stage2_stats["exact_duplicates"] - + stage3_stats["title_duplicates"] - ) - - logger.info( - f"Staged deduplication complete: {len(unprocessed_ids)} articles processed, " - f"{total_duplicates} total duplicates found" - ) - - return { - "processed_articles": len(unprocessed_ids), - "url_duplicates": stage1_stats["url_duplicates"], - "exact_duplicates": stage2_stats["exact_duplicates"], - "title_duplicates": stage3_stats["title_duplicates"], - "total_duplicates": total_duplicates, - } - - def get_duplicate_statistics(self) -> dict[str, int]: - """Get statistics about duplicates in the database""" - with get_db() as db: - total_articles = db.query(Article).count() - - # Count duplicates and originals in Python since SQLite JSON queries are limited - all_articles = db.query(Article).all() - duplicate_articles = 0 - original_articles = 0 - - for article in all_articles: - if article.priority_metadata: - if article.priority_metadata.get("is_duplicate"): - duplicate_articles += 1 - if article.priority_metadata.get("duplicate_of"): - original_articles += 1 - - return { - "total_articles": total_articles, - "duplicate_articles": duplicate_articles, - "original_articles": original_articles, - "unique_articles": total_articles - duplicate_articles, - "duplication_rate": duplicate_articles / total_articles - if total_articles > 0 - else 0.0, - } - - -def run_deduplication(hours: int = 24) -> dict[str, int]: - """Convenience function to run deduplication on recent articles""" - deduplicator = ArticleDeduplicator() - return deduplicator.deduplicate_recent_articles(hours=hours) diff --git a/src/routing/__init__.py b/src/routing/__init__.py new file mode 100644 index 0000000..28d4f7c --- /dev/null +++ b/src/routing/__init__.py @@ -0,0 +1,29 @@ +""" +Tier 1: deterministic routing of observations to watches. + +No model is involved anywhere in this package, and a test proves it by +blocking the import of ``src.llm`` while the full routing path runs. A watch's +trigger clauses compile to word-boundary regexes and a source-name test +(:mod:`~src.routing.compile`); the router evaluates them over a window of +observations and records the candidate pairs in ``routes`` +(:mod:`~src.routing.route`). Everything the adjudicator is later asked about +passes through here first, which is what keeps the model from seeing the bulk +of the corpus. + +Added 2026-09-22 for backlog task 028. +""" + +from .compile import CompiledClause, CompiledWatch, TriggerCompileError, compile_triggers +from .route import RoutingReport, UnroutedCluster, WatchRouting, live_watches, route + +__all__ = [ + "CompiledClause", + "CompiledWatch", + "RoutingReport", + "TriggerCompileError", + "UnroutedCluster", + "WatchRouting", + "compile_triggers", + "live_watches", + "route", +] diff --git a/src/routing/compile.py b/src/routing/compile.py new file mode 100644 index 0000000..29a7274 --- /dev/null +++ b/src/routing/compile.py @@ -0,0 +1,146 @@ +""" +Trigger clauses compiled to predicates. + +A watch's ``triggers`` is a list of clauses; a clause may populate ``terms``, +``entities`` and ``sources``. The semantics, restated so the compiler and the +file agree (``config/watches.example.yaml`` says the same thing to the author): + +* within a clause, **every** populated field must match; +* within a field, **any** value matches; +* any clause matching routes the observation, and the first that does is the + one recorded. + +``terms`` and ``entities`` compile identically, through +:func:`src.matching.entity_matcher.term_pattern` with its two load-bearing +rules: word boundaries (``CISA`` is not in ``precisa``) and the shouted-term +case rule (``BOD`` matches, ``body`` does not). There is no alias registry, so +an entity is a name until a watch needs aliases; that is its own task. +``sources`` is a case-insensitive exact match on the source's name. + +The loader in ``src/position/_validate.py`` already refuses a clause that is +prose, empty, or names an unknown field, so most of what this module could +reject never reaches it. It rejects again anyway (:class:`TriggerCompileError`), +because the row it compiles came from a table that ``sqlite3`` can write to. + +Added 2026-09-22 for backlog task 028. +""" + +from __future__ import annotations + +import re +from collections.abc import Iterable, Mapping, Sequence +from dataclasses import dataclass +from typing import Any + +from src.matching.entity_matcher import is_shouted, term_pattern +from src.position._validate import TRIGGER_FIELDS + +__all__ = ["CompiledClause", "CompiledWatch", "TriggerCompileError", "compile_triggers"] + + +class TriggerCompileError(ValueError): + """A stored trigger clause that cannot be compiled. Raised, never skipped.""" + + +def _compile_names(values: Sequence[str]) -> tuple[re.Pattern[str], ...]: + """ + One pattern per case group, as ``compile_entities`` does. + + Shouted terms (acronyms) match case-sensitively; everything else matches + case-insensitively. Grouping them into two alternations keeps each group on + the flag it needs. + """ + shouted = [term_pattern(v) for v in values if v.strip() and is_shouted(v)] + relaxed = [term_pattern(v) for v in values if v.strip() and not is_shouted(v)] + patterns: list[re.Pattern[str]] = [] + if shouted: + patterns.append(re.compile("|".join(shouted))) + if relaxed: + patterns.append(re.compile("|".join(relaxed), re.IGNORECASE)) + return tuple(patterns) + + +@dataclass(frozen=True) +class CompiledClause: + """One conjunctive clause. Empty fields are not constraints.""" + + index: int + terms: tuple[re.Pattern[str], ...] + entities: tuple[re.Pattern[str], ...] + sources: frozenset[str] + + def matches(self, text: str, source_name: str) -> bool: + return ( + (not self.sources or source_name.strip().lower() in self.sources) + and (not self.terms or any(p.search(text) for p in self.terms)) + and (not self.entities or any(p.search(text) for p in self.entities)) + ) + + +@dataclass(frozen=True) +class CompiledWatch: + """A watch's clauses, compiled once for reuse across every observation.""" + + watch_id: str + clauses: tuple[CompiledClause, ...] + + def first_match(self, text: str, source_name: str) -> int | None: + """The index of the first clause that fires, or None.""" + for clause in self.clauses: + if clause.matches(text, source_name): + return clause.index + return None + + +def _strings(watch_id: str, index: int, field_name: str, raw: Any) -> list[str]: + if raw is None: + return [] + if isinstance(raw, str) or not isinstance(raw, list | tuple): + raise TriggerCompileError( + f"watch '{watch_id}' clause {index}: '{field_name}' must be a list of strings, " + f"got {type(raw).__name__}" + ) + for value in raw: + if not isinstance(value, str): + raise TriggerCompileError( + f"watch '{watch_id}' clause {index}: '{field_name}' contains " + f"{type(value).__name__} {value!r}; every entry must be a string" + ) + return [v for v in raw if v.strip()] + + +def compile_triggers(watch_id: str, triggers: Iterable[Mapping[str, Any]] | None) -> CompiledWatch: + """Compile a watch's stored ``triggers`` JSON. Raises on anything uncompilable.""" + clauses: list[CompiledClause] = [] + for index, clause in enumerate(triggers or ()): + if not isinstance(clause, Mapping): + raise TriggerCompileError( + f"watch '{watch_id}' clause {index}: expected a mapping, " + f"got {type(clause).__name__}" + ) + unknown = sorted(set(clause) - set(TRIGGER_FIELDS)) + if unknown: + raise TriggerCompileError( + f"watch '{watch_id}' clause {index}: unknown field(s) {unknown}; " + f"a clause may constrain only {list(TRIGGER_FIELDS)}" + ) + compiled = CompiledClause( + index=index, + terms=_compile_names(_strings(watch_id, index, "terms", clause.get("terms"))), + entities=_compile_names(_strings(watch_id, index, "entities", clause.get("entities"))), + sources=frozenset( + s.strip().lower() + for s in _strings(watch_id, index, "sources", clause.get("sources")) + ), + ) + if not (compiled.terms or compiled.entities or compiled.sources): + raise TriggerCompileError( + f"watch '{watch_id}' clause {index} constrains nothing and would match " + f"every observation" + ) + clauses.append(compiled) + if not clauses: + raise TriggerCompileError( + f"watch '{watch_id}' has no trigger clauses; nothing can route to it" + ) + return CompiledWatch(watch_id=watch_id, clauses=tuple(clauses)) diff --git a/src/routing/route.py b/src/routing/route.py new file mode 100644 index 0000000..413dc34 --- /dev/null +++ b/src/routing/route.py @@ -0,0 +1,221 @@ +""" +The router: evaluate live watches over a window of observations. + +Reads ``observations`` (never ``articles``), the source name from the source +row, and ``watches.triggers``. Writes ``routes``. Idempotent: a pair already +linked is not linked again, so running twice produces one link per pair, and a +``--dry-run`` computes the same report without writing. + +The unrouted report is the coverage-gap signal, not a footnote. An observation +that routes to nothing is either noise, which is the common case and the point, +or a story no watch is written to catch. The two look identical as a count; +grouped by near-duplicate cluster and named by source, the second kind shows +up as one story carried by several outlets that nothing caught. + +Added 2026-09-22 for backlog task 028. +""" + +from __future__ import annotations + +from collections.abc import Sequence +from dataclasses import dataclass, field +from datetime import date, datetime + +from sqlalchemy import and_, or_ +from sqlalchemy.orm import Session + +from src.config.settings import settings +from src.database.models import Observation, Route, RSSFeed, Watch +from src.position.ledger import live_clause +from src.sources.minhash import group_near_duplicates +from src.sources.observation import observation_text + +from .compile import CompiledWatch, compile_triggers + +__all__ = ["RoutingReport", "UnroutedCluster", "WatchRouting", "live_watches", "route"] + +# How many unrouted clusters the report carries. The count is always complete; +# only the listing is bounded, and the report says how many it left out. +CLUSTERS_SHOWN = 10 + +# The near-duplicate grouper is pairwise, O(n^2), sized for a day of ingestion +# (src/sources/minhash.py). Above this many unrouted observations the report +# skips clustering and says so, rather than running for hours on a rebuild; +# the per-source counts and the total are still complete. +CLUSTER_LIMIT = 2000 + + +@dataclass(frozen=True) +class WatchRouting: + watch_id: str + new: int # links written (or that would be written) this run + total: int # observations in the window that route to this watch + + +@dataclass(frozen=True) +class UnroutedCluster: + size: int + sources: tuple[str, ...] + title: str + hashes: tuple[str, ...] + + +@dataclass +class RoutingReport: + since: datetime + rebuild: bool + observations: int # rows routed: the window, or the whole corpus on rebuild + watches: list[WatchRouting] = field(default_factory=list) + unrouted: int = 0 + unrouted_by_source: list[tuple[str, int]] = field(default_factory=list) + clusters: list[UnroutedCluster] = field(default_factory=list) + clusters_omitted: int = 0 + clustering_skipped: int = 0 # unrouted observations left unclustered, over CLUSTER_LIMIT + written: bool = False + + @property + def routed(self) -> int: + return self.observations - self.unrouted + + +def live_watches(db: Session, today: date) -> list[CompiledWatch]: + """ + Every watch routing may link to, compiled. + + Live means not expired, not retired and not resolved; the definition is + :func:`src.position.ledger.live_clause` and this is one of its readers. + """ + rows = db.query(Watch.id, Watch.triggers).filter(live_clause(today)).order_by(Watch.id) + return [compile_triggers(str(watch_id), triggers) for watch_id, triggers in rows.all()] + + +def _window(db: Session, since: datetime | None): + """Observations in the window, with their source name, in hash order.""" + query = db.query( + Observation.content_hash, + Observation.payload, + Observation.minhash, + Observation.published_date, + Observation.observed_at, + RSSFeed.name, + ).join(RSSFeed, RSSFeed.id == Observation.source_id) + if since is not None: + # published_date can be null for feeds that carry no date; those rows + # fall back to when we first saw them rather than dropping out. + query = query.filter( + or_( + Observation.published_date >= since, + and_(Observation.published_date.is_(None), Observation.observed_at >= since), + ) + ) + return query.order_by(Observation.content_hash).all() + + +def route( + db: Session, + *, + since: datetime, + today: date, + write: bool = True, + rebuild: bool = False, +) -> RoutingReport: + """ + Route the window's observations to the live watches. + + ``rebuild`` discards every existing link for the live watches and routes + the whole corpus, ignoring ``since`` for routing; it is how a changed + trigger takes effect on observations already stored. Without it, links are + only added. The unrouted report always describes the window, rebuild or + not, because that is the period whose coverage gap the operator is reading. + """ + watches = live_watches(db, today) + watch_ids = [w.watch_id for w in watches] + + if rebuild and write: + db.query(Route).filter(Route.watch_id.in_(watch_ids)).delete(synchronize_session=False) + db.flush() + + rows = _window(db, None if rebuild else since) + existing: set[tuple[str, str]] = set() + if watch_ids and not rebuild: + existing = { + (str(h), str(w)) + for h, w in db.query(Route.observation_hash, Route.watch_id) + .filter(Route.watch_id.in_(watch_ids)) + .all() + } + + new = dict.fromkeys(watch_ids, 0) + total = dict.fromkeys(watch_ids, 0) + unrouted: dict[str, tuple[int, ...]] = {} + details: dict[str, tuple[str, str]] = {} + + for content_hash, payload, minhash, published_date, observed_at, source_name in rows: + text = observation_text(payload) + matched = False + for watch in watches: + index = watch.first_match(text, str(source_name or "")) + if index is None: + continue + matched = True + total[watch.watch_id] += 1 + if (content_hash, watch.watch_id) in existing: + continue + new[watch.watch_id] += 1 + if write: + db.add( + Route( + observation_hash=content_hash, + watch_id=watch.watch_id, + clause_index=index, + ) + ) + if not matched and (published_date or observed_at) >= since: + unrouted[content_hash] = tuple(minhash) + details[content_hash] = (str(source_name), str(payload.get("title") or "")) + + if write: + db.flush() + + report = RoutingReport( + since=since, + rebuild=rebuild, + observations=len(rows), + watches=[WatchRouting(w, new[w], total[w]) for w in watch_ids], + unrouted=len(unrouted), + written=write, + ) + _cluster(report, unrouted, details) + return report + + +def _cluster( + report: RoutingReport, + unrouted: dict[str, tuple[int, ...]], + details: dict[str, tuple[str, str]], +) -> None: + """Group the unrouted observations by near-duplicate signature, largest first.""" + if not unrouted: + return + by_source: dict[str, int] = {} + for source, _title in details.values(): + by_source[source] = by_source.get(source, 0) + 1 + report.unrouted_by_source = sorted(by_source.items(), key=lambda kv: (-kv[1], kv[0])) + if len(unrouted) > CLUSTER_LIMIT: + report.clustering_skipped = len(unrouted) + return + groups: Sequence[Sequence[str]] = group_near_duplicates( + unrouted, settings.near_duplicate_threshold + ) + clusters = [] + for group in groups: + hashes = tuple(sorted(group)) + sources = tuple(sorted({details[h][0] for h in hashes})) + clusters.append( + UnroutedCluster( + size=len(hashes), sources=sources, title=details[hashes[0]][1], hashes=hashes + ) + ) + clusters.sort(key=lambda c: (-c.size, c.hashes[0])) + report.clusters = clusters[:CLUSTERS_SHOWN] + report.clusters_omitted = max(0, len(clusters) - CLUSTERS_SHOWN) diff --git a/src/rss/fetcher.py b/src/rss/fetcher.py index f8b1154..580afb1 100644 --- a/src/rss/fetcher.py +++ b/src/rss/fetcher.py @@ -5,9 +5,6 @@ import feedparser import httpx from bs4 import BeautifulSoup -from sqlalchemy.orm import Session - -from src.database.models import RSSFeed logger = logging.getLogger(__name__) @@ -207,20 +204,3 @@ async def _fetch_with_retry( await asyncio.sleep(backoff_time) return False, None, f"Failed after {self.max_retries} attempts: {last_error}" - - -def create_test_feed( - db: Session, - name: str = "NASA Breaking News", - url: str = "https://www.nasa.gov/rss/dyn/breaking_news.rss", -) -> RSSFeed: - """Create a test RSS feed for development""" - existing = db.query(RSSFeed).filter(RSSFeed.url == url).first() - if existing: - return existing - - feed = RSSFeed(name=name, url=url, category="news", is_active=True) - db.add(feed) - db.commit() - db.refresh(feed) - return feed diff --git a/src/rss/parallel_fetcher.py b/src/rss/parallel_fetcher.py deleted file mode 100644 index b429b92..0000000 --- a/src/rss/parallel_fetcher.py +++ /dev/null @@ -1,217 +0,0 @@ -""" -Parallel RSS Fetcher with rate limiting and error handling -Efficiently processes multiple RSS feeds concurrently -""" - -import asyncio -import logging -import time -from dataclasses import dataclass - -from src.database.models import RSSFeed -from src.rss.fetcher import LEGACY_PATH_MESSAGE, LegacyWritePathClosed, RSSFetcher -from src.utils import utcnow - -logger = logging.getLogger(__name__) - - -@dataclass -class FetchResult: - """Result of fetching a single RSS feed""" - - feed_id: int - feed_name: str - success: bool - articles_count: int - error_message: str | None - fetch_time: float - - -class ParallelRSSFetcher: - """Fetches multiple RSS feeds in parallel with rate limiting""" - - def __init__( - self, max_concurrent_feeds: int = 10, requests_per_second: float = 2.0, timeout: int = 30 - ): - self.max_concurrent_feeds = max_concurrent_feeds - self.requests_per_second = requests_per_second - self.timeout = timeout - self.rate_limiter = asyncio.Semaphore(max_concurrent_feeds) - self.last_request_time = 0.0 - - async def _rate_limited_fetch(self, fetcher: RSSFetcher, feed: RSSFeed) -> FetchResult: - """Fetch a single feed with rate limiting""" - async with self.rate_limiter: - # Rate limiting: ensure minimum time between requests - current_time = time.time() - time_since_last = current_time - self.last_request_time - min_interval = 1.0 / self.requests_per_second - - if time_since_last < min_interval: - sleep_time = min_interval - time_since_last - await asyncio.sleep(sleep_time) - - self.last_request_time = time.time() - - # Fetch the feed - start_time = time.time() - try: - success, articles_count, error = await fetcher.fetch_and_store_feed(feed.id) - fetch_time = time.time() - start_time - - return FetchResult( - feed_id=feed.id, - feed_name=feed.name, - success=success, - articles_count=articles_count, - error_message=error, - fetch_time=fetch_time, - ) - - except Exception as e: - fetch_time = time.time() - start_time - logger.error(f"Unexpected error fetching {feed.name}: {e}") - - return FetchResult( - feed_id=feed.id, - feed_name=feed.name, - success=False, - articles_count=0, - error_message=f"Unexpected error: {str(e)}", - fetch_time=fetch_time, - ) - - async def fetch_all_feeds(self, feeds: list[RSSFeed]) -> dict[str, any]: - """ - Fetch all feeds in parallel with rate limiting - Returns summary statistics and results - """ - if not feeds: - logger.warning("No feeds provided for fetching") - return self._empty_results() - - start_time = time.time() - logger.info(f"Starting parallel fetch of {len(feeds)} feeds...") - - # Create fetcher instance - fetcher = RSSFetcher(timeout=self.timeout) - - try: - # Create tasks for all feeds - tasks = [self._rate_limited_fetch(fetcher, feed) for feed in feeds] - - # Execute all tasks concurrently - results = await asyncio.gather(*tasks, return_exceptions=True) - - # Process results - fetch_results = [] - for result in results: - if isinstance(result, Exception): - logger.error(f"Task exception: {result}") - # Create a failed result for exceptions - fetch_results.append( - FetchResult( - feed_id=0, - feed_name="Unknown", - success=False, - articles_count=0, - error_message=str(result), - fetch_time=0.0, - ) - ) - else: - fetch_results.append(result) - - total_time = time.time() - start_time - - # Generate summary - summary = self._generate_summary(fetch_results, total_time) - - logger.info( - f"Parallel fetch completed in {total_time:.2f}s: " - f"{summary['successful_feeds']}/{summary['total_feeds']} successful, " - f"{summary['total_articles']} articles" - ) - - return summary - - finally: - await fetcher.close() - - def _generate_summary(self, results: list[FetchResult], total_time: float) -> dict[str, any]: - """Generate summary statistics from fetch results""" - successful_feeds = sum(1 for r in results if r.success) - failed_feeds = len(results) - successful_feeds - total_articles = sum(r.articles_count for r in results) - - # Calculate timing statistics - successful_times = [r.fetch_time for r in results if r.success] - avg_fetch_time = sum(successful_times) / len(successful_times) if successful_times else 0.0 - - # Group errors - error_summary = {} - for result in results: - if not result.success and result.error_message: - # Simplify error message for grouping - error_type = ( - result.error_message.split(":")[0] - if ":" in result.error_message - else result.error_message - ) - error_summary[error_type] = error_summary.get(error_type, 0) + 1 - - # Feeds that succeeded but got no articles - empty_feeds = [r for r in results if r.success and r.articles_count == 0] - - return { - "total_feeds": len(results), - "successful_feeds": successful_feeds, - "failed_feeds": failed_feeds, - "total_articles": total_articles, - "total_time": total_time, - "avg_fetch_time": avg_fetch_time, - "articles_per_second": total_articles / total_time if total_time > 0 else 0, - "feeds_per_second": len(results) / total_time if total_time > 0 else 0, - "error_summary": error_summary, - "empty_feeds": [f.feed_name for f in empty_feeds], - "failed_feeds_list": [f.feed_name for f in results if not f.success], - "timestamp": utcnow().isoformat(), - } - - def _empty_results(self) -> dict[str, any]: - """Return empty results structure""" - return { - "total_feeds": 0, - "successful_feeds": 0, - "failed_feeds": 0, - "total_articles": 0, - "total_time": 0.0, - "avg_fetch_time": 0.0, - "articles_per_second": 0.0, - "feeds_per_second": 0.0, - "error_summary": {}, - "empty_feeds": [], - "failed_feeds_list": [], - "timestamp": utcnow().isoformat(), - } - - -# ARG001: both arguments are unused on purpose, for the same reason as -# RSSFetcher.fetch_and_store_feed -- an existing caller should hit the refusal, -# not a TypeError about an argument that used to exist (2026-08-31, task 025). -async def fetch_all_active_feeds( - max_concurrent: int = 10, # noqa: ARG001 - rate_limit: float = 2.0, # noqa: ARG001 -) -> dict[str, any]: - """ - Closed. Always raises :class:`~src.rss.fetcher.LegacyWritePathClosed`. - - This is the function an operator reaches for to refresh the corpus, and - every article it produced arrived through ``fetch_and_store_feed``, which - no longer writes (backlog task 025, 2026-08-31). It refuses here rather - than further down for one reason: ``_rate_limited_fetch`` catches every - exception per feed and folds it into a summary dict, so a raise underneath - would return normally with "0 of 44 feeds succeeded" and a zero exit code - -- the same quiet nothing-happened this task exists to remove. - """ - raise LegacyWritePathClosed(LEGACY_PATH_MESSAGE) diff --git a/src/sources/__init__.py b/src/sources/__init__.py index 3392b2b..7df3b30 100644 --- a/src/sources/__init__.py +++ b/src/sources/__init__.py @@ -4,9 +4,10 @@ Added 2026-08-26 for backlog task 005. The seam is deliberately narrow -- an adapter turns *some upstream* into :class:`~src.sources.base.RawItem` values that carry exactly the field set ``RSSFetcher.normalize_article()`` -already produces. Everything downstream of the ``articles`` table -(deduplication, filtering, clustering, frames, questions, predictions, -synthesis) is untouched and has no idea an adapter exists. +already produces. Everything downstream of the store path (routing, +adjudication, the brief) reads observations and has no idea an adapter +exists. The briefing-era consumers this sentence used to list were deleted +on 2026-08-31 (task 012) and 2026-09-22 (task 027). Amended 2026-08-31 (backlog task 014): the same store path now also writes an immutable, content-addressed :class:`~src.database.models.Observation` for every diff --git a/src/sources/base.py b/src/sources/base.py index d80bde2..2c58b24 100644 --- a/src/sources/base.py +++ b/src/sources/base.py @@ -70,9 +70,11 @@ def normalize_for_hash(text: str) -> str: """ Lowercase, strip punctuation, collapse whitespace. - Matches ``ArticleDeduplicator._normalize_text`` so that a hash computed at - ingestion time and a hash computed later by the deduplicator agree about - what counts as "the same text". + This is the normalization every stored content hash was computed with. It + originally matched the pairwise deduplicator's ``_normalize_text`` so the + two agreed about what counts as "the same text"; that module was deleted on + 2026-09-22 (backlog task 027), and the rule stays exactly as it was because + changing it would silently re-identify every observation already stored. """ if not text: return "" diff --git a/src/sources/minhash.py b/src/sources/minhash.py index 3af831c..9aed508 100644 --- a/src/sources/minhash.py +++ b/src/sources/minhash.py @@ -9,9 +9,10 @@ That is the failure this module exists to prevent. **Why MinHash and not the existing similarity code.** -``src/processors/deduplicator.py`` compares articles pairwise with a word-set -Jaccard computed from scratch on every comparison, inside a time window, at -query time. It is not wrong, but nothing about it is storable: there is no +``src/processors/deduplicator.py`` (deleted 2026-09-22, backlog task 027; superseded +by the module below) compared articles pairwise with a word-set Jaccard computed +from scratch on every comparison, inside a time window, at query time. It was not +wrong, but nothing about it was storable: it left no per-article artefact you can keep and compare later, so the grouping cannot be recomputed identically after the fact. A MinHash signature *is* that artefact. It is a fixed-width function of the text alone, written once beside the diff --git a/src/sources/observation.py b/src/sources/observation.py index 0cd3c65..e8ff68a 100644 --- a/src/sources/observation.py +++ b/src/sources/observation.py @@ -57,6 +57,7 @@ "near_duplicate_groups", "observation_hash", "observation_payload", + "observation_text", "observe", "store_observation", ] @@ -112,13 +113,19 @@ def observation_hash(payload: dict[str, Any]) -> str: return content_hash(*(_render(payload[key]) for key in OBSERVATION_FIELDS)) -def minhash_text(payload: dict[str, Any]) -> str: +def observation_text(payload: dict[str, Any]) -> str: """ - The text a near-duplicate signature is computed over: title plus body. - - ``normalized_content`` is preferred over ``description`` because it is the - HTML-stripped full text; ``description`` is the fallback for feeds that - carry only a summary. + The words every reader of an observation sees: title plus body. + + One definition, two readers: the near-duplicate signature written at + insert and Tier 1 routing (backlog task 028), so that a match found by one + is a match the other can see. The adjudicator receives the same title and + body as two labelled fields of the same payload + (:class:`~src.evidence.adjudicator.ObservationView`) rather than this + joined string. ``normalized_content`` is preferred over ``description`` + because it is the HTML-stripped full text; ``description`` is the fallback + for feeds that carry only a summary. Renamed on 2026-09-22 when it gained + its second reader. """ body = payload.get("normalized_content") or payload.get("description") or "" return f"{payload.get('title') or ''} {body}".strip() @@ -140,7 +147,7 @@ def observe(source_url: str, item: RawItem) -> ObservationRecord: return ObservationRecord( content_hash=observation_hash(payload), payload=payload, - minhash=signature(minhash_text(payload)), + minhash=signature(observation_text(payload)), published_date=item.published_date, ) diff --git a/src/sources/rss_adapter.py b/src/sources/rss_adapter.py index b7628b0..754885b 100644 --- a/src/sources/rss_adapter.py +++ b/src/sources/rss_adapter.py @@ -2,13 +2,15 @@ The existing RSS fetcher, wrapped in the adapter contract. This module adds *no* behaviour: ``src/rss/fetcher.py`` is not modified and not -subclassed, and the live pipeline still fetches feeds through -``fetch_all_active_feeds`` exactly as before. What is new is a second way to -*read* an RSS feed -- returning :class:`~src.sources.base.RawItem` values -instead of writing rows -- so that RSS and the Federal Register API are the -same kind of thing to any caller. - -Added 2026-08-26 for backlog task 005. +subclassed. It is a way to *read* an RSS feed -- returning +:class:`~src.sources.base.RawItem` values instead of writing rows -- so that +RSS and the Federal Register API are the same kind of thing to any caller. + +Added 2026-08-26 for backlog task 005 as a second reader beside +``fetch_all_active_feeds``. That path was closed on 2026-08-31 (task 025) and +deleted on 2026-09-22 (task 027); since task 028 the same day, ``insightweaver +ingest`` reads every configured RSS feed through this adapter and the one +store path. """ from __future__ import annotations @@ -70,6 +72,18 @@ async def fetch(self, since: datetime) -> list[RawItem]: entries = getattr(feed_data, "entries", None) or [] feed_info = getattr(feed_data, "feed", None) or {} + if not getattr(feed_data, "version", ""): + # feedparser leaves ``version`` empty when the document is not a + # feed of any kind: a 200 carrying a landing page, a challenge + # page, JSON. That is not "a quiet day"; recorded as a success it + # would clear the source's error and list it in the brief as a + # feed that ran and returned nothing. Raise instead. A feed with + # parse warnings (``bozo``) but a recognised version is still a + # feed (2026-09-23, backlog task 031 review). + problem = getattr(feed_data, "bozo_exception", None) + raise SourceUnavailable( + self.name, "response is not a feed" + (f": {problem}" if problem else "") + ) items: list[RawItem] = [] skipped = 0 diff --git a/src/sources/runner.py b/src/sources/runner.py index 0dc9472..a7a62c7 100644 --- a/src/sources/runner.py +++ b/src/sources/runner.py @@ -24,6 +24,7 @@ from __future__ import annotations +import asyncio import logging from collections.abc import Callable, Iterator, Sequence from contextlib import AbstractContextManager @@ -38,7 +39,8 @@ from ..utils import utcnow from .base import SourceAdapter, SourceUnavailable from .federal_register import FederalRegisterAdapter, FederalRegisterConfigError -from .store import ensure_source, source_article_count, store_items +from .rss_adapter import RSSAdapter +from .store import ensure_source, record_attempt, source_article_count, store_items logger = logging.getLogger(__name__) @@ -148,17 +150,21 @@ async def run_adapter( except SourceUnavailable as exc: result.error = exc.reason logger.error(f"SOURCE UNREACHABLE: {adapter.name} - {exc.reason}") - _record_error(db_factory, source_id, exc.reason) + _record_outcome(db_factory, source_id, exc.reason) return result except Exception as exc: # noqa: BLE001 - an adapter bug is still an outage result.error = f"unexpected {type(exc).__name__}: {exc}" logger.error(f"SOURCE FAILED: {adapter.name} - {result.error}") - _record_error(db_factory, source_id, result.error) + _record_outcome(db_factory, source_id, result.error) return result result.fetched = len(items) if not items: + # The source ran and answered. Record that, or the brief cannot tell + # a source that returned nothing from one that never ran; QUIET names + # the former by this timestamp (2026-09-22, backlog task 031). + _record_outcome(db_factory, source_id, None) if prior_articles > 0: result.went_silent = True logger.error( @@ -187,44 +193,60 @@ async def run_adapter( return result -def _record_error(db_factory: DbFactory, source_id: int, reason: str) -> None: - """Write the failure onto the source row so it is visible outside the log.""" +def _record_outcome(db_factory: DbFactory, source_id: int, error: str | None) -> None: + """Write the attempt's outcome onto the source row so it is visible outside the log.""" from ..database.models import RSSFeed with db_factory() as db: row = db.query(RSSFeed).filter(RSSFeed.id == source_id).first() - if row is None: - return - # Column[...] vs value, as in src/sources/store.py. - row.last_fetched = utcnow() # type: ignore[assignment] - row.last_error = reason # type: ignore[assignment] - row.error_count = int(row.error_count or 0) + 1 # type: ignore[assignment] + if row is not None: + record_attempt(row, error=error) async def run_adapters( adapters: Sequence[SourceAdapter], since: datetime, db_factory: DbFactory = get_db, + *, + concurrency: int = 1, ) -> AdapterRunSummary: - """Run adapters one after another. Sequential on purpose: these are guests - on public APIs and the whole set is a handful of requests.""" - summary = AdapterRunSummary() - for adapter in adapters: - summary.results.append(await run_adapter(adapter, since, db_factory=db_factory)) + """ + Run adapters, at most ``concurrency`` at a time, and keep their order. + + Sequential was right for two API adapters that are guests on public + services. It is not right for dozens of RSS feeds with thirty-second + timeouts, so ``ingest`` passes a small bound (2026-09-22, backlog task + 028). Database work inside :func:`run_adapter` happens between awaits, + never across one, so sessions never interleave mid-transaction whatever + the bound. + """ + if concurrency < 1: + raise ValueError(f"concurrency must be at least 1, got {concurrency}") + semaphore = asyncio.Semaphore(concurrency) + + async def one(adapter: SourceAdapter) -> IngestResult: + async with semaphore: + return await run_adapter(adapter, since, db_factory=db_factory) + + results = await asyncio.gather(*(one(adapter) for adapter in adapters)) + summary = AdapterRunSummary(results=list(results)) for line in summary.alerts: logger.error(f"SOURCE ALERT: {line}") return summary -def build_configured_adapters(feeds_dir: Path | str | None = None) -> list[SourceAdapter]: +def build_configured_adapters( + feeds_dir: Path | str | None = None, *, include_rss: bool = False +) -> list[SourceAdapter]: """ - Instantiate an adapter for every configured non-RSS source. - - RSS feeds were excluded here because ``fetch_all_active_feeds`` owned them. - That path was closed on 2026-08-31 (backlog task 025) because it wrote - articles without observations; RSS feeds are still excluded from *this* - function, which only builds the non-RSS adapters named in config, and are - now read through ``src.sources.rss_adapter.RSSAdapter`` instead. + Instantiate an adapter for every configured source. + + Non-RSS sources always; RSS feeds too when ``include_rss`` is set, one + :class:`~src.sources.rss_adapter.RSSAdapter` per feed in ``config/feeds/``. + RSS was excluded here while ``fetch_all_active_feeds`` owned it; that path + was closed on 2026-08-31 (backlog task 025) because it wrote articles + without observations, and since 2026-09-22 (task 028) ``ingest`` reads + every feed through this function and the one store path. """ adapters: list[SourceAdapter] = [] for name in sorted(non_rss_adapter_names(feeds_dir)): @@ -240,6 +262,12 @@ def build_configured_adapters(feeds_dir: Path | str | None = None) -> list[Sourc adapters.append(factory()) except FederalRegisterConfigError as exc: raise ValueError(f"adapter '{name}' is configured but unusable: {exc}") + if include_rss: + for feed in _configured_feeds(feeds_dir): + if feed.adapter != "rss": + continue + category = feed.domain_tags[0] if feed.domain_tags else "uncategorized" + adapters.append(RSSAdapter(name=feed.name, url=feed.url, category=category)) return adapters @@ -248,17 +276,6 @@ def non_rss_adapter_names(feeds_dir: Path | str | None = None) -> set[str]: return {feed.adapter for feed in _configured_feeds(feeds_dir) if feed.adapter != "rss"} -def non_rss_source_urls(feeds_dir: Path | str | None = None) -> set[str]: - """ - URLs in ``config/feeds/`` that are not RSS. - - ``src/rss/parallel_fetcher.py`` uses this to leave them alone: handing a - JSON API endpoint to feedparser would produce a parse failure every run and - eventually auto-deactivate the source. - """ - return {feed.url for feed in _configured_feeds(feeds_dir) if feed.adapter != "rss"} - - def _configured_feeds(feeds_dir: Path | str | None = None) -> Iterator: """Every configured feed, read from an absolute path by default.""" directory = Path(feeds_dir) if feeds_dir is not None else DEFAULT_FEEDS_DIR @@ -269,13 +286,16 @@ async def run_configured_adapters( since: datetime | None = None, feeds_dir: Path | str | None = None, db_factory: DbFactory = get_db, + *, + include_rss: bool = False, + concurrency: int = 1, ) -> AdapterRunSummary: - """Run every configured non-RSS source. Used by the pipeline's fetch stage.""" - adapters = build_configured_adapters(feeds_dir) + """Run every configured source (non-RSS only unless ``include_rss``).""" + adapters = build_configured_adapters(feeds_dir, include_rss=include_rss) if not adapters: return AdapterRunSummary() window_start = since or (utcnow() - timedelta(days=DEFAULT_LOOKBACK_DAYS)) - logger.info( - f"Running {len(adapters)} non-RSS source adapter(s) since {window_start.isoformat()}" + logger.info(f"Running {len(adapters)} source adapter(s) since {window_start.isoformat()}") + return await run_adapters( + adapters, window_start, db_factory=db_factory, concurrency=concurrency ) - return await run_adapters(adapters, window_start, db_factory=db_factory) diff --git a/src/sources/store.py b/src/sources/store.py index c8aba82..55987c5 100644 --- a/src/sources/store.py +++ b/src/sources/store.py @@ -116,12 +116,28 @@ def store_items(db: Session, source: RSSFeed, items: Iterable[RawItem]) -> tuple if observations: logger.info(f"{source.name}: stored {observations} new observation(s)") - source.last_fetched = utcnow() # type: ignore[assignment] - source.last_error = None # type: ignore[assignment] - source.error_count = 0 # type: ignore[assignment] + record_attempt(source, error=None) return inserted, duplicates +def record_attempt(source: RSSFeed, *, error: str | None) -> None: + """ + Stamp the source row with the outcome of the fetch that just ran. + + ``last_fetched`` is the time of the last *attempt*, success or failure; + ``last_error`` is that attempt's error, or None when it succeeded, with or + without items. The row does not keep the time of the last success once a + failure has overwritten it, and the brief's header says so by labelling + the stamp "last attempt failed" when ``last_error`` is set. One function + for the three writers (items stored, nothing returned, failure) so they + cannot drift (2026-09-23, backlog task 031). + """ + # Column[...] vs value: the models use the pre-2.0 Column() style. + source.last_fetched = utcnow() # type: ignore[assignment] + source.last_error = error # type: ignore[assignment] + source.error_count = 0 if error is None else int(source.error_count or 0) + 1 # type: ignore[assignment] + + def source_article_count(db: Session, source: RSSFeed) -> int: """How many articles this source has ever contributed.""" return int(db.query(Article.id).filter(Article.feed_id == source.id).count()) diff --git a/src/utils/colors.py b/src/utils/colors.py deleted file mode 100644 index 91bc69a..0000000 --- a/src/utils/colors.py +++ /dev/null @@ -1,71 +0,0 @@ -""" -Terminal color palette - hacker aesthetic -Centralized color definitions for consistent CLI styling -""" - -import click - -# Color constants -ACCENT = "bright_green" -HEADER = "cyan" -SUCCESS = "green" -WARNING = "yellow" -ERROR = "red" -MUTED = "bright_black" -EMPHASIS = "bright_white" - - -def header(text: str) -> str: - """Style section header (cyan, bold)""" - return click.style(text, fg=HEADER, bold=True) - - -def accent(text: str) -> str: - """Style primary accent text (bright green)""" - return click.style(text, fg=ACCENT) - - -def success(text: str) -> str: - """Style success message (green)""" - return click.style(text, fg=SUCCESS) - - -def warning(text: str) -> str: - """Style warning message (yellow)""" - return click.style(text, fg=WARNING) - - -def error(text: str) -> str: - """Style error message (red)""" - return click.style(text, fg=ERROR) - - -def muted(text: str) -> str: - """Style secondary/muted text (gray)""" - return click.style(text, fg=MUTED) - - -def emphasis(text: str) -> str: - """Style emphasized text (bright white, bold)""" - return click.style(text, fg=EMPHASIS, bold=True) - - -def colorize_priority(priority: str) -> str: - """Colorize priority level tags""" - priority_upper = priority.upper() - if priority_upper in ("CRITICAL", "HIGH"): - return click.style(f"[{priority_upper}]", fg=ERROR, bold=True) - elif priority_upper == "MEDIUM": - return click.style(f"[{priority_upper}]", fg=WARNING) - else: - return click.style(f"[{priority_upper}]", fg=MUTED) - - -def colorize_confidence(score: float) -> str: - """Colorize confidence score based on value""" - if score >= 0.8: - return click.style(f"{score:.0%}", fg=SUCCESS) - elif score >= 0.5: - return click.style(f"{score:.0%}", fg=WARNING) - else: - return click.style(f"{score:.0%}", fg=ERROR) diff --git a/src/utils/logging.py b/src/utils/logging.py deleted file mode 100644 index 8671284..0000000 --- a/src/utils/logging.py +++ /dev/null @@ -1,228 +0,0 @@ -""" -Structured Logging Configuration for InsightWeaver - -Provides: -- JSON formatting for production -- Log rotation with size limits -- Contextual logging with structured data -- Multiple output handlers (file, console, JSON) -""" - -import json -import logging -import logging.handlers -import sys -from typing import Any - -from src.config.settings import settings - - -class JSONFormatter(logging.Formatter): - """ - Custom JSON formatter for structured logging - Outputs log records as JSON for easy parsing and analysis - """ - - def format(self, record: logging.LogRecord) -> str: - """Format log record as JSON""" - log_data: dict[str, Any] = { - "timestamp": self.formatTime(record, self.datefmt), - "level": record.levelname, - "logger": record.name, - "message": record.getMessage(), - "module": record.module, - "function": record.funcName, - "line": record.lineno, - } - - # Add exception info if present - if record.exc_info: - log_data["exception"] = self.formatException(record.exc_info) - - # Add extra fields if present - if hasattr(record, "extra_fields"): - log_data.update(record.extra_fields) - - return json.dumps(log_data) - - -class StructuredLogger(logging.LoggerAdapter): - """ - Logger adapter for adding contextual information to logs - - Usage: - logger = get_logger(__name__) - logger.info("Processing item", extra_fields={"item_id": 123, "status": "active"}) - """ - - def process(self, msg: str, kwargs: dict[str, Any]) -> tuple[str, dict[str, Any]]: - """Add extra_fields to the log record""" - extra_fields = kwargs.pop("extra_fields", {}) - if "extra" not in kwargs: - kwargs["extra"] = {} - kwargs["extra"]["extra_fields"] = extra_fields - return msg, kwargs - - -def setup_logging(json_output: bool = False) -> logging.Logger: - """ - Configure application logging with rotation and structured output - - Args: - json_output: If True, use JSON formatting for file output - - Returns: - Configured logger instance - """ - # Create logs directory if it doesn't exist - settings.logs_dir.mkdir(exist_ok=True, parents=True) - - # Remove existing handlers to avoid duplicates - root_logger = logging.getLogger() - root_logger.handlers.clear() - - # Set root logger level - log_level = getattr(logging, settings.log_level.upper(), logging.INFO) - root_logger.setLevel(log_level) - - # Console handler (human-readable) - console_handler = logging.StreamHandler(sys.stdout) - console_handler.setLevel(log_level) - console_format = logging.Formatter( - fmt="%(asctime)s - %(name)s - %(levelname)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S" - ) - console_handler.setFormatter(console_format) - root_logger.addHandler(console_handler) - - # Rotating file handler (prevents log files from growing too large) - log_file = settings.logs_dir / "insightweaver.log" - file_handler = logging.handlers.RotatingFileHandler( - filename=log_file, - maxBytes=10 * 1024 * 1024, # 10 MB - backupCount=5, # Keep 5 backup files - encoding="utf-8", - ) - file_handler.setLevel(log_level) - - # Use JSON formatter for file if requested - if json_output: - file_handler.setFormatter(JSONFormatter()) - else: - file_handler.setFormatter(console_format) - - root_logger.addHandler(file_handler) - - # JSON-only log file (always JSON format for easy parsing) - json_log_file = settings.logs_dir / "insightweaver.json.log" - json_handler = logging.handlers.RotatingFileHandler( - filename=json_log_file, - maxBytes=10 * 1024 * 1024, # 10 MB - backupCount=5, - encoding="utf-8", - ) - json_handler.setLevel(log_level) - json_handler.setFormatter(JSONFormatter()) - root_logger.addHandler(json_handler) - - # Set specific log levels for third-party libraries - logging.getLogger("urllib3").setLevel(logging.WARNING) - logging.getLogger("httpx").setLevel(logging.WARNING) - logging.getLogger("httpcore").setLevel(logging.WARNING) - logging.getLogger("sqlalchemy.engine").setLevel(logging.WARNING) - logging.getLogger("anthropic").setLevel(logging.INFO) - - logger = logging.getLogger(__name__) - logger.info( - "Logging configured successfully", extra={"extra_fields": {"json_output": json_output}} - ) - - return logger - - -def get_logger(name: str) -> StructuredLogger: - """ - Get a structured logger instance - - Args: - name: Logger name (usually __name__) - - Returns: - StructuredLogger instance with contextual logging support - - Example: - logger = get_logger(__name__) - logger.info("User action", extra_fields={"user_id": 123, "action": "login"}) - """ - base_logger = logging.getLogger(name) - return StructuredLogger(base_logger, {}) - - -def log_execution_time(func): - """ - Decorator to log function execution time - - Usage: - @log_execution_time - async def my_function(): - ... - """ - import functools - import time - - @functools.wraps(func) - async def async_wrapper(*args, **kwargs): - logger = get_logger(func.__module__) - start_time = time.time() - try: - result = await func(*args, **kwargs) - elapsed = time.time() - start_time - logger.info( - f"{func.__name__} completed", - extra_fields={"duration_seconds": elapsed, "function": func.__name__}, - ) - return result - except Exception as e: - elapsed = time.time() - start_time - logger.error( - f"{func.__name__} failed", - extra_fields={ - "duration_seconds": elapsed, - "function": func.__name__, - "error": str(e), - }, - exc_info=True, - ) - raise - - @functools.wraps(func) - def sync_wrapper(*args, **kwargs): - logger = get_logger(func.__module__) - start_time = time.time() - try: - result = func(*args, **kwargs) - elapsed = time.time() - start_time - logger.info( - f"{func.__name__} completed", - extra_fields={"duration_seconds": elapsed, "function": func.__name__}, - ) - return result - except Exception as e: - elapsed = time.time() - start_time - logger.error( - f"{func.__name__} failed", - extra_fields={ - "duration_seconds": elapsed, - "function": func.__name__, - "error": str(e), - }, - exc_info=True, - ) - raise - - # Return appropriate wrapper based on whether function is async - import asyncio - - if asyncio.iscoroutinefunction(func): - return async_wrapper - else: - return sync_wrapper diff --git a/src/utils/profile_loader.py b/src/utils/profile_loader.py deleted file mode 100644 index 2a9cf98..0000000 --- a/src/utils/profile_loader.py +++ /dev/null @@ -1,342 +0,0 @@ -""" -User Profile Loader for InsightWeaver - -Loads and manages user context profiles for personalized narrative synthesis. -Implements fail-fast approach - requires actual user_profile.json to exist. -""" - -import json -from pathlib import Path - - -class ProfileValidationError(Exception): - """Raised when user profile is missing required fields""" - - pass - - -class UserProfile: - """Manages user context profile for personalized intelligence synthesis""" - - # Required top-level sections - REQUIRED_SECTIONS = { - "geographic_context", - "professional_context", - "civic_interests", - "personal_priorities", - "content_preferences", - } - - # Required fields within each section - REQUIRED_FIELDS = { - "geographic_context": {"primary_location"}, - "professional_context": {"professional_domains"}, - "content_preferences": {"excluded_topics"}, - } - - def __init__(self, profile_path: str | None = None): - """ - Initialize profile loader - - Args: - profile_path: Path to user_profile.json (defaults to config/user_profile.json) - """ - if profile_path is None: - # Default to config/user_profile.json relative to project root - project_root = Path(__file__).parent.parent.parent - profile_path = project_root / "config" / "user_profile.json" - - self.profile_path = Path(profile_path) - self._profile_data: dict | None = None - - def _validate_profile(self, profile_data: dict) -> None: - """ - Validate that profile contains required sections and fields - - Args: - profile_data: Loaded profile dictionary - - Raises: - ProfileValidationError: If required sections or fields are missing - """ - missing_sections = self.REQUIRED_SECTIONS - set(profile_data.keys()) - if missing_sections: - raise ProfileValidationError( - f"User profile missing required sections: {', '.join(missing_sections)}" - ) - - # Validate required fields within each section - for section, required_fields in self.REQUIRED_FIELDS.items(): - if section in profile_data: - section_data = profile_data[section] - missing_fields = required_fields - set(section_data.keys()) - if missing_fields: - raise ProfileValidationError( - f"Section '{section}' missing required fields: {', '.join(missing_fields)}" - ) - - def load_profile(self) -> dict: - """ - Load user profile from JSON file - - Returns: - Dict containing full profile data - - Raises: - FileNotFoundError: If user_profile.json does not exist (fail-fast) - json.JSONDecodeError: If profile JSON is malformed - ProfileValidationError: If required sections or fields are missing - """ - if not self.profile_path.exists(): - raise FileNotFoundError( - f"User profile not found at {self.profile_path}. " - f"Please create config/user_profile.json from the example template. " - f"See config/user_profile.example.json" - ) - - with open(self.profile_path, encoding="utf-8") as f: - self._profile_data = json.load(f) - - # Validate profile structure - self._validate_profile(self._profile_data) - - return self._profile_data - - @property - def profile(self) -> dict: - """Get cached profile data, load if not already loaded""" - if self._profile_data is None: - self.load_profile() - return self._profile_data - - def get_geographic_context(self) -> dict: - """Extract geographic context from profile""" - return self.profile.get("geographic_context", {}) - - def get_professional_context(self) -> dict: - """Extract professional context from profile""" - return self.profile.get("professional_context", {}) - - def get_civic_interests(self) -> dict: - """Extract civic interests from profile""" - return self.profile.get("civic_interests", {}) - - def get_personal_priorities(self) -> dict: - """Extract personal priorities from profile""" - return self.profile.get("personal_priorities", {}) - - def get_content_preferences(self) -> dict: - """Extract content preferences from profile""" - return self.profile.get("content_preferences", {}) - - def get_excluded_topics(self) -> list[str]: - """Get list of topics to exclude from analysis""" - return self.get_content_preferences().get("excluded_topics", []) - - def get_professional_domains(self) -> list[str]: - """Get list of professional domains for relevance scoring""" - return self.get_professional_context().get("professional_domains", []) - - def get_primary_location(self) -> dict: - """Get primary location (city, state, region)""" - return self.get_geographic_context().get("primary_location", {}) - - def get_complexity_level(self) -> str: - """Get preferred content complexity level""" - return self.get_content_preferences().get("complexity_level", "balanced") - - def get_voting_context(self) -> dict: - """ - Get voting context (districts, precinct, address) - - Returns dict with keys: - - registered_state: Two-letter state code (e.g., "VA") - - county_fips: FIPS code for county - - congressional_district: e.g., "VA-11" - - state_senate_district: State senate district number - - state_house_district: State house/delegate district number - - school_district: School district name - - address: Dict with street, city, state, zip - """ - return self.profile.get("voting_context", {}) - - def get_civic_preferences(self) -> dict: - """ - Get civic tracking preferences - - Returns dict with keys: - - track_elections: bool - - track_meetings: bool - - track_public_comments: bool - - track_budget_hearings: bool - - track_zoning: bool - - advance_notice_days: int (default 7) - """ - return self.profile.get("civic_preferences", {}) - - def get_active_decisions(self) -> list[dict]: - """ - Get list of active decisions in structured format - - Supports both old format (list of strings) and new format (list of dicts). - Old format is converted to new format for consistency. - - Returns list of dicts with keys: - - name: Decision name/description - - key_factors: List of factors to track - - decision_type: Type (career, housing, education, financial, civic) - - created_at: When the decision was added - """ - priorities = self.get_personal_priorities() - decisions = priorities.get("active_decisions", []) - - # Normalize to structured format - normalized = [] - for decision in decisions: - if isinstance(decision, str): - # Old format: convert string to dict - normalized.append( - { - "name": decision, - "key_factors": [], - "decision_type": self._infer_decision_type(decision), - "created_at": None, - } - ) - elif isinstance(decision, dict): - # New format: ensure all fields present - normalized.append( - { - "name": decision.get("name", "Unknown"), - "key_factors": decision.get("key_factors", []), - "decision_type": decision.get( - "decision_type", self._infer_decision_type(decision.get("name", "")) - ), - "created_at": decision.get("created_at"), - } - ) - - return normalized - - def _infer_decision_type(self, name: str) -> str: - """Infer decision type from name if not specified.""" - name_lower = name.lower() - if any(kw in name_lower for kw in ["career", "job", "work", "salary", "role"]): - return "career" - elif any(kw in name_lower for kw in ["housing", "home", "apartment", "rent", "mortgage"]): - return "housing" - elif any(kw in name_lower for kw in ["school", "education", "learning", "degree"]): - return "education" - elif any(kw in name_lower for kw in ["money", "invest", "financial", "savings"]): - return "financial" - elif any(kw in name_lower for kw in ["vote", "election", "policy", "civic"]): - return "civic" - return "other" - - def get_districts(self) -> list[str]: - """ - Get list of all electoral districts for the user - - Returns list like ["VA-11", "SD-32", "HD-36"] - """ - voting = self.get_voting_context() - districts = [] - if cd := voting.get("congressional_district"): - districts.append(cd) - if sd := voting.get("state_senate_district"): - districts.append(f"SD-{sd}") - if hd := voting.get("state_house_district"): - districts.append(f"HD-{hd}") - return districts - - def has_voting_context(self) -> bool: - """Check if user has configured voting context""" - voting = self.get_voting_context() - return bool(voting.get("registered_state") or voting.get("address")) - - def format_for_agent_context(self) -> str: - """ - Format profile as contextual string for agent system prompts - - Returns: - Formatted string suitable for inclusion in agent prompts - """ - # Extract key context elements - location = self.get_primary_location() - # Handle both string and dict formats for primary_location - if isinstance(location, str): - location_str = location - elif isinstance(location, dict): - location_str = f"{location.get('city', '')}, {location.get('state', '')}" - else: - location_str = "Unknown" - - prof_context = self.get_professional_context() - role = prof_context.get("job_role", "") - industry = prof_context.get("industry", "") - domains = ", ".join(self.get_professional_domains()) - - civic = self.get_civic_interests() - engagement = civic.get("political_engagement_level", "moderate") - policy_areas = ", ".join(civic.get("policy_areas", [])[:3]) - - priorities = self.get_personal_priorities() - priority_topics = ", ".join(priorities.get("priority_topics", [])[:5]) - - excluded = ", ".join(self.get_excluded_topics()) - - context_str = f"""USER CONTEXT PROFILE: - -Location: {location_str} -Professional Role: {role} in {industry} -Professional Domains: {domains} -Civic Engagement: {engagement} - Focus on {policy_areas} -Priority Topics: {priority_topics} -Excluded Topics: {excluded} -Content Complexity: {self.get_complexity_level()} - -Use this context to filter, prioritize, and frame all analysis through the user's specific circumstances and interests.""" - - return context_str - - def __repr__(self) -> str: - location = self.get_primary_location() - role = self.get_professional_context().get("job_role", "Unknown") - # Handle both string and dict formats for primary_location - if isinstance(location, str): - location_str = location - elif isinstance(location, dict): - location_str = location.get("city", "Unknown") - else: - location_str = "Unknown" - return f"" - - -# Singleton instance for easy access throughout the application -_global_profile: UserProfile | None = None - - -def get_user_profile() -> UserProfile: - """ - Get global UserProfile instance (singleton pattern) - - Returns: - UserProfile instance - """ - global _global_profile - if _global_profile is None: - _global_profile = UserProfile() - return _global_profile - - -def reload_profile() -> UserProfile: - """ - Force reload of user profile (useful for testing or after profile updates) - - Returns: - Newly loaded UserProfile instance - """ - global _global_profile - _global_profile = UserProfile() - _global_profile.load_profile() - return _global_profile diff --git a/src/utils/profiler.py b/src/utils/profiler.py deleted file mode 100644 index 998b8aa..0000000 --- a/src/utils/profiler.py +++ /dev/null @@ -1,124 +0,0 @@ -""" -Performance Profiler for InsightWeaver -Thread-safe timing instrumentation for identifying bottlenecks -""" - -import threading -import time -from contextlib import contextmanager -from datetime import datetime - - -class PerformanceProfiler: - """Thread-safe performance profiler for timing operations""" - - def __init__(self): - self._operations: list[dict] = [] - self._lock = threading.Lock() - self._start_time = None - - @contextmanager - def profile(self, operation_name: str, **metadata): - """Context manager for timing operations""" - start = time.perf_counter() - try: - yield - finally: - duration = time.perf_counter() - start - with self._lock: - self._operations.append( - { - "operation": operation_name, - "duration": duration, - "timestamp": datetime.now(), - "metadata": metadata, - } - ) - - def start_session(self): - """Start timing session""" - self._start_time = time.perf_counter() - - def get_summary(self) -> dict: - """Get performance summary""" - if not self._operations: - return {} - - total_time = time.perf_counter() - self._start_time if self._start_time else 0 - - # Group by operation name - grouped = {} - for op in self._operations: - name = op["operation"] - if name not in grouped: - grouped[name] = [] - grouped[name].append(op["duration"]) - - # Calculate stats - summary = [] - for name, durations in grouped.items(): - summary.append( - { - "operation": name, - "count": len(durations), - "total": sum(durations), - "avg": sum(durations) / len(durations), - "min": min(durations), - "max": max(durations), - "pct": (sum(durations) / total_time * 100) if total_time > 0 else 0, - } - ) - - # Sort by total time - summary.sort(key=lambda x: x["total"], reverse=True) - - return { - "total_time": total_time, - "total_operations": len(self._operations), - "breakdown": summary, - } - - def print_summary(self): - """Print formatted summary""" - summary = self.get_summary() - - if not summary: - print("\nNo profiling data collected") - return - - print("\n" + "=" * 80) - print("PERFORMANCE PROFILE") - print("=" * 80) - print(f"Total Time: {summary['total_time']:.2f}s") - print(f"Total Operations: {summary['total_operations']}") - print() - print(f"{'Operation':<40} {'Count':>6} {'Total':>10} {'Avg':>10} {'%':>6}") - print("-" * 80) - - for item in summary["breakdown"]: - print( - f"{item['operation']:<40} {item['count']:>6} " - f"{item['total']:>9.2f}s {item['avg']:>9.2f}s {item['pct']:>5.1f}%" - ) - - def reset(self): - """Reset profiler state""" - with self._lock: - self._operations.clear() - self._start_time = None - - -# Global profiler instance -_profiler = PerformanceProfiler() - - -def get_profiler(): - """Get the global profiler instance""" - return _profiler - - -@contextmanager -def profile(operation: str, **metadata): - """Convenience function for profiling""" - with _profiler.profile(operation, **metadata): - yield diff --git a/src/processors/__init__.py b/tests/brief/__init__.py similarity index 100% rename from src/processors/__init__.py rename to tests/brief/__init__.py diff --git a/tests/brief/fixtures/agency_newsroom.xml b/tests/brief/fixtures/agency_newsroom.xml new file mode 100644 index 0000000..1e14f26 --- /dev/null +++ b/tests/brief/fixtures/agency_newsroom.xml @@ -0,0 +1,8 @@ + + + + Agency Newsroom + https://example.com/newsroom + Reachable, well-formed, and empty: the source that ran and returned nothing. + + diff --git a/tests/brief/fixtures/compliance_weekly.xml b/tests/brief/fixtures/compliance_weekly.xml new file mode 100644 index 0000000..6a34e4c --- /dev/null +++ b/tests/brief/fixtures/compliance_weekly.xml @@ -0,0 +1,22 @@ + + + + Compliance Weekly + https://example.com/compliance-weekly + A two-item feed for the brief's end-to-end test (2026-09-22): a reprint of a Federal Register notice under its own title, and an item no watch wants. + + Traffic and Conduct on the Grounds of Certain National Institute of Standards and Technology Sites + https://example.com/compliance-weekly/nist-site-rules + By this rule, NIST amends its regulations governing traffic and conduct at its sites in Gaithersburg, Maryland, and Boulder and Fort Collins, Colorado. This rule amends those regulations by removing excessive and redundant restrictions on personal conduct, updating or removing sections with outdated references or requirements, and broadening an exception regarding the use of service dogs. This action is necessary to ensure that NIST's regulations conform to the scope of the underlying statutory authorities and to reduce regulatory complexity, redundancy, and burden. This action is intended to promote statutory conformity, administrative efficiency, and accessibility for people with disabilities, without imposing any new obligations or costs on the public. + Fri, 21 Aug 2026 14:30:00 GMT + compliance-weekly-2026-08-21-nist + + + Persimmons ripen after the first frost + https://example.com/compliance-weekly/persimmons + Fall fruit guidance for the county extension office: pick after the first frost, and let the astringent varieties soften fully before eating. + Thu, 20 Aug 2026 09:00:00 GMT + compliance-weekly-2026-08-20-persimmons + + + diff --git a/tests/brief/fixtures/position.yaml b/tests/brief/fixtures/position.yaml new file mode 100644 index 0000000..dfd6152 --- /dev/null +++ b/tests/brief/fixtures/position.yaml @@ -0,0 +1,13 @@ +# The Position for the brief's end-to-end test. Fictional; the shape of +# config/position.example.yaml. Frozen "today" in the test is 2026-08-24. +version: 1 +reviewed: 2026-08-01 +decisions: + - key: schedule-site-visit + name: Schedule the NIST site visit before or after the conduct rule changes + deadline: 2026-09-10 + stake: Two travel days and the assessor's calendar, against a visit under rules that change mid-stay. + - key: renew-authorization + name: Renew the authorization or let it lapse + deadline: 2027-03-31 + stake: Two engineer-quarters against 40% of federal revenue. diff --git a/tests/brief/fixtures/watches.yaml b/tests/brief/fixtures/watches.yaml new file mode 100644 index 0000000..afff336 --- /dev/null +++ b/tests/brief/fixtures/watches.yaml @@ -0,0 +1,36 @@ +# Three watches for the brief's end-to-end test, chosen so that the recorded +# Federal Register week (tests/sources/fixtures/federal_register_week.json) +# routes to two of them and to none of the third. +version: 1 +watches: + - id: nist-site-rules-loosen + claim: NIST relaxes the conduct rules at its sites before the visit is scheduled. + belief: 0.3 + so_what: + decision: schedule-site-visit + because: A looser regime changes what the visit has to cover and who can attend. + triggers: + - terms: ["National Institute of Standards and Technology", "NIST"] + expires: 2026-09-15 + staleness_alert_days: 14 + - id: opm-benefit-forms-change + claim: OPM reopens comment on the retirement benefit application forms. + belief: 0.5 + so_what: + decision: renew-authorization + because: A changed form set moves the renewal's paperwork estimate. + triggers: + - terms: ["Application for Death Benefits"] + - terms: ["Court-Ordered Benefits"] + expires: 2027-03-31 + staleness_alert_days: 30 + - id: dfars-cyber-reporting + claim: DFARS adds a cyber incident reporting collection before the renewal. + belief: 0.2 + so_what: + decision: renew-authorization + because: A new collection is a new control family to evidence. + triggers: + - terms: ["cyber incident reporting"] + expires: 2027-01-31 + staleness_alert_days: 7 diff --git a/tests/brief/golden/brief.md b/tests/brief/golden/brief.md new file mode 100644 index 0000000..1553563 --- /dev/null +++ b/tests/brief/golden/brief.md @@ -0,0 +1,34 @@ +# Brief as of 2026-08-24 06:00 +window: since 2026-08-17 06:00 +position: reviewed 2026-08-01 (23 days ago) +sources: 4 configured, 3 fetched, 1 failed, 0 never fetched (--verbose for every source) +- Broken Feed: LAST ATTEMPT FAILED 2026-08-24 06:00: HTTP error: connection refused; 0 in window + +## MOVED +- nist-site-rules-loosen: NIST relaxes the conduct rules at its sites before the visit is scheduled. + - supports 0.80 2026-08-21 Federal Register - Documents API: Traffic and Conduct on the Grounds of Certain National Institute of Standards and Technology Sites [sha256:841e04c37028, claude-v1] (+1 near-duplicate) + - also supports 0.80 2026-08-21 Compliance Weekly: Traffic and Conduct on the Grounds of Certain National Institute of Standards and Technology Sites [sha256:8f54b09130d9, claude-v1] +- opm-benefit-forms-change: OPM reopens comment on the retirement benefit application forms. + - supports 0.55 2026-08-20 Federal Register - Documents API: Submission for Review: 3206-0156, Application for Death Benefits Under the Civil Service Retirement System, (SF 2800); Documentation in Support of Application for Death Benefits When Deceased was an Employee at the Time of Death, (SF 2800A) and Applying for Death Benefits Under CSRS Pamphlet, (SF 2800-1) [sha256:c2fcbdff3a66, claude-v1] + +## DUE +- decision schedule-site-visit: Schedule the NIST site visit before or after the conduct rule changes (2026-09-10, 17 days) + - stake: Two travel days and the assessor's calendar, against a visit under rules that change mid-stay. +- watch nist-site-rules-loosen: NIST relaxes the conduct rules at its sites before the visit is scheduled. (expires 2026-09-15, 22 days) + +## WATCHING +- dfars-cyber-reporting: belief 0.20 (file, 2026-08-24); serves renew-authorization; expires in 160 days; evidence in window 0, last never + - DFARS adds a cyber incident reporting collection before the renewal. +- nist-site-rules-loosen: belief 0.30 (file, 2026-08-24); serves schedule-site-visit; expires in 22 days; evidence in window 2, last 2026-08-24 + - NIST relaxes the conduct rules at its sites before the visit is scheduled. +- opm-benefit-forms-change: belief 0.50 (file, 2026-08-24); serves renew-authorization; expires in 219 days; evidence in window 1, last 2026-08-24 + - OPM reopens comment on the retirement benefit application forms. + +## QUIET +watches with nothing routed inside their staleness window: 1 +- dfars-cyber-reporting: never routed (alert after 7 days) +sources that ran in the window and returned nothing: 1 +- Agency Newsroom (never produced) +routed pairs no adjudication has answered: 0 +failed adjudications in the window: 1 +- sha256:ebf02a3e9ea4 / opm-benefit-forms-change [claude-v1]: Model declined the request (category: scripted) diff --git a/tests/brief/golden/brief.txt b/tests/brief/golden/brief.txt new file mode 100644 index 0000000..7af79cc --- /dev/null +++ b/tests/brief/golden/brief.txt @@ -0,0 +1,38 @@ +BRIEF AS OF 2026-08-24 06:00 +window: since 2026-08-17 06:00 +position: reviewed 2026-08-01 (23 days ago) +sources: 4 configured, 3 fetched, 1 failed, 0 never fetched (--verbose for every source) +* Broken Feed: LAST ATTEMPT FAILED 2026-08-24 06:00: HTTP error: connection refused; 0 in window + +MOVED +----- +* nist-site-rules-loosen: NIST relaxes the conduct rules at its sites before the visit is scheduled. + * supports 0.80 2026-08-21 Federal Register - Documents API: Traffic and Conduct on the Grounds of Certain National Institute of Standards and Technology Sites [sha256:841e04c37028, claude-v1] (+1 near-duplicate) + * also supports 0.80 2026-08-21 Compliance Weekly: Traffic and Conduct on the Grounds of Certain National Institute of Standards and Technology Sites [sha256:8f54b09130d9, claude-v1] +* opm-benefit-forms-change: OPM reopens comment on the retirement benefit application forms. + * supports 0.55 2026-08-20 Federal Register - Documents API: Submission for Review: 3206-0156, Application for Death Benefits Under the Civil Service Retirement System, (SF 2800); Documentation in Support of Application for Death Benefits When Deceased was an Employee at the Time of Death, (SF 2800A) and Applying for Death Benefits Under CSRS Pamphlet, (SF 2800-1) [sha256:c2fcbdff3a66, claude-v1] + +DUE +--- +* decision schedule-site-visit: Schedule the NIST site visit before or after the conduct rule changes (2026-09-10, 17 days) + * stake: Two travel days and the assessor's calendar, against a visit under rules that change mid-stay. +* watch nist-site-rules-loosen: NIST relaxes the conduct rules at its sites before the visit is scheduled. (expires 2026-09-15, 22 days) + +WATCHING +-------- +* dfars-cyber-reporting: belief 0.20 (file, 2026-08-24); serves renew-authorization; expires in 160 days; evidence in window 0, last never + * DFARS adds a cyber incident reporting collection before the renewal. +* nist-site-rules-loosen: belief 0.30 (file, 2026-08-24); serves schedule-site-visit; expires in 22 days; evidence in window 2, last 2026-08-24 + * NIST relaxes the conduct rules at its sites before the visit is scheduled. +* opm-benefit-forms-change: belief 0.50 (file, 2026-08-24); serves renew-authorization; expires in 219 days; evidence in window 1, last 2026-08-24 + * OPM reopens comment on the retirement benefit application forms. + +QUIET +----- +watches with nothing routed inside their staleness window: 1 +* dfars-cyber-reporting: never routed (alert after 7 days) +sources that ran in the window and returned nothing: 1 +* Agency Newsroom (never produced) +routed pairs no adjudication has answered: 0 +failed adjudications in the window: 1 +* sha256:ebf02a3e9ea4 / opm-benefit-forms-change [claude-v1]: Model declined the request (category: scripted) diff --git a/tests/brief/rows.py b/tests/brief/rows.py new file mode 100644 index 0000000..e54fcae --- /dev/null +++ b/tests/brief/rows.py @@ -0,0 +1,106 @@ +""" +Row builders for the selector tests, shared by ``test_select.py`` and +``test_select_quiet.py``. Every row takes an explicit timestamp; nothing here +reads the wall clock. + +Added 2026-09-23 for backlog task 031. +""" + +from __future__ import annotations + +from datetime import date, datetime + +from src.brief.select import select_brief +from src.database.models import ( + Adjudication, + Evidence, + Observation, + Route, + RSSFeed, + Watch, + WatchBelief, +) +from src.position.position import Position + +AS_OF = datetime(2026, 9, 20, 6, 0) +SINCE = datetime(2026, 9, 13, 6, 0) + + +def _add(session, row): + session.add(row) + session.flush() + return row + + +def _source(session, name, last_fetched=None, last_error=None): + row = RSSFeed(name=name, url=f"u:{name}", last_fetched=last_fetched, last_error=last_error) + return _add(session, row) + + +def _obs(session, suffix, source_id, title, published, observed_at, minhash): + row = Observation( + content_hash=f"sha256:{suffix.ljust(64, '0')}", + source_id=source_id, + payload={"title": title}, + minhash=minhash, + published_date=published, + observed_at=observed_at, + ) + return _add(session, row) + + +def _watch(session, watch_id, **overrides): + fields = { + "id": watch_id, + "claim": f"claim for {watch_id}", + "belief": 0.4, + "decision_key": "renew-authorization", + "so_what": "matters", + "triggers": [{"terms": ["x"]}], + "expires": date(2027, 1, 1), + "staleness_alert_days": 14, + } + fields.update(overrides) + return _add(session, Watch(**fields)) + + +def _evidence(session, obs_hash, watch_id, created_at, prompt_version="v1"): + row = Evidence( + observation_hash=obs_hash, + watch_id=watch_id, + direction="supports", + magnitude=0.5, + prompt_version=prompt_version, + created_at=created_at, + ) + return _add(session, row) + + +def _route(session, obs_hash, watch_id, routed_at): + row = Route(observation_hash=obs_hash, watch_id=watch_id, clause_index=0, routed_at=routed_at) + return _add(session, row) + + +def _belief(session, watch_id, belief, observed_at): + row = WatchBelief(watch_id=watch_id, belief=belief, source="principal", observed_at=observed_at) + return _add(session, row) + + +def _adjudication(session, obs_hash, watch_id, created_at, outcome="failed", error=None): + row = Adjudication( + observation_hash=obs_hash, + watch_id=watch_id, + prompt_version="v1", + outcome=outcome, + error=error, + created_at=created_at, + ) + return _add(session, row) + + +def _position(reviewed, *decisions): + return Position(path=None, version=1, decisions=tuple(decisions), reviewed=reviewed) + + +def _select(session, position=None, **kw): + return select_brief(session, as_of=AS_OF, since=SINCE, position=position, **kw) diff --git a/tests/brief/test_end_to_end.py b/tests/brief/test_end_to_end.py new file mode 100644 index 0000000..9a9caf2 --- /dev/null +++ b/tests/brief/test_end_to_end.py @@ -0,0 +1,272 @@ +""" +The morning, end to end, against a committed golden file. + +Recorded fixtures go through the real commands -- ``watch sync``, ``ingest``, +``route``, ``adjudicate`` with a scripted model client, ``brief`` -- and the +rendered bytes are compared with ``tests/brief/golden/``. Nothing here opens a +socket or reads a key. + +The clock is frozen at ``NOW`` by replacing the ``datetime`` class that +``src.utils.utcnow`` reads, which every column default and every command's +window goes through. Without that, ``last_fetched``, the belief ledger and the +evidence timestamps would carry the wall clock into the golden file. + +To regenerate the golden files after a deliberate change to the brief, run +``make golden`` and read the diff before committing it. A golden that changes +by accident is the test doing its job. + +Added 2026-09-22 for backlog task 031. +""" + +from __future__ import annotations + +import asyncio +import json +import os +from contextlib import contextmanager +from datetime import UTC, date, datetime +from pathlib import Path +from unittest.mock import AsyncMock, MagicMock, patch + +import httpx +import pytest +from click.testing import CliRunner + +from src.cli.adjudicate import adjudicate_command +from src.cli.brief import brief_command +from src.cli.ingest import ingest_command +from src.cli.route import route_command +from src.cli.watch import watch_command +from src.database.models import Adjudication, BriefRun, Evidence, Observation, Route +from src.evidence.claude_adjudicator import ClaudeAdjudicator +from src.llm.claude_client import ModelCallFailed, ModelResponse +from src.position import load_position, load_watches +from src.rss.fetcher import RSSFetcher +from src.sources.federal_register import ( + FederalRegisterAdapter, + FederalRegisterFilter, + FederalRegisterQuery, +) +from src.sources.rss_adapter import RSSAdapter +from tests.sources.conftest import json_responder, make_client + +HERE = Path(__file__).parent +FIXTURES = HERE / "fixtures" +GOLDEN = HERE / "golden" +FR_WEEK = HERE.parent / "sources" / "fixtures" / "federal_register_week.json" + +# A Monday morning after the recorded Federal Register week (2026-08-17 to 21). +NOW = datetime(2026, 8, 24, 6, 0) +AS_OF = NOW.isoformat() +UPDATE_GOLDEN = "INSIGHTWEAVER_UPDATE_GOLDEN" + + +class _FrozenDatetime(datetime): + @classmethod + def now(cls, tz=None): # noqa: ARG003 - the signature datetime.now has + return NOW.replace(tzinfo=UTC) if tz is not None else NOW + + +@pytest.fixture +def frozen_clock(monkeypatch): + monkeypatch.setattr("src.utils.datetime", _FrozenDatetime) + return NOW + + +@pytest.fixture +def private_files(monkeypatch): + """Point the loaders at the fixture Position and watches, dated at NOW.""" + position_path, watches_path = FIXTURES / "position.yaml", FIXTURES / "watches.yaml" + monkeypatch.setattr("src.config.settings.settings.position_path", position_path) + monkeypatch.setattr("src.config.settings.settings.watches_path", watches_path) + # `watch sync` dates expiry from the wall clock; hold it at NOW as the + # other commands are held, or this test would rot on 2026-09-15. + monkeypatch.setattr( + "src.cli.watch.load_position", + lambda **kw: load_position(position_path, today=kw.get("today") or NOW.date()), + ) + monkeypatch.setattr( + "src.cli.watch.load_watches", + lambda **kw: load_watches( + watches_path, position=kw["position"], today=kw.get("today") or NOW.date() + ), + ) + + +@contextmanager +def patch_db(session): + """Every command's ``get_db`` yields the one test session.""" + + @contextmanager + def _ctx(): + try: + yield session + session.flush() + except Exception: + session.rollback() + raise + + patches = [ + patch(f"src.cli.{m}.get_db", _ctx) + for m in ("ingest", "route", "adjudicate", "brief", "watch") + ] + for p in patches: + p.start() + try: + yield + finally: + for p in patches: + p.stop() + + +def _feed_reader(content: bytes | None, error: Exception | None = None): + """An RSSFetcher whose one HTTP call returns ``content`` or raises ``error``.""" + fetcher = RSSFetcher() + response = MagicMock() + response.content = content + response.raise_for_status = MagicMock() + getter = AsyncMock(return_value=response, side_effect=error) + return fetcher, patch.object(fetcher.session, "get", getter) + + +def _adapters(): + """The four sources: recorded, recorded, empty, unreachable.""" + with open(FR_WEEK, encoding="utf-8") as handle: + week = json.load(handle) + fr = FederalRegisterAdapter( + source_filter=FederalRegisterFilter( + queries=(FederalRegisterQuery(name="week", agencies=("personnel-management-office",)),), + per_page=100, + max_pages=1, + ), + client=make_client(json_responder(week)), + requests_per_second=0, + ) + weekly, weekly_patch = _feed_reader((FIXTURES / "compliance_weekly.xml").read_bytes()) + newsroom, newsroom_patch = _feed_reader((FIXTURES / "agency_newsroom.xml").read_bytes()) + broken, broken_patch = _feed_reader(None, httpx.ConnectError("connection refused")) + adapters = [ + fr, + RSSAdapter( + "Compliance Weekly", "https://example.com/compliance-weekly.xml", "news", weekly + ), + RSSAdapter("Agency Newsroom", "https://example.com/newsroom.xml", "news", newsroom), + RSSAdapter("Broken Feed", "https://example.com/broken.xml", "news", broken), + ] + return adapters, (weekly_patch, newsroom_patch, broken_patch), (weekly, newsroom, broken) + + +class ScriptedClient: + """ + Answers by the watch named in the prompt. Deterministic and offline: the + NIST pair is evidence, the death-benefits form is evidence, the + court-ordered form is refused so that QUIET has a failed adjudication to + print, and anything else is not evidence. + """ + + def __init__(self): + self.calls = 0 + + def analyze(self, system_prompt, user_message, **kwargs): # noqa: ARG002 + self.calls += 1 + watch_id = user_message.split("CLAIM (watch ", 1)[1].split(")", 1)[0] + title = user_message.split("\ntitle: ", 1)[1].split("\n", 1)[0] + if watch_id == "opm-benefit-forms-change" and "Court-Ordered" in title: + raise ModelCallFailed( + "Model declined the request (category: scripted)", + audit_id=f"audit-{self.calls}", + outcome="answered", + input_tokens=900, + output_tokens=2, + stop_reason="refusal", + ) + evidence = watch_id in ("nist-site-rules-loosen", "opm-benefit-forms-change") + body = { + "is_evidence": evidence, + "direction": "supports" if evidence else "none", + "magnitude": {"nist-site-rules-loosen": 0.8, "opm-benefit-forms-change": 0.55}.get( + watch_id, 0.0 + ), + "satisfies_clause": 0 if evidence else -1, + "confidence": 0.9, + "rationale": "scripted", + } + return ModelResponse( + text=json.dumps(body), + model="scripted", + stop_reason="end_turn", + input_tokens=1000, + output_tokens=40, + cache_read_input_tokens=0, + cache_creation_input_tokens=0, + audit_id=f"audit-{self.calls}", + ) + + +def _compare(path: Path, actual: str) -> None: + if os.environ.get(UPDATE_GOLDEN): + path.write_text(actual, encoding="utf-8") + return + assert path.exists(), f"{path} is missing; run 'make golden' and review the file it writes" + assert actual == path.read_text(encoding="utf-8"), ( + f"{path.name} differs from the rendered brief; if the change is intended, " + f"run 'make golden' and read the diff" + ) + + +def test_the_morning_end_to_end(test_session, frozen_clock, private_files): + cli_runner = CliRunner() + adapters, http_patches, fetchers = _adapters() + with patch_db(test_session): + sync = cli_runner.invoke(watch_command, ["sync"]) + assert sync.exit_code == 0, sync.output + + with ( + http_patches[0], + http_patches[1], + http_patches[2], + patch("src.cli.ingest.build_configured_adapters", return_value=adapters), + ): + ingest = cli_runner.invoke(ingest_command, ["--since", "7d"]) + for fetcher in fetchers: + asyncio.run(fetcher.close()) + assert ingest.exit_code == 0, ingest.output + assert "UNREACHABLE Broken Feed" in ingest.output + + route = cli_runner.invoke(route_command, ["--since", "7d"]) + assert route.exit_code == 0, route.output + + client = ScriptedClient() + with patch("src.cli.adjudicate.resolve", return_value=ClaudeAdjudicator(client)): + adjudicate = cli_runner.invoke(adjudicate_command, []) + assert adjudicate.exit_code == 0, adjudicate.output + + args = ["--as-of", AS_OF, "--since", "7d"] + first = cli_runner.invoke(brief_command, args) + second = cli_runner.invoke(brief_command, args) + markdown = cli_runner.invoke(brief_command, [*args, "--format", "md", "--dry-run"]) + + for result in (first, second, markdown): + assert result.exit_code == 0, result.output + + # The corpus the golden rests on, so a drift is diagnosable from the failure. + assert test_session.query(Observation).count() == 8 # six documents, two feed items + # The DFARS notice is dated midnight on the window's first day and the + # window opens at 06:00, so seven observations are in it; none of the + # seven matches the DFARS watch. NIST routes twice, the two OPM forms once. + assert test_session.query(Route).count() == 4 + assert client.calls == 4 + assert test_session.query(Adjudication).count() == 4 + assert test_session.query(Evidence).count() == 3 + assert test_session.query(BriefRun).count() == 2 # the dry run wrote no row + + assert first.output == second.output, "the same inputs must render the same bytes" + _compare(GOLDEN / "brief.txt", first.output) + _compare(GOLDEN / "brief.md", markdown.output) + + +def test_the_frozen_clock_is_what_the_commands_read(frozen_clock): + from src.utils import utcnow + + assert utcnow() == NOW + assert utcnow().date() == date(2026, 8, 24) diff --git a/tests/brief/test_render.py b/tests/brief/test_render.py new file mode 100644 index 0000000..597cfcd --- /dev/null +++ b/tests/brief/test_render.py @@ -0,0 +1,320 @@ +""" +render() on hand-built Brief dataclasses, no database. + +Covers the fixed part order, the two flavours' markers, empty-section zeros, +citation formatting including near-duplicate clustering, header variants, DUE +past/expired phrasing, QUIET wording and purity. + +Added 2026-09-22 for backlog task 031. +""" + +from __future__ import annotations + +from datetime import date, datetime +from typing import Any + +import pytest + +from src.brief.render import render +from src.brief.sections import ( + Brief, + Citation, + DueDecision, + DueWatch, + FailedAdjudication, + Header, + MovedWatch, + PendingWatch, + QuietWatch, + SilentSource, + SourceState, + WatchingRow, +) + +AS_OF = datetime(2026, 8, 24, 6, 0) +SINCE = datetime(2026, 8, 17, 6, 0) + + +def _empty_header(**overrides: Any) -> Header: + base: dict[str, Any] = { + "as_of": AS_OF, + "since": SINCE, + "position_problem": None, + "reviewed": date(2026, 8, 1), + "days_since_review": 23, + "review_banner": False, + "sources": (), + } + base.update(overrides) + return Header(**base) + + +def _empty_brief(**header_overrides) -> Brief: + return Brief(header=_empty_header(**header_overrides)) + + +def _citation(**overrides: Any) -> Citation: + base: dict[str, Any] = { + "content_hash": "sha256:" + "a" * 64, + "title": "Agency proposes new rule", + "source": "Federal Register", + "published": "2026-08-20", + "direction": "up", + "magnitude": 0.5, + "prompt_version": "v1", + } + base.update(overrides) + return Citation(**base) + + +def _full_brief() -> Brief: + """A Brief with every section populated, for the purity and flavour checks.""" + sources = (SourceState("feed-a", datetime(2026, 8, 23, 5, 0), None, 3),) + watching = WatchingRow( + "w1", "claim", 0.6, "operator", date(2026, 8, 20), "d1", 12, 2, date(2026, 8, 22) + ) + return Brief( + header=_empty_header(sources=sources), + moved=[MovedWatch(watch_id="w1", claim="claim", state=None, clusters=((_citation(),),))], + due_decisions=[ + DueDecision("d1", "Renew", date(2026, 9, 1), 8, "high"), + ], + due_watches=[DueWatch("w2", "watch claim", date(2026, 9, 5), 12)], + watching=[watching], + quiet_watches=[QuietWatch("w3", 7, date(2026, 8, 10))], + silent_sources=[SilentSource("feed-c", True)], + pending=[PendingWatch("w5", 3)], + failed=[FailedAdjudication("sha256:" + "d" * 64, "w4", "v1", "parse error")], + ) + + +@pytest.mark.parametrize( + "markdown,title_marker,section_markers", + [ + (False, "BRIEF AS OF", ["MOVED", "DUE", "WATCHING", "QUIET"]), + (True, "# Brief as of", ["## MOVED", "## DUE", "## WATCHING", "## QUIET"]), + ], +) +def test_order_and_markers(markdown, title_marker, section_markers): + text = render(_empty_brief(), markdown=markdown) + positions = [text.index(m) for m in (title_marker, *section_markers)] + assert positions == sorted(positions) + if markdown: + assert "-" * len("MOVED") not in text + else: + assert "MOVED\n" + "-" * len("MOVED") in text + for line in text.splitlines(): + assert not line.startswith("- ") + assert not line.startswith("## ") + + +def test_flavours_differ_only_in_markers(): + def normalize_markdown(text: str) -> list[str]: + out = [] + for line in text.splitlines(): + if line.startswith("# "): + out.append(line[2:]) + elif line.startswith("## "): + out.append(line[3:]) + elif line.startswith("- "): + out.append("* " + line[2:]) + elif line.startswith(" - "): + out.append(" * " + line[4:]) + else: + out.append(line) + return out + + brief = _full_brief() + terminal = render(brief, markdown=False) + md = render(brief, markdown=True) + # the dashed section underline (terminal only) has no markdown counterpart + t_lines = [line for line in terminal.splitlines() if not (line and set(line) == {"-"})] + m_lines = normalize_markdown(md) + assert len(t_lines) == len(m_lines) + assert t_lines[0] == m_lines[0].upper() # title is upper-cased in terminal only + assert t_lines[1:] == m_lines[1:] + + +def test_empty_sections_print_zeros(): + text = render(_empty_brief(), markdown=False) + assert "nothing: no watch gained evidence in the window" in text + assert "nothing inside the horizon" in text + assert "no live watches" in text + assert "watches with nothing routed inside their staleness window: 0" in text + assert "sources that ran in the window and returned nothing: 0" in text + assert "routed pairs no adjudication has answered: 0" in text + assert "failed adjudications in the window: 0" in text + + +def test_citation_line_fields(): + citation = _citation( + content_hash="sha256:" + "b" * 64, + title="Something happened", + source="Reuters", + published="2026-08-19", + direction="down", + magnitude=1.5, + prompt_version="v3", + ) + brief = _empty_brief() + brief.moved = [ + MovedWatch(watch_id="w1", claim="claim text", state=None, clusters=((citation,),)) + ] + text = render(brief, markdown=False) + assert "down 1.50" in text + assert "2026-08-19" in text + assert "Reuters: Something happened" in text + assert "sha256:" + "b" * 12 in text + assert "v3" in text + + +@pytest.mark.parametrize( + "size,expected_also,expected_marker", + [(3, "(+2 near-duplicates)", 2), (2, "(+1 near-duplicate)", 1)], +) +def test_cluster_near_duplicate_counts(size, expected_also, expected_marker): + clusters = tuple( + _citation(content_hash=f"sha256:{n}" + "0" * 63, title=str(n)) for n in range(size) + ) + brief = _empty_brief() + brief.moved = [MovedWatch(watch_id="w1", claim="claim", state=None, clusters=(clusters,))] + text = render(brief, markdown=False) + assert expected_also in text + assert text.count("also ") == expected_marker + if size == 2: + assert "near-duplicates" not in text # plural must not appear for a single extra + + +def test_one_observation_under_two_prompt_versions_is_not_a_near_duplicate_of_itself(): + same = "sha256:" + "e" * 64 + cluster = ( + _citation(content_hash=same, prompt_version="v1"), + _citation(content_hash=same, prompt_version="v2"), + ) + brief = _empty_brief() + brief.moved = [MovedWatch(watch_id="w1", claim="claim", state=None, clusters=(cluster,))] + text = render(brief, markdown=False) + assert "near-duplicate" not in text + assert text.count("also ") == 1 # the second version is still cited + + +def test_a_watch_that_is_not_live_prints_its_state_beside_its_id(): + brief = _empty_brief() + brief.moved = [ + MovedWatch("w1", "claim", "expired 2026-08-22, unresolved", ((_citation(),),)), + ] + assert "* w1 [expired 2026-08-22, unresolved]: claim" in render(brief, markdown=False) + + +def test_header_position_problem_never_reviewed_and_banner(): + problem = "position.yaml is not a valid Position:\n - 'decisions' is required\n - bad date" + brief = _empty_brief(position_problem=problem) + brief.position_read = False + text = render(brief, markdown=False) + assert "POSITION NOT READ: position.yaml is not a valid Position:\n" in text + assert "\n - 'decisions' is required\n - bad date\n" in text + assert "decisions: POSITION NOT READ (see the header)" in text # DUE says so too + assert "decisions: POSITION NOT READ" not in render(_empty_brief(), markdown=False) + text = render(_empty_brief(reviewed=None, days_since_review=None), markdown=False) + assert "never reviewed" in text + text_on = render(_empty_brief(review_banner=True), markdown=False) + text_off = render(_empty_brief(review_banner=False), markdown=False) + assert "REVIEW OVERDUE" in text_on + assert "REVIEW OVERDUE" not in text_off + + +def _three_sources(): + return ( + SourceState(name="feed-a", last_attempt=None, last_error=None, items_in_window=0), + SourceState( + name="feed-b", + last_attempt=datetime(2026, 8, 23, 5, 0), + last_error="timeout", + items_in_window=2, + ), + SourceState( + name="feed-c", + last_attempt=datetime(2026, 8, 22, 4, 0), + last_error=None, + items_in_window=1, + ), + ) + + +def test_verbose_header_lists_never_fetched_failed_attempt_success_and_none_registered(): + text = render(_empty_brief(sources=_three_sources()), markdown=False, verbose=True) + assert "* feed-a: never fetched; 0 in window" in text + # A failed attempt is never printed as a fetch: the stamp is the attempt's. + assert "* feed-b: LAST ATTEMPT FAILED 2026-08-23 05:00: timeout; 2 in window" in text + assert "* feed-c: fetched 2026-08-22 04:00; 1 in window" in text + assert "none registered" in render(_empty_brief(sources=()), markdown=False, verbose=True) + + +def test_compact_header_is_the_default_and_folds_answered_sources_into_counts(): + """A source that answered, whatever it returned, is a count, never a line. + A source whose last attempt failed is always a line, every time -- that + is the one thing invariant 5 requires this header to never hide.""" + text = render(_empty_brief(sources=_three_sources()), markdown=False) + assert "sources: 3 configured, 1 fetched, 1 failed, 1 never fetched" in text + assert "* feed-b: LAST ATTEMPT FAILED 2026-08-23 05:00: timeout; 2 in window" in text + assert "feed-a" not in text # never-fetched: folded into the count, not named + assert "feed-c" not in text # answered cleanly: folded into the count, not named + assert "none registered" in render(_empty_brief(sources=()), markdown=False) + + +def test_compact_header_with_no_failures_prints_no_source_bullets(): + sources = (SourceState("feed-a", datetime(2026, 8, 23, 5, 0), None, 3),) + text = render(_empty_brief(sources=sources), markdown=False) + assert "sources: 1 configured, 1 fetched, 0 failed, 0 never fetched" in text + assert "* feed-a" not in text + + +def test_due_decision_past_and_watch_expired(): + brief = _empty_brief() + brief.due_decisions = [ + DueDecision( + key="dec1", name="Renew contract", deadline=date(2026, 8, 1), days_left=-5, stake=None + ) + ] + brief.due_watches = [ + DueWatch(watch_id="w1", claim="claim text", expires=date(2026, 8, 1), days_left=-3) + ] + text = render(brief, markdown=False) + assert "5 days PAST" in text + assert "EXPIRED 2026-08-01, 3 days ago, unresolved" in text + + +def test_quiet_never_routed_since_date_and_failed_line(): + brief = _empty_brief() + brief.quiet_watches = [ + QuietWatch(watch_id="w1", staleness_alert_days=7, last_routed=None), + QuietWatch(watch_id="w2", staleness_alert_days=7, last_routed=date(2026, 8, 10)), + ] + brief.failed = [ + FailedAdjudication( + content_hash="sha256:" + "c" * 64, + watch_id="w9", + prompt_version="v2", + error="model timeout", + ) + ] + brief.silent_sources = [SilentSource("feed-c", True), SilentSource("feed-d", False)] + brief.pending = [PendingWatch("w7", 4), PendingWatch("w8", 1)] + text = render(brief, markdown=False) + assert "w1: never routed" in text + assert "w2: nothing routed since 2026-08-10" in text + assert "sources that ran in the window and returned nothing: 2" in text + assert "* feed-c (HAS PRODUCED BEFORE; check the source)" in text + assert "* feed-d (never produced)" in text + assert "routed pairs no adjudication has answered: 5" in text + assert "* w7: 4" in text and "* w8: 1" in text + assert "sha256:" + "c" * 12 + " / w9 [v2]: model timeout" in text + + +def test_render_is_pure_and_ends_with_one_newline(): + brief = _full_brief() + text = render(brief, markdown=False) + assert text == render(brief, markdown=False) + assert render(brief, markdown=True) == render(brief, markdown=True) + assert text.endswith("\n") + assert not text.endswith("\n\n") diff --git a/tests/brief/test_select.py b/tests/brief/test_select.py new file mode 100644 index 0000000..19a4697 --- /dev/null +++ b/tests/brief/test_select.py @@ -0,0 +1,219 @@ +""" +``select_brief`` against a real database, no rendering: header, MOVED, DUE and +WATCHING. Rows are inserted out of the order the brief must print them, so a +missing sort is a failure, and each threshold is tested on both sides of its +boundary. QUIET is in ``test_select_quiet.py``. + +Added 2026-09-23 for backlog task 031; strengthened the same day after review. +""" + +from __future__ import annotations + +from datetime import date, datetime, timedelta + +from src.brief.select import HORIZON_DAYS, REVIEW_BANNER_DAYS, select_brief +from src.position.position import Decision +from tests.evidence.stubs import add_observations, add_routes, add_watches + +from .rows import ( + AS_OF, + SINCE, + _belief, + _evidence, + _obs, + _position, + _select, + _source, + _watch, +) + + +class TestHeader: + def test_sources_sorted_by_name_with_window_counts_and_the_last_attempt(self, test_session): + zeta = _source(test_session, "Zeta Feed", datetime(2026, 9, 19, 5, 0)) + alpha = _source(test_session, "Alpha Feed", datetime(2026, 9, 19, 5, 0), "timeout") + _obs(test_session, "a1", alpha.id, "t1", None, datetime(2026, 9, 15), [1, 2, 3]) + _obs(test_session, "a2", alpha.id, "t2", None, SINCE, [1, 2, 4]) # on the boundary: in + _obs(test_session, "z1", zeta.id, "t3", None, SINCE - timedelta(seconds=1), [4, 5, 6]) + + header = _select(test_session, _position(date(2026, 9, 1))).header + + assert [s.name for s in header.sources] == ["Alpha Feed", "Zeta Feed"] + alpha_state, zeta_state = header.sources + assert (alpha_state.items_in_window, alpha_state.last_error) == (2, "timeout") + assert (zeta_state.items_in_window, zeta_state.last_error) == (0, None) + assert zeta_state.last_attempt == datetime(2026, 9, 19, 5, 0) + + def test_the_review_banner_turns_on_the_day_after_the_threshold(self, test_session): + at = _select(test_session, _position(AS_OF.date() - timedelta(days=REVIEW_BANNER_DAYS))) + past = _select( + test_session, _position(AS_OF.date() - timedelta(days=REVIEW_BANNER_DAYS + 1)) + ) + assert (at.header.days_since_review, at.header.review_banner) == (REVIEW_BANNER_DAYS, False) + assert past.header.review_banner is True + assert REVIEW_BANNER_DAYS == 90 # the number the task file names + + def test_never_reviewed_and_not_read_both_carry_the_banner(self, test_session): + never = _select(test_session, _position(None)) + assert (never.header.reviewed, never.header.review_banner) == (None, True) + + unread = _select( + test_session, position=None, position_problem="x is not a Position:\n - y" + ) + assert unread.header.position_problem == "x is not a Position:\n - y" + assert unread.header.review_banner is True + assert unread.position_read is False + + +class TestMoved: + def test_clusters_and_citations_are_ordered_by_date_before_hash(self, test_session): + watch = _watch(test_session, "w") + source = _source(test_session, "Feed") + # The earlier observation has the LARGER hash in both pairs, so an + # order by hash alone gets both wrong. + later_small = _obs( + test_session, "aa", source.id, "later", None, datetime(2026, 9, 16), [7] * 10 + ) + earlier_big = _obs( + test_session, "zz", source.id, "earlier", None, datetime(2026, 9, 15), [7] * 10 + ) + single_later = _obs( + test_session, "ab", source.id, "single", None, datetime(2026, 9, 17), [9] * 10 + ) + for obs in (later_small, single_later, earlier_big): + _evidence(test_session, obs.content_hash, watch.id, datetime(2026, 9, 18)) + + [moved] = _select(test_session).moved + + assert moved.state is None + assert [c[0].title for c in moved.clusters] == ["earlier", "single"] + assert [c.title for c in moved.clusters[0]] == ["earlier", "later"] + + def test_two_prompt_versions_are_two_citations_of_one_observation(self, test_session): + watch = _watch(test_session, "w") + source = _source(test_session, "Feed") + obs = _obs(test_session, "a1", source.id, "t", None, datetime(2026, 9, 15), [1] * 10) + _evidence(test_session, obs.content_hash, watch.id, datetime(2026, 9, 18), "v2") + _evidence(test_session, obs.content_hash, watch.id, datetime(2026, 9, 18), "v1") + + [moved] = _select(test_session).moved + + assert [(c.content_hash, c.prompt_version) for c in moved.clusters[0]] == [ + (obs.content_hash, "v1"), + (obs.content_hash, "v2"), + ] + + def test_only_evidence_created_inside_the_window_moves(self, test_session): + watch = _watch(test_session, "w") + source = _source(test_session, "Feed") + before = _obs(test_session, "b1", source.id, "before", None, datetime(2026, 9, 1), [1] * 10) + edge = _obs(test_session, "e1", source.id, "edge", None, datetime(2026, 9, 1), [2] * 10) + after = _obs(test_session, "f1", source.id, "after", None, datetime(2026, 9, 1), [3] * 10) + _evidence(test_session, before.content_hash, watch.id, SINCE - timedelta(seconds=1)) + _evidence(test_session, edge.content_hash, watch.id, SINCE) + _evidence(test_session, after.content_hash, watch.id, AS_OF + timedelta(seconds=1)) + + [moved] = _select(test_session).moved + + assert [c[0].title for c in moved.clusters] == ["edge"] + + def test_a_watch_that_expired_or_was_resolved_in_the_window_still_shows_its_evidence( + self, test_session + ): + """Grading needs the evidence, so the watch is shown with its state, not dropped.""" + expired = _watch(test_session, "expired", expires=date(2026, 9, 18)) + resolved = _watch( + test_session, + "resolved", + resolved_at=datetime(2026, 9, 19), + outcome="no", + resolution_note="n", + ) + retired = _watch(test_session, "retired", retired_at=datetime(2026, 9, 19)) + source = _source(test_session, "Feed") + for n, w in enumerate((expired, resolved, retired)): + obs = _obs(test_session, f"x{n}", source.id, "t", None, datetime(2026, 9, 15), [n] * 10) + _evidence(test_session, obs.content_hash, w.id, datetime(2026, 9, 17)) + + moved = {m.watch_id: m.state for m in _select(test_session).moved} + + assert moved == { + "expired": "expired 2026-09-18, unresolved", + "resolved": "resolved no", + "retired": "retired", + } + + +class TestDue: + def test_decisions_and_watches_inside_the_horizon_sorted_by_date(self, test_session): + horizon = AS_OF.date() + timedelta(days=HORIZON_DAYS) + position = _position( + date(2026, 9, 1), + Decision(key="edge", name="On the horizon", deadline=horizon), + Decision(key="past", name="Past due", deadline=date(2026, 9, 10)), + Decision(key="beyond", name="Beyond", deadline=horizon + timedelta(days=1)), + Decision(key="soon", name="Soon", deadline=date(2026, 9, 25), stake="medium"), + ) + _watch(test_session, "within-horizon", expires=date(2026, 9, 30)) + _watch( + test_session, + "resolved-soon", + expires=date(2026, 9, 22), + resolved_at=datetime(2026, 9, 15), + outcome="yes", + resolution_note="settled", + ) + _watch(test_session, "expired-open", expires=date(2026, 9, 5)) + + brief = _select(test_session, position) + + assert [(d.key, d.days_left) for d in brief.due_decisions] == [ + ("past", -10), + ("soon", 5), + ("edge", HORIZON_DAYS), + ] + assert [(w.watch_id, w.days_left) for w in brief.due_watches] == [ + ("expired-open", -15), + ("within-horizon", 10), + ] + + +class TestWatching: + def test_one_row_per_live_watch_sorted_by_id_with_the_belief_as_of(self, test_session): + over = _watch(test_session, "overridden", belief=0.2) + _watch(test_session, "fallback", belief=0.3, created_at=datetime(2026, 8, 1)) + _watch(test_session, "gone", expires=date(2026, 9, 19)) + _belief(test_session, over.id, 0.9, datetime(2026, 9, 18)) + _belief(test_session, over.id, 0.4, datetime(2026, 9, 1)) + _belief(test_session, over.id, 0.1, AS_OF + timedelta(minutes=1)) # after as_of: not yet + source = _source(test_session, "Feed") + obs_in = _obs(test_session, "w1", source.id, "t", None, datetime(2026, 9, 14), [1] * 10) + obs_out = _obs(test_session, "w2", source.id, "t2", None, datetime(2026, 9, 14), [2] * 10) + _evidence(test_session, obs_in.content_hash, over.id, datetime(2026, 9, 15)) + _evidence(test_session, obs_out.content_hash, over.id, datetime(2026, 9, 2)) + + rows = _select(test_session).watching + + assert [r.watch_id for r in rows] == ["fallback", "overridden"] + fallback, overridden = rows + assert (fallback.belief, fallback.belief_source, fallback.belief_date) == ( + 0.3, + "file", + date(2026, 8, 1), + ) + assert (overridden.belief, overridden.belief_source, overridden.belief_date) == ( + 0.9, + "principal", + date(2026, 9, 18), + ) + assert (overridden.evidence_in_window, overridden.last_evidence) == (1, date(2026, 9, 15)) + + +def test_select_brief_is_deterministic(test_session): + add_watches(test_session) + add_observations(test_session) + add_routes(test_session) + as_of, since = datetime(2026, 9, 1, 6, 0), datetime(2026, 1, 1, 0, 0) + assert select_brief(test_session, as_of=as_of, since=since, position=None) == select_brief( + test_session, as_of=as_of, since=since, position=None + ) diff --git a/tests/brief/test_select_quiet.py b/tests/brief/test_select_quiet.py new file mode 100644 index 0000000..206fd08 --- /dev/null +++ b/tests/brief/test_select_quiet.py @@ -0,0 +1,92 @@ +""" +``select_brief``'s QUIET section: staleness on routing recency, silent sources, +pending pairs and failed adjudications. + +Added 2026-09-23 for backlog task 031 review. +""" + +from __future__ import annotations + +from datetime import date, datetime, timedelta + +from .rows import ( + AS_OF, + SINCE, + _adjudication, + _evidence, + _obs, + _route, + _select, + _source, + _watch, +) + + +class TestQuiet: + def test_staleness_is_tested_on_when_routing_last_linked_something(self, test_session): + """An old item routed yesterday is not silence; a fresh route after as_of is not seen.""" + stale = _watch(test_session, "stale", staleness_alert_days=5) + _watch(test_session, "never-routed", staleness_alert_days=5) + backfill = _watch(test_session, "backfill", staleness_alert_days=5) + future = _watch(test_session, "future-route", staleness_alert_days=5) + src = _source(test_session, "Feed", datetime(2026, 9, 18)) + old = _obs( + test_session, "s1", src.id, "o", datetime(2026, 8, 1), datetime(2026, 8, 1), [1] * 10 + ) + _route(test_session, old.content_hash, stale.id, routed_at=datetime(2026, 9, 14)) + _route(test_session, old.content_hash, backfill.id, routed_at=datetime(2026, 9, 19)) + _route(test_session, old.content_hash, future.id, routed_at=AS_OF + timedelta(hours=1)) + + quiet = {q.watch_id: q.last_routed for q in _select(test_session).quiet_watches} + + assert quiet == { + "stale": date(2026, 9, 14), + "never-routed": None, + "future-route": None, + } + + def test_silent_sources_say_whether_they_have_produced_before(self, test_session): + veteran = _source(test_session, "Veteran", datetime(2026, 9, 18)) + _source(test_session, "Newcomer", datetime(2026, 9, 18)) + _source(test_session, "Broken", datetime(2026, 9, 18), "500") + _source(test_session, "Not run", SINCE - timedelta(days=1)) + _source(test_session, "Never", None) + _obs(test_session, "v1", veteran.id, "t", None, datetime(2026, 8, 1), [1] * 10) + + silent = [(s.name, s.produced_before) for s in _select(test_session).silent_sources] + + assert silent == [("Newcomer", False), ("Veteran", True)] + + def test_pending_pairs_and_failed_adjudications(self, test_session): + w = _watch(test_session, "w") + closed = _watch(test_session, "closed", retired_at=datetime(2026, 9, 1)) + src = _source(test_session, "Feed") + obs = [ + _obs(test_session, f"p{n}", src.id, "t", None, datetime(2026, 9, 15), [n] * 10) + for n in range(4) + ] + for o in obs: + _route(test_session, o.content_hash, w.id, routed_at=datetime(2026, 9, 16)) + _route(test_session, obs[0].content_hash, closed.id, routed_at=datetime(2026, 9, 16)) + _adjudication(test_session, obs[0].content_hash, w.id, datetime(2026, 9, 16), "none") + _adjudication(test_session, obs[1].content_hash, w.id, datetime(2026, 9, 16), "failed", "x") + _evidence( + test_session, obs[2].content_hash, w.id, datetime(2026, 9, 16) + ) # replay-committed + _adjudication( + test_session, obs[3].content_hash, w.id, SINCE - timedelta(days=1), "failed", "old" + ) + + brief = _select(test_session) + + assert [(p.watch_id, p.pairs) for p in brief.pending] == [] + assert [(f.watch_id, f.error) for f in brief.failed] == [("w", "x")] + + def test_a_routed_pair_nobody_has_answered_is_pending(self, test_session): + w = _watch(test_session, "w") + src = _source(test_session, "Feed") + for n in range(2): + obs = _obs(test_session, f"q{n}", src.id, "t", None, datetime(2026, 9, 15), [n] * 10) + _route(test_session, obs.content_hash, w.id, routed_at=datetime(2026, 9, 16)) + + assert [(p.watch_id, p.pairs) for p in _select(test_session).pending] == [("w", 2)] diff --git a/tests/cli/test_adjudicate_cli.py b/tests/cli/test_adjudicate_cli.py new file mode 100644 index 0000000..d772f05 --- /dev/null +++ b/tests/cli/test_adjudicate_cli.py @@ -0,0 +1,162 @@ +""" +Tests for the `adjudicate` CLI command (backlog task 029). + +`get_db` is patched with a throwaway session and the registered adjudicator is +replaced with one whose client answers from a script. `--dry-run` is tested +with the client class itself patched to raise, which is the acceptance +criterion "without constructing a client" stated as a test. +""" + +import json +from contextlib import contextmanager +from unittest.mock import patch + +import pytest + +from src.cli.adjudicate import adjudicate_command +from src.database.models import Adjudication, Evidence +from src.evidence.claude_adjudicator import ClaudeAdjudicator +from src.llm.claude_client import ModelResponse + +from ..evidence.stubs import add_observations, add_routes, add_watches + + +def _verdict(is_evidence=True) -> str: + return json.dumps( + { + "is_evidence": is_evidence, + "direction": "supports" if is_evidence else "none", + "magnitude": 0.5, + "satisfies_clause": 0 if is_evidence else -1, + "confidence": 0.7, + "rationale": "words", + } + ) + + +class FakeClient: + def __init__(self, *scripted): + self.scripted = list(scripted) + + def analyze(self, system_prompt, user_message, **kwargs): # noqa: ARG002 + item = self.scripted.pop(0) + if isinstance(item, Exception): + raise item + return ModelResponse( + text=item, + model="m", + stop_reason="end_turn", + input_tokens=50, + output_tokens=5, + cache_read_input_tokens=0, + cache_creation_input_tokens=0, + audit_id="audit", + ) + + +@contextmanager +def _patched(session, *scripted): + @contextmanager + def _ctx(): + try: + yield session + session.flush() + except Exception: + session.rollback() + raise + + adjudicator = ClaudeAdjudicator(FakeClient(*scripted)) + with ( + patch("src.cli.adjudicate.get_db", _ctx), + patch("src.cli.adjudicate.resolve", return_value=adjudicator), + ): + yield + + +@pytest.fixture +def corpus(test_session): + add_watches(test_session) + add_observations(test_session) + add_routes(test_session) + return test_session + + +class TestRun: + def test_asks_every_pending_pair_and_prints_the_totals(self, cli_runner, corpus): + with _patched(corpus, _verdict(), _verdict(is_evidence=False)): + result = cli_runner.invoke(adjudicate_command, []) + + assert result.exit_code == 0, result.output + assert "asked 2: evidence 1, none 1, failed 0" in result.output + assert "tokens: 100 in, 10 out" in result.output + assert corpus.query(Adjudication).count() == 2 + assert corpus.query(Evidence).count() == 1 + + def test_a_second_run_reports_nothing_pending(self, cli_runner, corpus): + with _patched(corpus, _verdict(), _verdict()): + cli_runner.invoke(adjudicate_command, []) + result = cli_runner.invoke(adjudicate_command, []) + + assert result.exit_code == 0, result.output + assert "asked 0" in result.output + assert "No pending pairs" in result.output + + def test_a_failure_is_printed_and_recorded_and_the_command_still_exits_zero( + self, cli_runner, corpus + ): + with _patched(corpus, "garbage", _verdict()): + result = cli_runner.invoke(adjudicate_command, []) + + assert result.exit_code == 0, result.output + assert "FAILED" in result.output + assert "1 failed adjudication(s) are recorded, not retried" in result.output + assert corpus.query(Adjudication).filter(Adjudication.outcome == "failed").count() == 1 + + def test_limit_is_honoured_and_zero_is_refused(self, cli_runner, corpus): + with _patched(corpus, _verdict(), _verdict()): + result = cli_runner.invoke(adjudicate_command, ["--limit", "1"]) + zero = cli_runner.invoke(adjudicate_command, ["--limit", "0"]) + + assert result.exit_code == 0, result.output + assert "asked 1" in result.output + assert zero.exit_code != 0 + + def test_a_missing_key_exits_non_zero_naming_the_fix_and_writes_nothing( + self, cli_runner, corpus, memory_keyring + ): + @contextmanager + def _ctx(): + yield corpus + + with ( + patch("src.cli.adjudicate.get_db", _ctx), + patch("src.cli.adjudicate.resolve", return_value=ClaudeAdjudicator()), + ): + result = cli_runner.invoke(adjudicate_command, []) + + assert result.exit_code != 0 + assert "insightweaver auth set anthropic" in result.output + assert corpus.query(Adjudication).count() == 0 + + +class TestDryRun: + def test_prints_the_exact_text_and_never_constructs_a_client(self, cli_runner, corpus): + def explode(*_args, **_kwargs): + raise AssertionError("a client was constructed during --dry-run") + + @contextmanager + def _ctx(): + yield corpus + + with ( + patch("src.cli.adjudicate.get_db", _ctx), + patch("src.evidence.claude_adjudicator.ClaudeClient", explode), + ): + result = cli_runner.invoke(adjudicate_command, ["--dry-run"]) + + assert result.exit_code == 0, result.output + assert "[system]" in result.output and "[user]" in result.output + assert "You judge whether one published item" in result.output + assert "character estimate, not a count" in result.output + assert "Nothing was sent." in result.output + assert corpus.query(Adjudication).count() == 0 diff --git a/tests/cli/test_app.py b/tests/cli/test_app.py index 5dff87e..23a5569 100644 --- a/tests/cli/test_app.py +++ b/tests/cli/test_app.py @@ -6,7 +6,7 @@ import pytest -from src.cli.app import cli, interactive_mode, print_command_refresher +from src.cli.app import cli class TestCliGroup: @@ -29,24 +29,19 @@ def test_cli_version(self, cli_runner): def test_cli_debug_flag(self, cli_runner): """Should accept debug flag""" - with ( - patch("src.cli.app.set_debug_mode") as mock_debug, - patch("src.cli.app.interactive_mode"), - ): - cli_runner.invoke(cli, ["--debug"]) + with patch("src.cli.app.set_debug_mode") as mock_debug: + result = cli_runner.invoke(cli, ["--debug"]) mock_debug.assert_called_with(True) + assert result.exit_code == 0 + assert "InsightWeaver" in result.output -class TestPrintCommandRefresher: - """Tests for command refresher helper""" - - def test_print_command_refresher(self, cli_runner, capsys): - """Should print command refresher""" - print_command_refresher() - captured = capsys.readouterr() + def test_cli_with_no_arguments_prints_help_and_exits(self, cli_runner): + """No subcommand prints the group help and exits 0, rather than entering a REPL.""" + result = cli_runner.invoke(cli, []) - assert "Commands:" in captured.out - assert "sources" in captured.out + assert result.exit_code == 0 + assert "sources" in result.output class TestSubcommandRegistration: @@ -78,11 +73,13 @@ def test_watch_has_no_add_subcommand(self, cli_runner): @pytest.mark.parametrize( "gone", - ["brief", "frames", "diet", "questions", "predictions", "forecast", "decisions", "beat"], + ["frames", "diet", "questions", "predictions", "forecast", "decisions", "beat"], ) def test_deleted_commands_are_not_registered(self, cli_runner, gone): """ - The briefing commands are gone from --help and from dispatch. + The briefing commands are gone from --help and from dispatch. ``brief`` + left this list on 2026-09-22 (backlog task 031) when it came back as a + derived view over the monitor's tables, with no model call in it. Pinned rather than assumed: the editable install resolves a missing ``src.*`` module against the developer's other checkout, so a dangling @@ -93,78 +90,3 @@ def test_deleted_commands_are_not_registered(self, cli_runner, gone): result = cli_runner.invoke(cli, [gone, "--help"]) assert result.exit_code != 0 - - -class TestAsciiArt: - """Tests for ASCII art constant""" - - def test_ascii_art_defined(self): - """Should have ASCII art defined""" - from src.cli.app import ASCII_ART - - # ASCII art uses Unicode block characters, not ASCII letters - assert len(ASCII_ART) > 100 # Has substantial content - assert "Transform Data" in ASCII_ART or "Insight" in ASCII_ART - - -class TestInteractiveMode: - """Tests for interactive mode""" - - @patch("src.cli.app.click.prompt") - @patch("src.cli.app.click.echo") - @patch("src.cli.app.time.sleep") - def test_interactive_mode_exits_on_exit_command(self, mock_sleep, mock_echo, mock_prompt): - """Should exit on 'exit' command""" - mock_prompt.return_value = "exit" - - interactive_mode() - - # Should have called prompt at least once - mock_prompt.assert_called() - - @patch("src.cli.app.click.prompt") - @patch("src.cli.app.click.echo") - @patch("src.cli.app.time.sleep") - def test_interactive_mode_exits_on_quit_command(self, mock_sleep, mock_echo, mock_prompt): - """Should exit on 'quit' command""" - mock_prompt.return_value = "quit" - - interactive_mode() - - mock_prompt.assert_called() - - @patch("src.cli.app.click.prompt") - @patch("src.cli.app.click.echo") - @patch("src.cli.app.time.sleep") - def test_interactive_mode_shows_help(self, mock_sleep, mock_echo, mock_prompt): - """Should show help on 'help' command""" - mock_prompt.side_effect = ["help", "exit"] - - interactive_mode() - - # Check that help was shown (echo called multiple times) - assert mock_echo.call_count > 2 - - @patch("src.cli.app.click.prompt") - @patch("src.cli.app.click.echo") - @patch("src.cli.app.time.sleep") - def test_interactive_mode_handles_keyboard_interrupt(self, mock_sleep, mock_echo, mock_prompt): - """Should handle KeyboardInterrupt gracefully""" - mock_prompt.side_effect = KeyboardInterrupt() - - interactive_mode() - - # Should have printed exit message - assert any("InsightWeaver" in str(call) for call in mock_echo.call_args_list) - - @patch("src.cli.app.click.prompt") - @patch("src.cli.app.click.echo") - @patch("src.cli.app.time.sleep") - def test_interactive_mode_handles_unknown_command(self, mock_sleep, mock_echo, mock_prompt): - """Should handle unknown commands""" - mock_prompt.side_effect = ["unknown_cmd", "exit"] - - interactive_mode() - - # Should show error message - assert any("Unknown" in str(call) for call in mock_echo.call_args_list) diff --git a/tests/cli/test_auth_cli.py b/tests/cli/test_auth_cli.py new file mode 100644 index 0000000..c0b7b66 --- /dev/null +++ b/tests/cli/test_auth_cli.py @@ -0,0 +1,66 @@ +""" +The ``auth`` subcommand of ``insightweaver``. + +Moved from ``tests/estate/test_cli.py`` on 2026-09-22 (backlog task 027) when +the ``estate`` script folded into ``insightweaver`` as one command. +""" + +from src.cli.app import cli +from src.config import credentials +from src.config.settings import settings + + +class TestAuth: + def test_set_stores_under_the_known_username(self, cli_runner, memory_keyring): + result = cli_runner.invoke(cli, ["auth", "set", "anthropic", "--value", "sk-test"]) + + assert result.exit_code == 0, result.output + assert memory_keyring.store[(settings.keyring_service, credentials.ANTHROPIC)] == "sk-test" + assert "sk-test" not in result.output + + def test_set_prompts_with_hidden_input_when_no_value_given(self, cli_runner, memory_keyring): + result = cli_runner.invoke(cli, ["auth", "set", "anthropic"], input="sk-prompted\n") + + assert result.exit_code == 0, result.output + assert memory_keyring.store[(settings.keyring_service, credentials.ANTHROPIC)] == ( + "sk-prompted" + ) + assert "sk-prompted" not in result.output + + def test_set_refuses_a_blank_value(self, cli_runner, memory_keyring): + result = cli_runner.invoke(cli, ["auth", "set", "anthropic", "--value", " "]) + + assert result.exit_code != 0 + assert "blank" in result.output + assert not memory_keyring.store + + def test_set_rejects_an_unknown_name(self, cli_runner, memory_keyring): + result = cli_runner.invoke(cli, ["auth", "set", "plaid", "--value", "x"]) + + assert result.exit_code != 0 + assert not memory_keyring.store + + def test_status_never_prints_a_value(self, cli_runner, memory_keyring): + credentials.write(credentials.ANTHROPIC, "sk-secret") + + result = cli_runner.invoke(cli, ["auth", "status"]) + + assert result.exit_code == 0, result.output + assert "anthropic" in result.output and "set" in result.output + assert "sk-secret" not in result.output + + def test_status_reports_not_set(self, cli_runner, memory_keyring): + result = cli_runner.invoke(cli, ["auth", "status"]) + + assert result.exit_code == 0, result.output + assert "not set" in result.output + + def test_clear_removes_and_a_second_clear_fails(self, cli_runner, memory_keyring): + credentials.write(credentials.ANTHROPIC, "sk-test") + + first = cli_runner.invoke(cli, ["auth", "clear", "anthropic"]) + second = cli_runner.invoke(cli, ["auth", "clear", "anthropic"]) + + assert first.exit_code == 0, first.output + assert not memory_keyring.store + assert second.exit_code != 0 diff --git a/tests/cli/test_brief_cli.py b/tests/cli/test_brief_cli.py new file mode 100644 index 0000000..e772952 --- /dev/null +++ b/tests/cli/test_brief_cli.py @@ -0,0 +1,279 @@ +""" +Tests for the ``brief`` CLI command (backlog task 031). + +Every render passes ``--as-of`` explicitly so nothing here reads the wall +clock. The Position is always patched at ``src.cli.brief.load_position`` so +these tests do not depend on whether a real Position file exists on the +machine running them. + +Added 2026-09-22 for backlog task 031. +""" + +from __future__ import annotations + +import hashlib +import re +from contextlib import contextmanager +from datetime import date, datetime, timedelta +from pathlib import Path +from unittest.mock import patch + +import pytest + +from src.cli.brief import brief_command +from src.database.models import BriefRun +from src.position.position import Position, PositionError + + +def _stamp(when: datetime) -> str: + return when.strftime("%Y-%m-%d %H:%M") + + +def _patch_db(session): + @contextmanager + def _ctx(): + try: + yield session + session.flush() + except Exception: + session.rollback() + raise + + return patch("src.cli.brief.get_db", _ctx) + + +def _position(reviewed: date | None = date(2026, 9, 1)) -> Position: + return Position(path=Path("position.yaml"), version=1, decisions=(), reviewed=reviewed) + + +def _patch_position(value=None, error: Exception | None = None): + def _load(**_kwargs): + if error is not None: + raise error + return value if value is not None else _position() + + return patch("src.cli.brief.load_position", _load) + + +@pytest.fixture +def run(cli_runner, test_session): + """Invoke brief_command against the test session with a valid Position.""" + + def _run(args, position_patch=None): + with _patch_db(test_session), position_patch or _patch_position(): + return cli_runner.invoke(brief_command, args) + + return _run + + +class TestDefaultWindow: + def test_no_briefs_rows_defaults_to_seven_days_back(self, run): + as_of = "2026-09-22T06:00:00" + result = run(["--as-of", as_of, "--dry-run"]) + assert result.exit_code == 0, result.output + expected_since = datetime(2026, 9, 22, 6, 0) - timedelta(days=7) + assert f"window: since {_stamp(expected_since)}" in result.output + + def test_a_row_before_todays_start_sets_the_window(self, run, test_session): + # 2026-09-21 23:00 is before the start of 2026-09-22, so it qualifies. + prior = datetime(2026, 9, 21, 23, 0) + test_session.add( + BriefRun( + as_of=prior, since=prior - timedelta(days=7), moved=0, quiet=0, rendered_sha="x" + ) + ) + test_session.flush() + + result = run(["--as-of", "2026-09-22T06:00:00", "--dry-run"]) + assert result.exit_code == 0, result.output + assert f"window: since {_stamp(prior)}" in result.output + + def test_a_row_later_the_same_day_is_ignored_by_the_next_run(self, run, test_session): + # A qualifying row from yesterday sets the window both times. + prior = datetime(2026, 9, 21, 20, 0) + test_session.add( + BriefRun( + as_of=prior, since=prior - timedelta(days=7), moved=0, quiet=0, rendered_sha="x" + ) + ) + test_session.flush() + + as_of = "2026-09-22T06:00:00" + first = run(["--as-of", as_of]) + second = run(["--as-of", as_of]) + assert first.exit_code == 0, first.output + assert second.exit_code == 0, second.output + assert first.output == second.output, ( + "a second run the same morning must reproduce the first, " + "not fold in the row the first run just wrote" + ) + + def test_the_newest_qualifying_row_wins(self, run, test_session): + older = datetime(2026, 9, 19, 8, 0) + newer = datetime(2026, 9, 20, 8, 0) + test_session.add_all( + [ + BriefRun(as_of=older, since=older, moved=0, quiet=0, rendered_sha="a"), + BriefRun(as_of=newer, since=newer, moved=0, quiet=0, rendered_sha="b"), + ] + ) + test_session.flush() + + result = run(["--as-of", "2026-09-22T06:00:00", "--dry-run"]) + assert result.exit_code == 0, result.output + assert f"window: since {_stamp(newer)}" in result.output + assert f"window: since {_stamp(older)}" not in result.output + + +class TestSinceOverride: + def test_since_2w_overrides_the_default(self, run): + as_of = "2026-09-22T06:00:00" + result = run(["--as-of", as_of, "--since", "2w", "--dry-run"]) + assert result.exit_code == 0, result.output + expected_since = datetime(2026, 9, 22, 6, 0) - timedelta(days=14) + assert f"window: since {_stamp(expected_since)}" in result.output + + +class TestBriefsRow: + def test_a_row_is_written_per_render_with_counts_and_sha(self, run, test_session): + as_of = "2026-09-22T06:00:00" + result = run(["--as-of", as_of]) + assert result.exit_code == 0, result.output + + rows = test_session.query(BriefRun).all() + assert len(rows) == 1 + row = rows[0] + assert row.moved == len([]) # no watches exist in this corpus + assert row.quiet == 0 + assert row.rendered_sha == hashlib.sha256(result.output.encode("utf-8")).hexdigest() + + def test_dry_run_writes_no_row(self, run, test_session): + as_of = "2026-09-22T06:00:00" + result = run(["--as-of", as_of, "--dry-run"]) + assert result.exit_code == 0, result.output + assert test_session.query(BriefRun).count() == 0 + + +class TestFormatAndOutput: + def test_format_md_prints_markdown_headings(self, run): + as_of = "2026-09-22T06:00:00" + result = run(["--as-of", as_of, "--format", "md", "--dry-run"]) + assert result.exit_code == 0, result.output + assert "## MOVED" in result.output + assert "## QUIET" in result.output + assert not re.search(r"^MOVED$", result.output, re.MULTILINE) + + def test_verbose_lists_every_source_default_folds_answered_ones_into_a_count( + self, run, test_session + ): + from src.database.models import RSSFeed + + test_session.add( + RSSFeed( + name="Quiet Feed", + url="https://example.com/feed", + last_fetched=datetime(2026, 9, 21, 8, 0), + last_error=None, + ) + ) + test_session.commit() + as_of = "2026-09-22T06:00:00" + + compact = run(["--as-of", as_of, "--dry-run"]) + verbose = run(["--as-of", as_of, "--dry-run", "--verbose"]) + + assert compact.exit_code == 0 and verbose.exit_code == 0 + assert "sources: 1 configured, 1 fetched, 0 failed, 0 never fetched" in compact.output + # An answered source is folded into the count in the header, even + # though it is also named later in QUIET as a source that produced + # nothing -- a different, unrelated section doing its own job. + assert "* Quiet Feed: fetched" not in compact.output + assert "* Quiet Feed: fetched 2026-09-21 08:00; 0 in window" in verbose.output + + def test_output_path_writes_the_file_and_prints_wrote(self, run, tmp_path): + as_of = "2026-09-22T06:00:00" + out_path = tmp_path / "brief.txt" + + plain = run(["--as-of", as_of, "--dry-run"]) + assert plain.exit_code == 0, plain.output + + written = run(["--as-of", as_of, "--dry-run", "--output", str(out_path)]) + assert written.exit_code == 0, written.output + assert "wrote" in written.output + assert str(out_path) in written.output + assert out_path.read_text(encoding="utf-8") == plain.output + + +class TestAsOfParsing: + def test_a_non_iso_as_of_exits_non_zero_with_a_message(self, run): + result = run(["--as-of", "not-a-date", "--dry-run"]) + assert result.exit_code != 0 + assert "not-a-date" in result.output + assert "ISO 8601" in result.output + + def test_an_aware_as_of_is_converted_to_naive_utc(self, run): + # 2026-09-22T08:00:00+02:00 is 2026-09-22T06:00:00 UTC. + result = run(["--as-of", "2026-09-22T08:00:00+02:00", "--dry-run"]) + assert result.exit_code == 0, result.output + assert f"Brief as of {_stamp(datetime(2026, 9, 22, 6, 0))}".upper() in result.output + + +class TestPositionNotRead: + def test_a_position_that_cannot_be_read_still_renders_and_exits_zero(self, run): + result = run( + ["--as-of", "2026-09-22T06:00:00", "--dry-run"], + position_patch=_patch_position(error=FileNotFoundError("no position at /nowhere")), + ) + assert result.exit_code == 0, result.output + assert "POSITION NOT READ" in result.output + assert "no position at /nowhere" in result.output + + def test_a_position_error_also_renders_with_the_message(self, run): + bad_path = Path("/nowhere/position.yaml") + error = PositionError(bad_path, ["'decisions' is required"]) + result = run( + ["--as-of", "2026-09-22T06:00:00", "--dry-run"], + position_patch=_patch_position(error=error), + ) + assert result.exit_code == 0, result.output + assert "POSITION NOT READ" in result.output + # Every problem the loader found, not just the first line of the message. + assert "'decisions' is required" in result.output + assert "REVIEW OVERDUE" in result.output + assert "decisions: POSITION NOT READ (see the header)" in result.output + + +class TestOutputFailure: + def test_an_unwritable_output_path_records_no_brief(self, run, test_session, tmp_path): + """A row for a brief nobody received would move the next default window past it.""" + missing_dir = tmp_path / "no-such-dir" / "brief.txt" + result = run(["--as-of", "2026-09-22T06:00:00", "--output", str(missing_dir)]) + assert result.exit_code != 0 + assert "could not write" in result.output + assert test_session.query(BriefRun).count() == 0 + + +class TestInvalidSince: + def test_an_invalid_since_exits_non_zero_and_writes_no_row(self, run, test_session): + result = run(["--as-of", "2026-09-22T06:00:00", "--since", "not-a-cadence"]) + assert result.exit_code != 0 + assert test_session.query(BriefRun).count() == 0 + + +class TestNoModelCallInTheRenderPath: + def test_no_module_imports_the_model_client_or_the_adjudicator(self): + """ + The render path (backlog task 031) makes no model call; OUT OF SCOPE in + the task file. Scanning source text rather than sys.modules, because an + indirect import elsewhere in the process could otherwise make this test + pass by accident. + """ + root = Path(__file__).resolve().parents[2] / "src" + files = [*sorted((root / "brief").glob("*.py")), root / "cli" / "brief.py"] + assert files, "expected src/brief/*.py and src/cli/brief.py to exist" + for path in files: + text = path.read_text(encoding="utf-8") + assert "src.llm" not in text, f"{path} imports src.llm" + assert "src.evidence.claude_adjudicator" not in text, ( + f"{path} imports src.evidence.claude_adjudicator" + ) diff --git a/tests/cli/test_ingest_cli.py b/tests/cli/test_ingest_cli.py new file mode 100644 index 0000000..7536ce2 --- /dev/null +++ b/tests/cli/test_ingest_cli.py @@ -0,0 +1,199 @@ +""" +Tests for the `ingest` CLI command (backlog task 028). + +Everything here is offline: `build_configured_adapters` is patched to return +FakeAdapters (mirroring tests/sources/test_runner.py::FakeAdapter) and +`get_db` is patched with the `_patch_db` pattern from +tests/cli/test_replay_cli.py, so nothing here touches config/feeds/ or the +real database. +""" + +from contextlib import contextmanager +from datetime import timedelta +from unittest.mock import patch + +from src.cli.ingest import ingest_command +from src.database.models import Observation +from src.sources.base import RawItem, SourceUnavailable +from src.sources.store import ensure_source, store_items +from src.utils import utcnow + + +def _patch_db(session): + @contextmanager + def _ctx(): + try: + yield session + session.flush() + except Exception: + session.rollback() + raise + + return patch("src.cli.ingest.get_db", _ctx) + + +def _patch_adapters(adapters): + return patch("src.cli.ingest.build_configured_adapters", return_value=adapters) + + +def _item(guid: str) -> RawItem: + return RawItem( + guid=guid, + url=f"https://example.gov/{guid}", + title=f"Title {guid}", + normalized_content=f"Body of {guid}", + ) + + +class FakeAdapter: + """An adapter whose behaviour each test dictates outright.""" + + category = "federal_policy" + + def __init__(self, name, items=None, error=None): + self.name = name + self.source_url = f"https://example.gov/api/{name}" + self._items = items or [] + self._error = error + self.since_seen = None + + async def fetch(self, since): + self.since_seen = since + if self._error is not None: + raise self._error + return self._items + + +class TestSuccessfulRun: + def test_prints_fetched_and_inserted_counts_and_exits_zero(self, cli_runner, test_session): + adapter = FakeAdapter("Source A", items=[_item("a1"), _item("a2")]) + + with _patch_db(test_session), _patch_adapters([adapter]): + result = cli_runner.invoke(ingest_command, []) + + assert result.exit_code == 0, result.output + assert "Source A" in result.output + assert "fetched 2" in result.output + assert "inserted 2" in result.output + + def test_the_observations_table_holds_the_stored_items(self, cli_runner, test_session): + adapter = FakeAdapter("Source A", items=[_item("a1"), _item("a2")]) + + with _patch_db(test_session), _patch_adapters([adapter]): + cli_runner.invoke(ingest_command, []) + + assert test_session.query(Observation).count() == 2 + + +class TestUnreachableSource: + def test_an_unreachable_source_is_printed_as_unreachable(self, cli_runner, test_session): + good = FakeAdapter("Good Source", items=[_item("a1")]) + bad = FakeAdapter("Bad Source", error=SourceUnavailable("Bad Source", "HTTP 503")) + + with _patch_db(test_session), _patch_adapters([bad, good]): + result = cli_runner.invoke(ingest_command, []) + + assert "UNREACHABLE" in result.output + assert "Bad Source" in result.output + + def test_the_command_still_exits_zero_when_another_source_succeeded( + self, cli_runner, test_session + ): + good = FakeAdapter("Good Source", items=[_item("a1")]) + bad = FakeAdapter("Bad Source", error=SourceUnavailable("Bad Source", "HTTP 503")) + + with _patch_db(test_session), _patch_adapters([bad, good]): + result = cli_runner.invoke(ingest_command, []) + + assert result.exit_code == 0, result.output + + def test_every_source_unreachable_exits_non_zero(self, cli_runner, test_session): + bad = FakeAdapter("Bad Source", error=SourceUnavailable("Bad Source", "HTTP 503")) + + with _patch_db(test_session), _patch_adapters([bad]): + result = cli_runner.invoke(ingest_command, []) + + assert result.exit_code != 0 + + +class TestWentSilent: + def test_a_source_that_produced_before_and_returns_nothing_is_flagged( + self, cli_runner, test_session + ): + adapter = FakeAdapter("Quiet Source", items=[]) + source = ensure_source(test_session, adapter.name, adapter.source_url, adapter.category) + store_items(test_session, source, [_item("earlier")]) + test_session.flush() + + with _patch_db(test_session), _patch_adapters([adapter]): + result = cli_runner.invoke(ingest_command, []) + + assert result.exit_code == 0, result.output + assert "WENT SILENT" in result.output + assert "SOURCE ALERT" in result.output + assert "Quiet Source" in result.output + + +class TestAdapterSet: + def test_the_command_asks_for_every_configured_feed_including_rss( + self, cli_runner, test_session + ): + seen = {} + + def build(*args, **kwargs): + seen.update(kwargs) + return [FakeAdapter("Source A", items=[_item("a1")])] + + with _patch_db(test_session), patch("src.cli.ingest.build_configured_adapters", build): + result = cli_runner.invoke(ingest_command, []) + + assert result.exit_code == 0, result.output + assert seen == {"include_rss": True} + + +class TestSourceFilter: + def test_filters_sources_by_case_insensitive_substring(self, cli_runner, test_session): + federal = FakeAdapter("Federal Register", items=[_item("a1")]) + regional = FakeAdapter("Regional Gazette", items=[_item("b1")]) + + with _patch_db(test_session), _patch_adapters([federal, regional]): + result = cli_runner.invoke(ingest_command, ["--source", "federal"]) + + assert result.exit_code == 0, result.output + assert "Federal Register" in result.output + assert "Regional Gazette" not in result.output + + def test_an_unmatched_filter_exits_non_zero_and_says_nothing_matched( + self, cli_runner, test_session + ): + federal = FakeAdapter("Federal Register", items=[_item("a1")]) + + with _patch_db(test_session), _patch_adapters([federal]): + result = cli_runner.invoke(ingest_command, ["--source", "nonexistent"]) + + assert result.exit_code != 0 + assert "nothing matched" in result.output + + +class TestSinceOption: + def test_an_invalid_since_exits_non_zero(self, cli_runner, test_session): + adapter = FakeAdapter("Source A", items=[]) + + with _patch_db(test_session), _patch_adapters([adapter]): + result = cli_runner.invoke(ingest_command, ["--since", "soon"]) + + assert result.exit_code != 0 + + def test_since_2w_passes_a_window_start_roughly_fourteen_days_back( + self, cli_runner, test_session + ): + adapter = FakeAdapter("Source A", items=[]) + + before = utcnow() + with _patch_db(test_session), _patch_adapters([adapter]): + result = cli_runner.invoke(ingest_command, ["--since", "2w"]) + after = utcnow() + + assert result.exit_code == 0, result.output + assert adapter.since_seen is not None + assert before - timedelta(days=14) <= adapter.since_seen <= after - timedelta(days=14) diff --git a/tests/cli/test_replay_cli.py b/tests/cli/test_replay_cli.py index f7c1642..01ebc3f 100644 --- a/tests/cli/test_replay_cli.py +++ b/tests/cli/test_replay_cli.py @@ -20,10 +20,10 @@ import pytest from src.cli.replay import replay_command -from src.database.models import Evidence +from src.database.models import Evidence, Route from src.evidence import commit, rebuild -from ..evidence.stubs import KeywordAdjudicator, add_observations, add_watches +from ..evidence.stubs import KeywordAdjudicator, add_observations, add_routes, add_watches V1 = "tests.evidence.stubs:make_v1" V2 = "tests.evidence.stubs:make_v2" @@ -52,6 +52,7 @@ def corpus(test_session): """ add_watches(test_session) add_observations(test_session) + add_routes(test_session) commit(test_session, "v1", rebuild(test_session, KeywordAdjudicator("v1"))) test_session.flush() return test_session @@ -183,12 +184,55 @@ def test_an_empty_observation_corpus_says_so(self, cli_runner, test_session): class TestRegisteredInTheApp: def test_replay_is_a_top_level_command(self): - from src.cli.app import COMMAND_DISPATCH, cli + from src.cli.app import cli - assert COMMAND_DISPATCH["replay"] is replay_command - assert "replay" in cli.commands + assert cli.commands["replay"] is replay_command def test_commit_is_a_flag_that_defaults_to_off(self): flag = next(p for p in replay_command.params if p.name == "do_commit") assert flag.is_flag is True assert flag.default is False + + +class TestAnUnroutedCorpusIsRefused: + def test_replay_refuses_rather_than_reading_as_no_evidence( + self, cli_runner, test_session, corpus + ): + """ + With routes cleared, a replay would judge no pair and, with --commit, + delete the version's stored evidence. The command names the fix instead. + """ + test_session.query(Route).delete() + # Committed, so the harness's rollback on the refusal cannot be what + # keeps the evidence; only the command's own behaviour can. + test_session.commit() + + with _patch_db(test_session): + result = cli_runner.invoke( + replay_command, ["--prompt-version", "v1", "--adjudicator", V1, "--commit"] + ) + + assert result.exit_code != 0 + assert "nothing is routed" in result.output + assert test_session.query(Evidence).count() == 2 + + +class TestABoundedReplayCannotBeCommitted: + def test_limit_with_commit_is_refused_before_anything_runs( + self, cli_runner, test_session, corpus + ): + """ + commit makes the stored rows equal the replay. A bounded replay produced + rows for part of the corpus, so committing it would delete the rest. + """ + test_session.commit() + + with _patch_db(test_session): + result = cli_runner.invoke( + replay_command, + ["--prompt-version", "v1", "--adjudicator", V1, "--limit", "1", "--commit"], + ) + + assert result.exit_code != 0 + assert "--commit with --limit is refused" in result.output + assert test_session.query(Evidence).count() == 2 diff --git a/tests/cli/test_route_cli.py b/tests/cli/test_route_cli.py new file mode 100644 index 0000000..ac7d059 --- /dev/null +++ b/tests/cli/test_route_cli.py @@ -0,0 +1,139 @@ +""" +Tests for the `route` CLI command (backlog task 028). + +`get_db` is patched with the `_patch_db` pattern from +tests/cli/test_replay_cli.py, so nothing here touches the real database. The +corpus is built from tests/evidence/stubs.py::add_watches / add_observations, +the same builders tests/cli/test_replay_cli.py uses, so the two suites cannot +drift about what the corpus contains. + +The stub corpus is published 2026-08-20 to 2026-08-23 and the command's clock +is frozen at 2026-09-01, so `--since 10y` covers the corpus and both stub +watches (expiring 2026-12-15 and 2027-03-31) are live on every day the suite +runs. +""" + +from contextlib import contextmanager +from datetime import datetime +from unittest.mock import patch + +import pytest + +from src.cli.route import route_command +from src.database.models import Observation, Route +from tests.evidence.stubs import add_observations, add_watches + +SINCE = "10y" + + +# The stub watches expire 2026-12-15 and 2027-03-31. The command's clock is +# frozen here so the suite does not start failing on 2026-12-16. +FROZEN_NOW = datetime(2026, 9, 1, 8, 0) + + +@contextmanager +def _patch_db(session): + """A throwaway session for the command, and a frozen clock beside it.""" + + @contextmanager + def _ctx(): + try: + yield session + session.flush() + except Exception: + session.rollback() + raise + + with ( + patch("src.cli.route.get_db", _ctx), + patch("src.cli.route.utcnow", return_value=FROZEN_NOW), + ): + yield + + +@pytest.fixture +def corpus(test_session): + """Two watches and four observations; two of the four match a watch.""" + add_watches(test_session) + add_observations(test_session) + test_session.flush() + return test_session + + +def _hash_for(session, title_fragment: str) -> str: + for obs in session.query(Observation).all(): + if title_fragment in (obs.payload or {}).get("title", ""): + return obs.content_hash + raise AssertionError(f"no observation with '{title_fragment}' in its title") + + +class TestRouteWrites: + def test_route_writes_two_route_rows_and_reports_the_count(self, cli_runner, corpus): + with _patch_db(corpus): + result = cli_runner.invoke(route_command, ["--since", SINCE]) + + assert result.exit_code == 0, result.output + assert corpus.query(Route).count() == 2 + assert "2 link(s) written" in result.output + + def test_dry_run_writes_nothing_and_says_so(self, cli_runner, corpus): + with _patch_db(corpus): + result = cli_runner.invoke(route_command, ["--since", SINCE, "--dry-run"]) + + assert result.exit_code == 0, result.output + assert corpus.query(Route).count() == 0 + assert "Nothing was written" in result.output + + def test_running_route_twice_leaves_two_rows(self, cli_runner, corpus): + with _patch_db(corpus): + cli_runner.invoke(route_command, ["--since", SINCE]) + cli_runner.invoke(route_command, ["--since", SINCE]) + + assert corpus.query(Route).count() == 2 + + +class TestRebuild: + def test_rebuild_after_a_stale_route_row_leaves_exactly_the_two_correct_rows( + self, cli_runner, corpus + ): + stale_hash = _hash_for(corpus, "Persimmons") + corpus.add( + Route(observation_hash=stale_hash, watch_id="conmon-scope-expands", clause_index=0) + ) + corpus.flush() + + with _patch_db(corpus): + result = cli_runner.invoke(route_command, ["--since", SINCE, "--rebuild"]) + + assert result.exit_code == 0, result.output + rows = {(r.observation_hash, r.watch_id) for r in corpus.query(Route).all()} + assert len(rows) == 2 + assert stale_hash not in {h for h, _ in rows} + assert (_hash_for(corpus, "continuous monitoring"), "conmon-scope-expands") in rows + assert (_hash_for(corpus, "Hiring notice"), "hiring-market-tightens") in rows + + +class TestReport: + def test_the_report_lists_each_watch_with_new_and_in_window_counts(self, cli_runner, corpus): + with _patch_db(corpus): + result = cli_runner.invoke(route_command, ["--since", SINCE]) + + assert result.exit_code == 0, result.output + assert "conmon-scope-expands: 1 new, 1 in window" in result.output + assert "hiring-market-tightens: 1 new, 1 in window" in result.output + + def test_the_report_lists_unrouted_clusters_with_their_source_name(self, cli_runner, corpus): + with _patch_db(corpus): + result = cli_runner.invoke(route_command, ["--since", SINCE]) + + assert result.exit_code == 0, result.output + assert "unrouted, largest clusters first:" in result.output + assert "Example Agency" in result.output + + +class TestRefusals: + def test_an_invalid_since_exits_non_zero(self, cli_runner, corpus): + with _patch_db(corpus): + result = cli_runner.invoke(route_command, ["--since", "soon"]) + + assert result.exit_code != 0 diff --git a/tests/cli/test_run_cli.py b/tests/cli/test_run_cli.py new file mode 100644 index 0000000..27ff85d --- /dev/null +++ b/tests/cli/test_run_cli.py @@ -0,0 +1,135 @@ +""" +Tests for the `run` CLI command (backlog task 031). + +``run`` chains ingest, route, adjudicate and brief and stops at the first +step that raises a ``click.ClickException``. These tests never execute the +real steps -- ``src.cli.run.STEPS`` is patched with fake commands whose +callbacks record their own invocation, so the tests exercise only the +orchestration logic in ``run_command`` itself. + +Added 2026-09-22, backlog task 031. +""" + +from unittest.mock import patch + +import click +import pytest + +from src.cli.app import cli +from src.cli.run import STEPS, run_command + + +def _fake_step(name, calls, raises=None, warn=None): + """Build a click.Command whose callback records the call and optionally raises.""" + + @click.command(name=name) + def _cmd(): + calls.append(name) + if warn is not None: + click.echo(warn) + if raises is not None: + raise raises + + return name, _cmd + + +class TestRunOrdersAndEchoesSteps: + def test_steps_run_in_order(self, cli_runner): + calls = [] + steps = ( + _fake_step("ingest", calls), + _fake_step("route", calls), + _fake_step("adjudicate", calls), + _fake_step("brief", calls), + ) + + with patch("src.cli.run.STEPS", steps): + result = cli_runner.invoke(run_command, []) + + assert result.exit_code == 0 + assert calls == ["ingest", "route", "adjudicate", "brief"] + + def test_each_step_name_is_echoed_with_arrow_prefix(self, cli_runner): + calls = [] + steps = ( + _fake_step("ingest", calls), + _fake_step("route", calls), + ) + + with patch("src.cli.run.STEPS", steps): + result = cli_runner.invoke(run_command, []) + + assert "==> ingest" in result.output + assert "==> route" in result.output + + +class TestRunStopsAtFirstFailure: + def test_click_exception_in_second_step_stops_the_run(self, cli_runner): + calls = [] + steps = ( + _fake_step("ingest", calls), + _fake_step("route", calls, raises=click.ClickException("boom")), + _fake_step("adjudicate", calls), + _fake_step("brief", calls), + ) + + with patch("src.cli.run.STEPS", steps): + result = cli_runner.invoke(run_command, []) + + assert result.exit_code != 0 + assert calls == ["ingest", "route"] + assert "route" not in calls[2:] + assert "adjudicate" not in calls + assert "brief" not in calls + + def test_failure_message_is_prefixed_with_the_step_name(self, cli_runner): + calls = [] + steps = ( + _fake_step("ingest", calls), + _fake_step("route", calls, raises=click.ClickException("boom")), + ) + + with patch("src.cli.run.STEPS", steps): + result = cli_runner.invoke(run_command, []) + + assert "route: boom" in result.output + + +class TestRunToleratesWarnings: + def test_a_step_that_warns_but_returns_normally_does_not_stop_the_run(self, cli_runner): + calls = [] + steps = ( + _fake_step("ingest", calls, warn="warning: one source unreachable"), + _fake_step("route", calls), + ) + + with patch("src.cli.run.STEPS", steps): + result = cli_runner.invoke(run_command, []) + + assert result.exit_code == 0 + assert calls == ["ingest", "route"] + assert "warning: one source unreachable" in result.output + + +class TestRealStepsTable: + def test_step_names_are_exactly_ingest_route_adjudicate_brief_in_order(self): + assert tuple(name for name, _ in STEPS) == ("ingest", "route", "adjudicate", "brief") + + @pytest.mark.parametrize("name", ["ingest", "route", "adjudicate", "brief"]) + def test_each_step_command_is_the_one_registered_on_the_cli_group(self, name): + steps_by_name = dict(STEPS) + assert steps_by_name[name] is cli.commands[name] + + +class TestRealCliHelp: + def test_run_help_exits_zero_through_the_real_cli_group(self, cli_runner): + result = cli_runner.invoke(cli, ["run", "--help"]) + assert result.exit_code == 0 + + def test_brief_help_exits_zero_through_the_real_cli_group(self, cli_runner): + result = cli_runner.invoke(cli, ["brief", "--help"]) + assert result.exit_code == 0 + + def test_run_and_brief_are_registered_on_the_cli_group(self): + assert "run" in cli.commands + assert "brief" in cli.commands diff --git a/tests/cli/test_watch_cli.py b/tests/cli/test_watch_cli.py index e6f3157..120eaf8 100644 --- a/tests/cli/test_watch_cli.py +++ b/tests/cli/test_watch_cli.py @@ -18,6 +18,7 @@ from src.cli.watch import _expiry_phrase, watch_command from src.database.models import Watch as WatchRow +from src.database.models import WatchBelief EXAMPLE_POSITION = Path(__file__).resolve().parents[2] / "config" / "position.example.yaml" EXAMPLE_WATCHES = Path(__file__).resolve().parents[2] / "config" / "watches.example.yaml" @@ -147,8 +148,14 @@ def test_sync_reports_a_bad_file_and_stores_nothing(self, cli_runner, test_sessi class TestNoWriteSeamExists: """Invariant 6: the system never authors its own watches.""" - def test_only_list_and_sync_are_registered(self): - assert set(watch_command.commands) == {"list", "sync"} + def test_only_the_four_operator_commands_are_registered(self): + """list and sync (task 013); believe and resolve (task 030). No constructor.""" + assert set(watch_command.commands) == {"list", "sync", "believe", "resolve"} + + @pytest.mark.parametrize("command", ["believe", "resolve"]) + def test_the_operator_commands_take_no_argument_describing_a_watch(self, command): + names = {p.name for p in watch_command.commands[command].params} + assert names.isdisjoint({"claim", "triggers", "so_what", "decision", "expires"}) @pytest.mark.parametrize("forbidden", ["add", "create", "new", "propose", "accept", "edit"]) def test_no_write_command_exists(self, forbidden): @@ -176,3 +183,90 @@ def test_today(self): def test_past(self): assert "expired 5d ago" in _expiry_phrase(date(2026, 8, 27), date(2026, 9, 1)) + + +class TestBelieve: + def test_records_a_principal_belief_with_its_note(self, cli_runner, stored_watch): + with _patch_db(stored_watch): + result = cli_runner.invoke( + watch_command, ["believe", "conmon-scope-expands", "0.6", "--note", "memo landed"] + ) + + assert result.exit_code == 0, result.output + assert "belief 0.60 recorded" in result.output + row = stored_watch.query(WatchBelief).one() + assert (row.belief, row.source, row.note) == (0.6, "principal", "memo landed") + + def test_refuses_without_a_note_and_out_of_range(self, cli_runner, stored_watch): + with _patch_db(stored_watch): + no_note = cli_runner.invoke(watch_command, ["believe", "conmon-scope-expands", "0.6"]) + too_big = cli_runner.invoke( + watch_command, ["believe", "conmon-scope-expands", "1.6", "--note", "n"] + ) + + assert no_note.exit_code != 0 + assert too_big.exit_code != 0 + assert stored_watch.query(WatchBelief).count() == 0 + + def test_refuses_an_unknown_watch(self, cli_runner, stored_watch): + with _patch_db(stored_watch): + result = cli_runner.invoke(watch_command, ["believe", "nope", "0.5", "--note", "n"]) + + assert result.exit_code != 0 + assert "no watch 'nope'" in result.output + + def test_list_shows_the_current_belief_its_source_and_the_registration( + self, cli_runner, stored_watch, tmp_path + ): + with _patch_db(stored_watch): + cli_runner.invoke( + watch_command, ["believe", "conmon-scope-expands", "0.6", "--note", "memo"] + ) + result = cli_runner.invoke(watch_command, ["list"]) + + assert result.exit_code == 0, result.output + assert "belief: 0.60" in result.output + assert "(principal, " in result.output + assert "registered 0.35" in result.output + + +class TestResolve: + def test_grades_once_and_refuses_a_second_time(self, cli_runner, stored_watch): + with _patch_db(stored_watch): + first = cli_runner.invoke( + watch_command, + ["resolve", "conmon-scope-expands", "--outcome", "no", "--note", "deviation"], + ) + second = cli_runner.invoke( + watch_command, + ["resolve", "conmon-scope-expands", "--outcome", "yes", "--note", "changed"], + ) + listing = cli_runner.invoke(watch_command, ["list"]) + + assert first.exit_code == 0, first.output + assert "resolved no" in first.output + assert second.exit_code != 0 + row = stored_watch.get(WatchRow, "conmon-scope-expands") + assert (row.outcome, row.resolution_note) == ("no", "deviation") + assert "[resolved no" in listing.output + + def test_list_marks_a_retired_watch(self, cli_runner, stored_watch): + from datetime import datetime + + stored_watch.get(WatchRow, "conmon-scope-expands").retired_at = datetime(2026, 8, 30) + stored_watch.commit() + + with _patch_db(stored_watch): + result = cli_runner.invoke(watch_command, ["list"]) + + assert result.exit_code == 0, result.output + assert "[retired 2026-08-30]" in result.output + + def test_refuses_an_outcome_outside_yes_no(self, cli_runner, stored_watch): + with _patch_db(stored_watch): + result = cli_runner.invoke( + watch_command, + ["resolve", "conmon-scope-expands", "--outcome", "maybe", "--note", "n"], + ) + + assert result.exit_code != 0 diff --git a/tests/config/conftest.py b/tests/config/conftest.py deleted file mode 100644 index 3e20bbc..0000000 --- a/tests/config/conftest.py +++ /dev/null @@ -1,31 +0,0 @@ -""" -Config-specific test fixtures -""" - -import pytest - - -@pytest.fixture -def clean_env(monkeypatch): - """Clear environment variables that might affect settings""" - env_vars = [ - "DATABASE_URL", - "ANTHROPIC_API_KEY", - "DEBUG", - "LOG_LEVEL", - "ENABLE_SMART_RSS_FETCH", - ] - for var in env_vars: - monkeypatch.delenv(var, raising=False) - return monkeypatch - - -@pytest.fixture -def sample_feed_config(): - """Sample feed configuration for testing""" - return { - "name": "Test Feed", - "url": "https://example.com/feed.xml", - "category": "test_category", - "description": "A test feed for testing purposes", - } diff --git a/tests/config/test_credentials.py b/tests/config/test_credentials.py new file mode 100644 index 0000000..178968a --- /dev/null +++ b/tests/config/test_credentials.py @@ -0,0 +1,70 @@ +""" +Credentials: keychain only, lazy, and never defaulted. +""" + +import pytest + +from src.config import credentials +from src.config.settings import settings + + +class TestRead: + def test_a_stored_value_is_returned(self, memory_keyring): + memory_keyring.store[(settings.keyring_service, credentials.ANTHROPIC)] = "sk-test" + assert credentials.read(credentials.ANTHROPIC) == "sk-test" + + def test_a_missing_value_raises_naming_the_fix(self, memory_keyring): + with pytest.raises(credentials.MissingCredential) as excinfo: + credentials.read(credentials.ANTHROPIC) + assert "insightweaver auth set anthropic" in str(excinfo.value) + + def test_an_empty_stored_value_is_missing_not_empty(self, memory_keyring): + memory_keyring.store[(settings.keyring_service, credentials.ANTHROPIC)] = "" + with pytest.raises(credentials.MissingCredential): + credentials.read(credentials.ANTHROPIC) + + def test_the_environment_is_not_consulted(self, memory_keyring, monkeypatch): + """ + There is no ANTHROPIC_API_KEY fallback. A key in the environment and + none in the keychain is a missing key. + """ + monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-from-env") + with pytest.raises(credentials.MissingCredential): + credentials.read(credentials.ANTHROPIC) + + +class TestWriteAndDelete: + def test_write_then_read_round_trips_stripped(self, memory_keyring): + credentials.write(credentials.ANTHROPIC, " sk-test \n") + assert credentials.read(credentials.ANTHROPIC) == "sk-test" + + @pytest.mark.parametrize("blank", ["", " ", "\n"]) + def test_a_blank_value_is_refused_not_stored(self, memory_keyring, blank): + with pytest.raises(ValueError, match="blank"): + credentials.write(credentials.ANTHROPIC, blank) + assert not credentials.is_set(credentials.ANTHROPIC) + + def test_delete_removes_the_entry(self, memory_keyring): + credentials.write(credentials.ANTHROPIC, "sk-test") + credentials.delete(credentials.ANTHROPIC) + assert not credentials.is_set(credentials.ANTHROPIC) + + def test_deleting_an_absent_entry_is_an_error(self, memory_keyring): + with pytest.raises(credentials.MissingCredential): + credentials.delete(credentials.ANTHROPIC) + + +def test_importing_the_module_touches_no_keychain(monkeypatch): + """ + Lookups are lazy. Reloading the module with a keyring that explodes on + contact must succeed; only read() may reach the backend. + """ + import importlib + + import keyring + + def explode(*_args, **_kwargs): + raise AssertionError("keychain touched at import time") + + monkeypatch.setattr(keyring, "get_password", explode) + importlib.reload(credentials) diff --git a/tests/config/test_feeds.py b/tests/config/test_feeds.py deleted file mode 100644 index f16e4dc..0000000 --- a/tests/config/test_feeds.py +++ /dev/null @@ -1,234 +0,0 @@ -""" -Tests for RSS feed configuration -""" - -from src.config.feeds import ( - RSS_FEEDS, - get_all_feeds, - get_category_list, - get_feed_count, - get_feeds_by_category, - get_feeds_by_category_group, - validate_feeds, -) - - -class TestRSSFeedsStructure: - """Tests for RSS_FEEDS data structure""" - - def test_rss_feeds_is_dict(self): - """RSS_FEEDS should be a dictionary""" - assert isinstance(RSS_FEEDS, dict) - - def test_rss_feeds_has_categories(self): - """RSS_FEEDS should have multiple category groups""" - assert len(RSS_FEEDS) > 0 - expected_groups = [ - "government", - "virginia", - "cybersecurity", - "technology", - "news", - ] - for group in expected_groups: - assert group in RSS_FEEDS, f"Category group '{group}' should exist" - - def test_each_category_has_feeds(self): - """Each category group should have at least one feed""" - for group_name, feeds in RSS_FEEDS.items(): - assert isinstance(feeds, list), f"{group_name} should be a list" - assert len(feeds) > 0, f"{group_name} should have at least one feed" - - def test_feed_has_required_fields(self): - """Each feed should have required fields""" - required_fields = ["name", "url", "category", "description"] - - for group_name, feeds in RSS_FEEDS.items(): - for i, feed in enumerate(feeds): - for field in required_fields: - assert field in feed, f"{group_name}[{i}] missing '{field}'" - assert feed[field], f"{group_name}[{i}] has empty '{field}'" - - -class TestGetAllFeeds: - """Tests for get_all_feeds function""" - - def test_returns_list(self): - """get_all_feeds should return a list""" - result = get_all_feeds() - assert isinstance(result, list) - - def test_returns_all_feeds(self): - """get_all_feeds should return all feeds from all categories""" - result = get_all_feeds() - - total_expected = sum(len(feeds) for feeds in RSS_FEEDS.values()) - assert len(result) == total_expected - - def test_adds_category_group(self): - """get_all_feeds should add category_group to each feed""" - result = get_all_feeds() - - for feed in result: - assert "category_group" in feed - assert feed["category_group"] in RSS_FEEDS - - def test_preserves_original_fields(self): - """get_all_feeds should preserve original feed fields""" - result = get_all_feeds() - - for feed in result: - assert "name" in feed - assert "url" in feed - assert "category" in feed - assert "description" in feed - - -class TestGetFeedsByCategory: - """Tests for get_feeds_by_category function""" - - def test_returns_matching_feeds(self): - """Should return feeds with matching category""" - result = get_feeds_by_category("security_news") - - assert isinstance(result, list) - for feed in result: - assert feed["category"] == "security_news" - - def test_returns_empty_for_nonexistent_category(self): - """Should return empty list for non-existent category""" - result = get_feeds_by_category("nonexistent_category_xyz") - - assert isinstance(result, list) - assert len(result) == 0 - - def test_adds_category_group(self): - """Should add category_group to returned feeds""" - result = get_feeds_by_category("security_news") - - for feed in result: - assert "category_group" in feed - - -class TestGetFeedsByCategoryGroup: - """Tests for get_feeds_by_category_group function""" - - def test_returns_feeds_for_valid_group(self): - """Should return feeds for valid category group""" - result = get_feeds_by_category_group("cybersecurity") - - assert isinstance(result, list) - assert len(result) > 0 - - def test_returns_empty_for_invalid_group(self): - """Should return empty list for invalid category group""" - result = get_feeds_by_category_group("invalid_group_xyz") - - assert isinstance(result, list) - assert len(result) == 0 - - def test_returns_same_as_direct_access(self): - """Should return same result as direct RSS_FEEDS access""" - result = get_feeds_by_category_group("government") - - assert result == RSS_FEEDS["government"] - - -class TestGetFeedCount: - """Tests for get_feed_count function""" - - def test_returns_positive_integer(self): - """Should return a positive integer""" - result = get_feed_count() - - assert isinstance(result, int) - assert result > 0 - - def test_matches_all_feeds_length(self): - """Should match length of get_all_feeds()""" - result = get_feed_count() - all_feeds = get_all_feeds() - - assert result == len(all_feeds) - - -class TestGetCategoryList: - """Tests for get_category_list function""" - - def test_returns_sorted_list(self): - """Should return a sorted list""" - result = get_category_list() - - assert isinstance(result, list) - assert result == sorted(result) - - def test_contains_unique_categories(self): - """Should contain unique category values""" - result = get_category_list() - - assert len(result) == len(set(result)) - - def test_contains_expected_categories(self): - """Should contain expected category values""" - result = get_category_list() - - expected = ["security_news", "tech_news", "politics", "general_news"] - for cat in expected: - assert cat in result, f"Category '{cat}' should exist" - - -class TestValidateFeeds: - """Tests for validate_feeds function""" - - def test_returns_list(self): - """Should return a list of issues""" - result = validate_feeds() - - assert isinstance(result, list) - - def test_current_config_has_duplicates(self): - """Current config may have intentional duplicates (Federal Reserve, SEC)""" - # This test documents the current state - # Some feeds appear in multiple categories intentionally - result = validate_feeds() - - # Just verify the function runs - assert isinstance(result, list) - - -class TestFeedUrlFormat: - """Tests for feed URL format validation""" - - def test_all_urls_are_http_or_https(self): - """All feed URLs should use HTTP or HTTPS""" - all_feeds = get_all_feeds() - - for feed in all_feeds: - url = feed["url"] - assert url.startswith("http://") or url.startswith("https://"), ( - f"Invalid URL scheme: {url}" - ) - - def test_no_empty_urls(self): - """No feed should have empty URL""" - all_feeds = get_all_feeds() - - for feed in all_feeds: - assert feed["url"].strip(), f"Empty URL for feed: {feed['name']}" - - -class TestFeedCategories: - """Tests for feed category consistency""" - - def test_category_groups_are_strings(self): - """All category group keys should be strings""" - for key in RSS_FEEDS: - assert isinstance(key, str) - - def test_feed_categories_are_strings(self): - """All feed categories should be strings""" - all_feeds = get_all_feeds() - - for feed in all_feeds: - assert isinstance(feed["category"], str) - assert len(feed["category"]) > 0 diff --git a/tests/config/test_settings.py b/tests/config/test_settings.py index 7223783..503fd47 100644 --- a/tests/config/test_settings.py +++ b/tests/config/test_settings.py @@ -17,82 +17,6 @@ def test_database_url_default(self, monkeypatch): assert "sqlite" in settings_module.settings.database_url - def test_debug_default_false(self, monkeypatch): - """Debug should default to False""" - monkeypatch.delenv("DEBUG", raising=False) - - import importlib - - import src.config.settings as settings_module - - importlib.reload(settings_module) - - assert settings_module.settings.debug is False - - def test_log_level_default(self, monkeypatch): - """Log level should default to INFO""" - monkeypatch.delenv("LOG_LEVEL", raising=False) - - import importlib - - import src.config.settings as settings_module - - importlib.reload(settings_module) - - assert settings_module.settings.log_level == "INFO" - - -class TestBooleanParsing: - """Tests for boolean environment variable parsing""" - - def test_debug_true_string(self, monkeypatch): - """DEBUG=true should parse as True""" - monkeypatch.setenv("DEBUG", "true") - - import importlib - - import src.config.settings as settings_module - - importlib.reload(settings_module) - - assert settings_module.settings.debug is True - - def test_debug_True_string(self, monkeypatch): - """DEBUG=True should parse as True""" - monkeypatch.setenv("DEBUG", "True") - - import importlib - - import src.config.settings as settings_module - - importlib.reload(settings_module) - - assert settings_module.settings.debug is True - - def test_debug_false_string(self, monkeypatch): - """DEBUG=false should parse as False""" - monkeypatch.setenv("DEBUG", "false") - - import importlib - - import src.config.settings as settings_module - - importlib.reload(settings_module) - - assert settings_module.settings.debug is False - - def test_debug_FALSE_string(self, monkeypatch): - """DEBUG=FALSE should parse as False (case insensitive)""" - monkeypatch.setenv("DEBUG", "FALSE") - - import importlib - - import src.config.settings as settings_module - - importlib.reload(settings_module) - - assert settings_module.settings.debug is False - class TestPathConfiguration: """Tests for path configuration""" @@ -118,25 +42,3 @@ def test_data_dir_created(self): from src.config.settings import settings assert settings.data_dir.exists() - - def test_logs_dir_created(self): - """Settings should create logs directory""" - from src.config.settings import settings - - assert settings.logs_dir.exists() - - -class TestFeatureFlags: - """Tests for feature flag configuration""" - - def test_smart_rss_fetch_default(self, monkeypatch): - """Smart RSS fetch should default to enabled""" - monkeypatch.delenv("ENABLE_SMART_RSS_FETCH", raising=False) - - import importlib - - import src.config.settings as settings_module - - importlib.reload(settings_module) - - assert settings_module.settings.enable_smart_rss_fetch is True diff --git a/tests/conftest.py b/tests/conftest.py index deb2c2a..a921623 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -1,134 +1,70 @@ """ Shared test fixtures for all InsightWeaver tests -Provides mocks for ClaudeClient, web_fetch, and common test data """ +import keyring +import keyring.backend import pytest +from keyring.errors import PasswordDeleteError from sqlalchemy import create_engine from sqlalchemy.orm import sessionmaker from src.database.models import Base -@pytest.fixture -def test_engine(tmp_path): - """Create temporary SQLite database with all tables.""" - db_path = tmp_path / "test.db" - engine = create_engine(f"sqlite:///{db_path}", echo=False) - Base.metadata.create_all(bind=engine) - return engine +class MemoryKeyring(keyring.backend.KeyringBackend): + """A keyring that forgets everything when the test ends. See memory_keyring.""" + priority = 1 # type: ignore[assignment] -@pytest.fixture -def test_session(test_engine): - """Database session for tests.""" - Session = sessionmaker(bind=test_engine) - session = Session() - yield session - session.close() - + def __init__(self) -> None: + super().__init__() + self.store: dict[tuple[str, str], str] = {} -@pytest.fixture -def mock_claude_client(mocker): - """ - Mock ClaudeClient for all tests + def get_password(self, service: str, username: str) -> str | None: + return self.store.get((service, username)) - Returns an AsyncMock that can be configured per test to return - specific JSON responses from the analyze() method. - """ - mock_client = mocker.AsyncMock() - mock_client.analyze = mocker.AsyncMock() - return mock_client + def set_password(self, service: str, username: str, password: str) -> None: + self.store[(service, username)] = password - -@pytest.fixture -def mock_web_fetch(mocker): - """ - Mock web_fetch for authoritative source testing - - Returns an AsyncMock that can be configured to return specific - content from web sources without making real HTTP requests. - """ - mock_fetch = mocker.patch("src.utils.web_tools.web_fetch", new_callable=mocker.AsyncMock) - return mock_fetch + def delete_password(self, service: str, username: str) -> None: + if (service, username) not in self.store: + raise PasswordDeleteError(f"{service}/{username} is not stored") + del self.store[(service, username)] @pytest.fixture -def mock_authoritative_sources(): +def memory_keyring(): """ - Mock authoritative_sources.yaml config + An in-memory keyring backend for the duration of one test. - Returns a dictionary mimicking the YAML structure with test sources. + Shared here rather than in tests/config/ because the model client in + tests/llm/ reads the keychain too. Every test that touches credentials uses + it, so the suite never reads or writes the operator's real keychain and runs + identically on CI, which has none. (2026-09-22, backlog task 026.) """ - return { - "sources": [ - { - "name": "Test US President Source", - "keywords": ["president", "united states", "potus"], - "url": "https://test.whitehouse.gov/administration/president", - "query_prompt": "Who is the current president of the United States?", - }, - { - "name": "Test Prime Minister India", - "keywords": ["prime minister", "india"], - "url": "https://test.pmindia.gov.in", - "query_prompt": "Who is the current Prime Minister of India?", - }, - { - "name": "Test CEO Apple", - "keywords": ["ceo", "apple", "leadership"], - "url": "https://test.apple.com/leadership", - "query_prompt": "Who is the current CEO of Apple?", - }, - { - "name": "Test Unemployment Rate", - "keywords": ["unemployment", "rate", "labor", "jobs"], - "url": "https://test.bls.gov/unemployment", - "query_prompt": "What is the current unemployment rate?", - }, - { - "name": "Test Wikipedia Country Template", - "keywords": ["country", "wikipedia"], - "url_template": "https://en.wikipedia.org/wiki/{country}", - "requires_country_extraction": True, - "query_prompt": "Extract information about the country from Wikipedia", - }, - ], - "fallback": { - "enabled": True, - "reason": "No authoritative source available for verification beyond model knowledge cutoff", - }, - } + previous = keyring.get_keyring() + backend = MemoryKeyring() + keyring.set_keyring(backend) + try: + yield backend + finally: + keyring.set_keyring(previous) @pytest.fixture -def sample_response(): - """ - Sample Claude response with various claim types for testing - """ - return """The unemployment rate is 3.7% as of December 2025. This suggests a strong labor market. - It's possible that rates will remain low through 2026. Many economists believe the economy is healthy.""" - - -@pytest.fixture -def mock_settings(monkeypatch): - """ - Mock settings for testing without requiring .env file - """ - monkeypatch.setenv("ANTHROPIC_API_KEY", "test-api-key-12345") - monkeypatch.setenv("DEBUG", "false") - monkeypatch.setenv("LOG_LEVEL", "INFO") - return None +def test_engine(tmp_path): + """Create temporary SQLite database with all tables.""" + db_path = tmp_path / "test.db" + engine = create_engine(f"sqlite:///{db_path}", echo=False) + Base.metadata.create_all(bind=engine) + return engine @pytest.fixture -def temp_yaml_file(tmp_path, mock_authoritative_sources): - """ - Create a temporary YAML file with mock sources for testing - """ - import yaml - - yaml_path = tmp_path / "authoritative_sources.yaml" - with open(yaml_path, "w") as f: - yaml.dump(mock_authoritative_sources, f) - return yaml_path +def test_session(test_engine): + """Database session for tests.""" + Session = sessionmaker(bind=test_engine) + session = Session() + yield session + session.close() diff --git a/tests/database/test_add_monitor_tables.py b/tests/database/test_add_monitor_tables.py new file mode 100644 index 0000000..85d8171 --- /dev/null +++ b/tests/database/test_add_monitor_tables.py @@ -0,0 +1,182 @@ +""" +Tests for the migration that adds the decision monitor's tables (backlog task 028). + +Mirrors tests/database/test_add_watches_table.py: the table is built from the +model, so the tests are weighted towards what would be silently lost if it were +ever replaced with hand-written DDL -- the UNIQUE and CHECK constraints -- and +towards the way down, which loses rows and refuses without ``--confirm``. + +Every fixture builds its own SQLite file. Nothing here opens the real database. +""" + +import pytest +from sqlalchemy import create_engine, inspect, text + +from src.database.migrations import add_monitor_tables as mig +from src.database.models import Route + + +@pytest.fixture +def blank_engine(tmp_path): + return create_engine(f"sqlite:///{tmp_path / 'fresh.db'}") + + +class TestUpgrade: + def test_creates_routes_and_returns_its_name(self, blank_engine): + assert mig.upgrade(blank_engine) == ["routes", "adjudications", "watch_beliefs", "briefs"] + assert inspect(blank_engine).has_table("routes") + + def test_is_idempotent(self, blank_engine): + mig.upgrade(blank_engine) + assert mig.upgrade(blank_engine) == [] + + def test_columns_match_the_route_model(self, blank_engine): + mig.upgrade(blank_engine) + created = {c["name"] for c in inspect(blank_engine).get_columns("routes")} + assert created == set(Route.__table__.columns.keys()) + + def test_the_unique_and_check_constraints_are_in_the_created_ddl(self, blank_engine): + """ + Read from sqlite_master rather than from the model: the question is what + the migration actually created, not what it intended to. + """ + mig.upgrade(blank_engine) + with blank_engine.connect() as conn: + ddl = conn.execute( + text("SELECT sql FROM sqlite_master WHERE type='table' AND name='routes'") + ).scalar() + + assert "_route_observation_watch_uc" in ddl + assert "UNIQUE (observation_hash, watch_id)" in ddl + assert "ck_routes_clause_index" in ddl + assert "CHECK (clause_index >= 0)" in ddl + + def test_touches_nothing_else(self, blank_engine): + """Additive means additive: it creates one table and no others.""" + mig.upgrade(blank_engine) + assert set(inspect(blank_engine).get_table_names()) == { + "routes", + "adjudications", + "watch_beliefs", + "briefs", + } + + +class TestDowngrade: + def test_refuses_without_confirm(self, blank_engine): + mig.upgrade(blank_engine) + with pytest.raises(SystemExit) as exc: + mig.downgrade(blank_engine) + assert "--confirm" in str(exc.value) + assert inspect(blank_engine).has_table("routes") + + def test_drops_with_confirm(self, blank_engine): + mig.upgrade(blank_engine) + assert mig.downgrade(blank_engine, confirmed=True) == [ + "briefs", + "watch_beliefs", + "adjudications", + "routes", + ] + assert not inspect(blank_engine).has_table("routes") + + def test_drop_on_a_missing_table_is_a_no_op(self, blank_engine): + assert mig.downgrade(blank_engine, confirmed=True) == [] + + +class TestMainEntryPoint: + def test_down_without_confirm_exits_non_zero(self, blank_engine, monkeypatch): + """ + Drives ``main`` rather than ``downgrade`` directly, to prove the CLI + wiring refuses too, not just the function it calls. + + The module-level ``engine`` is patched to the throwaway file so this + exercises ``main``'s argument parsing without ever touching whatever + DATABASE_URL names. + """ + monkeypatch.setattr(mig, "engine", blank_engine) + mig.upgrade(blank_engine) + + with pytest.raises(SystemExit) as exc: + mig.main(["--down"]) + + assert exc.value.code + assert inspect(blank_engine).has_table("routes") + + +class TestWatchColumns: + """ + Task 030 added four lifecycle columns to ``watches``. A fresh table has them + from the model; an older table gets them from the migration, one ALTER each. + """ + + OLD_WATCHES_DDL = ( + "CREATE TABLE watches (id VARCHAR(100) PRIMARY KEY, claim TEXT NOT NULL, " + "belief FLOAT NOT NULL, decision_key VARCHAR(100) NOT NULL, so_what TEXT NOT NULL, " + "triggers JSON NOT NULL, expires DATE NOT NULL, staleness_alert_days INTEGER NOT NULL, " + "created_at DATETIME, updated_at DATETIME)" + ) + + def test_an_older_watches_table_gains_the_columns_and_the_check(self, blank_engine): + with blank_engine.begin() as conn: + conn.execute(text(self.OLD_WATCHES_DDL)) + + added = mig.add_watch_columns(blank_engine) + + assert added == ["retired_at", "resolved_at", "outcome", "resolution_note"] + columns = {c["name"] for c in inspect(blank_engine).get_columns("watches")} + assert set(mig.WATCH_COLUMNS) <= columns + with blank_engine.begin() as conn, pytest.raises(Exception, match="CHECK"): + conn.execute( + text( + "INSERT INTO watches (id, claim, belief, decision_key, so_what, triggers, " + "expires, staleness_alert_days, outcome) VALUES ('w', 'c', 0.5, 'd', 's', " + "'[]', '2027-01-01', 30, 'maybe')" + ) + ) + + def test_adding_the_columns_twice_adds_nothing_the_second_time(self, blank_engine): + with blank_engine.begin() as conn: + conn.execute(text(self.OLD_WATCHES_DDL)) + mig.add_watch_columns(blank_engine) + + assert mig.add_watch_columns(blank_engine) == [] + + def test_a_fresh_table_from_the_model_needs_no_alter(self, blank_engine): + from src.database.models import Watch + + Watch.__table__.create(bind=blank_engine) + + assert mig.add_watch_columns(blank_engine) == [] + + def test_no_watches_table_means_nothing_to_alter(self, blank_engine): + assert mig.add_watch_columns(blank_engine) == [] + + def test_the_altered_table_carries_the_named_check_like_the_model_does(self, blank_engine): + with blank_engine.begin() as conn: + conn.execute(text(self.OLD_WATCHES_DDL)) + mig.add_watch_columns(blank_engine) + + with blank_engine.connect() as conn: + ddl = conn.execute( + text("SELECT sql FROM sqlite_master WHERE type='table' AND name='watches'") + ).scalar() + assert "ck_watches_outcome" in ddl + + def test_downgrade_on_a_schema_created_from_the_models_drops_columns_then_tables( + self, blank_engine + ): + """ + A fresh install builds watches from the model, whose outcome CHECK is a + column constraint precisely so that this DROP COLUMN is allowed. + """ + from src.database.models import Base + + Base.metadata.create_all(bind=blank_engine) + + dropped = mig.downgrade(blank_engine, confirmed=True) + + assert dropped == ["briefs", "watch_beliefs", "adjudications", "routes"] + columns = {c["name"] for c in inspect(blank_engine).get_columns("watches")} + assert columns.isdisjoint(mig.WATCH_COLUMNS) + assert inspect(blank_engine).has_table("watches") diff --git a/tests/database/test_connection.py b/tests/database/test_connection.py index 2af0b34..fad3612 100644 --- a/tests/database/test_connection.py +++ b/tests/database/test_connection.py @@ -3,7 +3,7 @@ """ import pytest -from sqlalchemy import create_engine, text +from sqlalchemy import text from sqlalchemy.orm import Session @@ -92,57 +92,3 @@ def test_get_db_closes_session_on_exit(self, test_engine, mocker): # Note: Session.is_active may still be True after close(), # but the session should be unusable assert session_ref is not None - - -class TestCreateTables: - """Tests for create_tables function""" - - def test_create_tables_creates_all_tables(self, tmp_path, mocker): - """create_tables should create all defined tables""" - # Create a fresh engine - db_path = tmp_path / "fresh.db" - engine = create_engine(f"sqlite:///{db_path}") - - # Mock the engine - mocker.patch("src.database.connection.engine", engine) - - from src.database.connection import create_tables - - create_tables() - - # Verify tables were created - from sqlalchemy import inspect - - inspector = inspect(engine) - table_names = inspector.get_table_names() - - # Asserted as a set rather than a subset: backlog task 012 deleted - # nineteen models, and a subset check would pass again the moment one of - # them was reintroduced by accident. `watches` was added deliberately by - # task 013 (2026-08-31); `observations` and `evidence` by task 014 the - # same day. Every addition here should be a task that says so. - assert set(table_names) == { - "rss_feeds", - "articles", - "watches", - "observations", - "evidence", - } - - def test_create_tables_is_idempotent(self, tmp_path, mocker): - """create_tables should be safe to call multiple times""" - db_path = tmp_path / "idempotent.db" - engine = create_engine(f"sqlite:///{db_path}") - mocker.patch("src.database.connection.engine", engine) - - from src.database.connection import create_tables - - # Call twice - should not raise - create_tables() - create_tables() - - # Tables should still exist - from sqlalchemy import inspect - - inspector = inspect(engine) - assert "rss_feeds" in inspector.get_table_names() diff --git a/tests/database/test_create_schema.py b/tests/database/test_create_schema.py new file mode 100644 index 0000000..0046e83 --- /dev/null +++ b/tests/database/test_create_schema.py @@ -0,0 +1,39 @@ +""" +The bootstrap for a fresh database (2026-09-23, backlog task 033). +""" + +from sqlalchemy import create_engine, inspect + +from src.database.migrations import add_monitor_tables, create_schema +from src.database.models import Base + + +def _blank(tmp_path): + return create_engine(f"sqlite:///{tmp_path / 'fresh.db'}") + + +def test_a_fresh_database_gets_every_declared_table(tmp_path): + engine = _blank(tmp_path) + + created = create_schema.upgrade(engine) + + assert set(created) == set(Base.metadata.tables) + assert set(inspect(engine).get_table_names()) == set(Base.metadata.tables) + + +def test_running_it_again_creates_nothing(tmp_path): + engine = _blank(tmp_path) + create_schema.upgrade(engine) + + assert create_schema.upgrade(engine) == [] + + +def test_it_creates_only_what_is_absent_and_the_additive_migrations_still_run(tmp_path): + engine = _blank(tmp_path) + add_monitor_tables.upgrade(engine) # an older database with some tables + + created = create_schema.upgrade(engine) + + assert "routes" not in created + assert {"rss_feeds", "articles", "observations", "watches"} <= set(created) + assert add_monitor_tables.upgrade(engine) == [] diff --git a/tests/database/test_models.py b/tests/database/test_models.py index ee3420e..94a9ba5 100644 --- a/tests/database/test_models.py +++ b/tests/database/test_models.py @@ -187,12 +187,15 @@ def test_no_table_in_the_schema_is_person_shaped(self, test_engine): def test_only_the_declared_tables_are_mapped(self): """ Task 012 removed nineteen models. If one comes back by accident, - ``create_tables()`` would recreate a concept the rewrite deleted, so the - mapped set is pinned rather than left to review. + ``Base.metadata.create_all()`` would recreate a concept the rewrite + deleted, so the mapped set is pinned rather than left to review. ``watches`` joined the set on 2026-08-31 (backlog task 013); - ``observations`` and ``evidence`` on 2026-08-31 (backlog task 014). - Every addition to this set should be a task that says so. + ``observations`` and ``evidence`` on 2026-08-31 (backlog task 014); + ``routes`` on 2026-09-22 (backlog task 028); ``adjudications`` the same + day (task 029); ``watch_beliefs`` the same day (task 030); ``briefs`` + the same day (task 031). Every addition to this set should be a task + that says so. """ from src.database.models import Base @@ -202,4 +205,8 @@ def test_only_the_declared_tables_are_mapped(self): "watches", "observations", "evidence", + "routes", + "adjudications", + "watch_beliefs", + "briefs", } diff --git a/tests/evidence/conftest.py b/tests/evidence/conftest.py index 35d4af7..667c1c0 100644 --- a/tests/evidence/conftest.py +++ b/tests/evidence/conftest.py @@ -9,7 +9,7 @@ import pytest -from .stubs import add_observations, add_watches +from .stubs import add_observations, add_routes, add_watches @pytest.fixture @@ -23,5 +23,7 @@ def source(test_session): @pytest.fixture -def observations(test_session, source): +def observations(test_session, watches, source): + """The stored corpus, routed: what the adjudicator is allowed to see.""" + add_routes(test_session) return source diff --git a/tests/evidence/stubs.py b/tests/evidence/stubs.py index 907ac83..ca5a105 100644 --- a/tests/evidence/stubs.py +++ b/tests/evidence/stubs.py @@ -163,3 +163,20 @@ def add_observations(session): store_items(session, source, list(CORPUS_ITEMS)) session.flush() return source + + +def add_routes(session): + """ + Route the stub corpus with the real router. + + Since backlog task 029 (2026-09-22) the adjudicator sees only routed + pairs, so a replay over an unrouted corpus judges nothing. Two of the four + items carry a watch's terms and route; the other two do not. + """ + from datetime import date, datetime + + from src.routing import route + + report = route(session, since=datetime(2026, 1, 1), today=date(2026, 9, 1)) + session.flush() + return report diff --git a/tests/evidence/test_adjudicate.py b/tests/evidence/test_adjudicate.py new file mode 100644 index 0000000..5fefec7 --- /dev/null +++ b/tests/evidence/test_adjudicate.py @@ -0,0 +1,266 @@ +""" +The adjudication run: every routed pair once, every outcome recorded. + +The corpus is the replay stubs' four items and two watches, routed with the +real router, so two pairs are pending. The adjudicator's client is a stub that +answers from a script; no network, no key. +""" + +import json + +import pytest + +from src.config import credentials +from src.database.models import Adjudication, Evidence +from src.evidence import commit, rebuild +from src.evidence.adjudicate import dry_run, pending_pairs, run +from src.evidence.claude_adjudicator import PROMPT_VERSION, ClaudeAdjudicator +from src.llm.claude_client import ModelCallFailed, ModelResponse + +from .stubs import KeywordAdjudicator + + +def _verdict(is_evidence=True, direction="supports", **overrides) -> str: + body = { + "is_evidence": is_evidence, + "direction": direction, + "magnitude": 0.6, + "satisfies_clause": 0 if is_evidence else -1, + "confidence": 0.8, + "rationale": "quoted words", + } + body.update(overrides) + return json.dumps(body) + + +class FakeClient: + def __init__(self, *scripted): + self.scripted = list(scripted) + self.calls = 0 + + def analyze(self, system_prompt, user_message, **kwargs): + self.calls += 1 + item = self.scripted.pop(0) + if isinstance(item, BaseException): + raise item + return ModelResponse( + text=item, + model="m", + stop_reason="end_turn", + input_tokens=100, + output_tokens=10, + cache_read_input_tokens=0, + cache_creation_input_tokens=0, + audit_id=f"audit-{self.calls}", + ) + + +@pytest.fixture +def corpus(test_session, observations): + """The routed stub corpus: doc-1 -> conmon, doc-2 -> hiring.""" + return test_session + + +class TestPendingPairs: + def test_the_routed_pairs_are_pending_in_a_fixed_order(self, corpus): + pairs = pending_pairs(corpus, PROMPT_VERSION) + + assert [p.watch.id for p in pairs] == sorted(p.watch.id for p in pairs) + assert {p.watch.id for p in pairs} == {"conmon-scope-expands", "hiring-market-tightens"} + assert all(p.view.payload["title"] for p in pairs) + + def test_a_pair_already_answered_under_this_version_is_not_pending(self, corpus): + run(corpus, ClaudeAdjudicator(FakeClient(_verdict(), _verdict()))) + + assert pending_pairs(corpus, PROMPT_VERSION) == [] + assert len(pending_pairs(corpus, "some-other-version")) == 2 + + def test_a_pair_with_evidence_committed_by_replay_is_not_asked_again(self, corpus): + """`replay --commit` writes evidence but no ledger row; that still counts as answered.""" + commit(corpus, PROMPT_VERSION, rebuild(corpus, KeywordAdjudicator(PROMPT_VERSION))) + + assert pending_pairs(corpus, PROMPT_VERSION) == [] + result = run(corpus, ClaudeAdjudicator(FakeClient())) + assert result.asked == 0 + + def test_expiry_is_routing_s_gate_not_adjudication_s(self, corpus): + """A routed pair on a watch that has since expired is still asked once.""" + from datetime import date + + from src.database.models import Watch + + corpus.get(Watch, "hiring-market-tightens").expires = date(2020, 1, 1) + corpus.flush() + + assert {p.watch.id for p in pending_pairs(corpus, PROMPT_VERSION)} == { + "conmon-scope-expands", + "hiring-market-tightens", + } + assert {r.watch_id for r in rebuild(corpus, KeywordAdjudicator("v1"))} == { + "conmon-scope-expands", + "hiring-market-tightens", + } + + def test_a_retired_or_resolved_watch_s_pairs_are_not_pending(self, corpus): + """A state the operator set, not a date: asking about a closed watch costs for nothing.""" + from datetime import datetime + + from src.database.models import Watch + from src.position.ledger import resolve_watch + + corpus.get(Watch, "conmon-scope-expands").retired_at = datetime(2026, 8, 30) + resolve_watch(corpus, "hiring-market-tightens", outcome="yes", note="settled") + corpus.flush() + + assert pending_pairs(corpus, PROMPT_VERSION) == [] + assert rebuild(corpus, KeywordAdjudicator("v1")) == [] + + def test_limit_narrows_the_run_and_zero_is_refused(self, corpus): + assert len(pending_pairs(corpus, PROMPT_VERSION, limit=1)) == 1 + with pytest.raises(ValueError, match="at least 1"): + pending_pairs(corpus, PROMPT_VERSION, limit=0) + + +class TestRun: + def test_every_pair_gets_a_ledger_row_and_evidence_gets_an_evidence_row(self, corpus): + client = FakeClient(_verdict(), _verdict(is_evidence=False, direction="none")) + + result = run(corpus, ClaudeAdjudicator(client)) + + assert (result.asked, result.evidence, result.none, result.failed) == (2, 1, 1, 0) + assert (result.input_tokens, result.output_tokens) == (200, 20) + ledger = corpus.query(Adjudication).order_by(Adjudication.watch_id).all() + assert [(a.watch_id, a.outcome, a.audit_id) for a in ledger] == [ + ("conmon-scope-expands", "evidence", "audit-1"), + ("hiring-market-tightens", "none", "audit-2"), + ] + evidence = corpus.query(Evidence).all() + assert [(e.watch_id, e.direction, e.prompt_version) for e in evidence] == [ + ("conmon-scope-expands", "supports", PROMPT_VERSION) + ] + + def test_the_rest_of_a_verdict_is_kept_on_the_ledger_for_none_verdicts_too(self, corpus): + client = FakeClient(_verdict(), _verdict(is_evidence=False, direction="none")) + + run(corpus, ClaudeAdjudicator(client)) + + rows = {a.outcome: a for a in corpus.query(Adjudication).all()} + assert (rows["evidence"].confidence, rows["evidence"].satisfies_clause) == (0.8, 0) + assert (rows["none"].confidence, rows["none"].satisfies_clause) == (0.8, -1) + assert rows["none"].rationale == "quoted words" + + def test_a_second_run_asks_nothing(self, corpus): + client = FakeClient(_verdict(), _verdict()) + run(corpus, ClaudeAdjudicator(client)) + + second = run(corpus, ClaudeAdjudicator(client)) + + assert second.asked == 0 + assert client.calls == 2 + assert corpus.query(Adjudication).count() == 2 + + def test_a_failure_is_recorded_with_its_error_and_cost_and_writes_no_evidence(self, corpus): + client = FakeClient("not json", _verdict()) + + result = run(corpus, ClaudeAdjudicator(client)) + + assert result.failed == 1 + assert result.evidence == 1 + failed = corpus.query(Adjudication).filter(Adjudication.outcome == "failed").one() + assert failed.error is not None and failed.error.startswith("invalid verdict") + assert failed.input_tokens == 100 # the failed call still cost something + assert failed.audit_id == "audit-1" + assert failed.rationale is None + assert result.failures == [(failed.observation_hash, failed.watch_id, failed.error)] + assert corpus.query(Evidence).count() == 1 + + def test_a_refused_call_keeps_its_audit_id_and_cost_on_the_ledger(self, corpus): + refusal = ModelCallFailed( + "Model declined the request (category: x)", + audit_id="audit-refused", + outcome="answered", + input_tokens=500, + output_tokens=3, + stop_reason="refusal", + ) + client = FakeClient(refusal, _verdict()) + + result = run(corpus, ClaudeAdjudicator(client)) + + failed = corpus.query(Adjudication).filter(Adjudication.outcome == "failed").one() + assert failed.audit_id == "audit-refused" + assert (failed.input_tokens, failed.output_tokens) == (500, 3) + assert result.input_tokens == 600 + + def test_a_failed_pair_is_not_asked_again_on_the_next_run(self, corpus): + client = FakeClient( + ModelCallFailed("boom", audit_id="a", outcome="answered"), _verdict(), _verdict() + ) + run(corpus, ClaudeAdjudicator(client)) + + second = run(corpus, ClaudeAdjudicator(client)) + + assert second.asked == 0 + assert client.calls == 2 + + def test_an_interrupted_run_keeps_the_answers_already_committed(self, corpus): + client = FakeClient(_verdict(), KeyboardInterrupt()) + + with pytest.raises(KeyboardInterrupt): + run(corpus, ClaudeAdjudicator(client)) + corpus.rollback() + + assert corpus.query(Adjudication).count() == 1 + assert corpus.query(Evidence).count() == 1 + assert len(pending_pairs(corpus, PROMPT_VERSION)) == 1 + + def test_an_outage_stops_the_run_with_the_pair_left_pending(self, corpus): + outage = ModelCallFailed("APIConnectionError: down", audit_id="a", outcome="unavailable") + client = FakeClient(_verdict(), outage) + + with pytest.raises(ModelCallFailed, match="down"): + run(corpus, ClaudeAdjudicator(client)) + corpus.rollback() + + assert corpus.query(Adjudication).count() == 1 + assert corpus.query(Adjudication).filter(Adjudication.outcome == "failed").count() == 0 + assert len(pending_pairs(corpus, PROMPT_VERSION)) == 1 + + def test_a_rejected_request_stops_the_run_with_earlier_answers_kept(self, corpus): + rejected = ModelCallFailed("BadRequestError: bad schema", audit_id="a", outcome="rejected") + client = FakeClient(_verdict(), rejected) + + with pytest.raises(ModelCallFailed, match="bad schema"): + run(corpus, ClaudeAdjudicator(client)) + corpus.rollback() + + assert corpus.query(Adjudication).count() == 1 + assert corpus.query(Adjudication).filter(Adjudication.outcome == "failed").count() == 0 + + def test_a_missing_key_raises_before_anything_is_written(self, corpus, memory_keyring): + """A configuration error is not a verdict; no pair may be marked failed by it.""" + with pytest.raises(credentials.MissingCredential): + run(corpus, ClaudeAdjudicator()) + + assert corpus.query(Adjudication).count() == 0 + assert len(pending_pairs(corpus, PROMPT_VERSION)) == 2 + + def test_limit_asks_only_that_many(self, corpus): + client = FakeClient(_verdict(), _verdict()) + + result = run(corpus, ClaudeAdjudicator(client), limit=1) + + assert result.asked == 1 + assert client.calls == 1 + + +class TestDryRun: + def test_dry_run_renders_the_text_and_writes_nothing(self, corpus): + previews = dry_run(corpus, PROMPT_VERSION, limit=5) + + assert len(previews) == 2 + for pair, system, user, estimate in previews: + assert system.startswith("You judge") + assert pair.watch.claim in user + assert estimate > 0 + assert corpus.query(Adjudication).count() == 0 diff --git a/tests/evidence/test_claude_adjudicator.py b/tests/evidence/test_claude_adjudicator.py new file mode 100644 index 0000000..b2fcad9 --- /dev/null +++ b/tests/evidence/test_claude_adjudicator.py @@ -0,0 +1,384 @@ +""" +The one model adjudicator: what it sends, what it accepts, what it refuses. + +No test here makes a network call. The client is replaced with a stub whose +``analyze`` returns a scripted :class:`ModelResponse`, so the tests cover the +adjudicator's own promises: the prompt is pinned to its version, a verdict is +validated on receipt, a failure is recorded once and never retried, and the +protocol method only ever sees routed watches. +""" + +import json +from datetime import date + +import pytest +from pydantic import ValidationError + +from src.config import credentials +from src.database.models import Watch +from src.evidence import ObservationView, Verdict, known_prompt_versions, resolve +from src.evidence.claude_adjudicator import ( + PROMPT_FINGERPRINT, + PROMPT_VERSION, + SCHEMA, + AdjudicationFailed, + AdjudicationVerdict, + ClaudeAdjudicator, + api_schema, +) +from src.evidence.prompt import EFFORT, MAX_TOKENS, TEXT_CAP, build_messages, estimate_tokens +from src.llm.claude_client import ModelCallFailed, ModelResponse + +# Change the prompt, the effort, the schema, the cap or max_tokens and this +# changes; then PROMPT_VERSION must change too, or two different judges share +# one name in every evidence row. The value was computed on 2026-09-22. +PINNED_FINGERPRINT = ( + "07ca3d984c03f131802542bb77eeefe902f2b8db8c34e20d46405b6ba93a9674" # pragma: allowlist secret +) + + +def _watch(**overrides) -> Watch: + fields = { + "id": "conmon-scope-expands", + "claim": "Continuous monitoring scope expands before the assessment window.", + "belief": 0.35, + "decision_key": "renew-authorization", + "so_what": "Scope expansion moves renewal past the point where lapsing is cheaper.", + "triggers": [{"terms": ["continuous monitoring", "conmon"]}, {"sources": ["FR"]}], + "expires": date(2027, 3, 31), + "staleness_alert_days": 30, + } + fields.update(overrides) + return Watch(**fields) + + +def _view(text="The agency expanded continuous monitoring today.", **payload) -> ObservationView: + base = { + "title": "Agency expands continuous monitoring scope", + "normalized_content": text, + "source_url": "https://example.gov/api", + "published_date": "2026-08-20T09:00:00", + } + base.update(payload) + return ObservationView(content_hash="sha256:abc", payload=base) + + +def _verdict(**overrides) -> str: + body = { + "is_evidence": True, + "direction": "supports", + "magnitude": 0.7, + "satisfies_clause": 0, + "confidence": 0.8, + "rationale": "The text says scope expanded.", + } + body.update(overrides) + return json.dumps(body) + + +def _response(text: str, stop_reason: str = "end_turn") -> ModelResponse: + return ModelResponse( + text=text, + model="m", + stop_reason=stop_reason, + input_tokens=120, + output_tokens=30, + cache_read_input_tokens=0, + cache_creation_input_tokens=0, + audit_id="audit-1", + ) + + +class FakeClient: + """Answers each call with the next scripted text, or raises the next error.""" + + def __init__(self, *scripted): + self.scripted = list(scripted) + self.calls: list[dict] = [] + + def analyze(self, system_prompt, user_message, **kwargs): + self.calls.append({"system": system_prompt, "user": user_message, **kwargs}) + item = self.scripted.pop(0) + if isinstance(item, Exception): + raise item + if isinstance(item, tuple): + return _response(*item) + return _response(item) + + +class TestPromptIdentity: + def test_the_prompt_fingerprint_is_pinned_to_the_version(self): + assert PROMPT_VERSION == "claude-v1" + assert PROMPT_FINGERPRINT == PINNED_FINGERPRINT, ( + "the prompt, effort, schema, text cap or max_tokens changed: bump PROMPT_VERSION " + "and update PINNED_FINGERPRINT in the same commit" + ) + + def test_the_version_is_registered_without_building_a_client(self, monkeypatch): + def explode(*_args, **_kwargs): + raise AssertionError("a client was constructed") + + monkeypatch.setattr("src.evidence.claude_adjudicator.ClaudeClient", explode) + + assert "claude-v1" in known_prompt_versions() + adjudicator = resolve("claude-v1") + assert isinstance(adjudicator, ClaudeAdjudicator) + build_messages(_view(), _watch()) + + +class TestMessages: + def test_the_user_message_carries_the_claim_the_stake_and_the_indexed_clauses(self): + system, user = build_messages(_view(), _watch()) + + assert system.startswith("You judge whether one published item") + assert "Continuous monitoring scope expands" in user + assert "renew-authorization" in user + assert "lapsing is cheaper" in user + assert "0: terms: continuous monitoring, conmon" in user + assert "1: sources: FR" in user + assert "source: https://example.gov/api" in user + assert "published: 2026-08-20T09:00:00" in user + assert "title: Agency expands continuous monitoring scope" in user + + def test_long_text_is_capped_and_the_message_says_so(self): + long_text = "x" * (TEXT_CAP + 500) + + _system, user = build_messages(_view(text=long_text), _watch()) + + assert f"{TEXT_CAP + 500} characters, truncated to {TEXT_CAP}" in user + body = user.rsplit("):\n", 1)[1] # the text line is the last one in the template + assert body == "x" * TEXT_CAP + + def test_short_text_is_sent_whole_with_its_length(self): + _system, user = build_messages(_view(text="short body"), _watch()) + + assert "text (10 characters):" in user + assert "truncated" not in user + + def test_the_estimate_is_a_character_count_not_a_token_count(self): + assert estimate_tokens("a" * 40, "b" * 40) == 20 + + +class TestVerdictValidation: + def test_a_well_formed_verdict_validates(self): + verdict = AdjudicationVerdict.model_validate_json(_verdict()) + assert verdict.direction == "supports" + + def test_evidence_without_a_direction_is_refused(self): + with pytest.raises(ValidationError, match="must carry a direction"): + AdjudicationVerdict.model_validate_json(_verdict(direction="none")) + + def test_non_evidence_with_a_direction_is_refused(self): + with pytest.raises(ValidationError, match="carries no direction"): + AdjudicationVerdict.model_validate_json(_verdict(is_evidence=False)) + + @pytest.mark.parametrize( + "field, value", + [("magnitude", 1.5), ("confidence", -0.1), ("direction", "maybe"), ("rationale", "")], + ) + def test_out_of_range_fields_are_refused(self, field, value): + with pytest.raises(ValidationError): + AdjudicationVerdict.model_validate_json(_verdict(**{field: value})) + + def test_an_unexpected_field_is_refused(self): + with pytest.raises(ValidationError): + AdjudicationVerdict.model_validate_json(_verdict(recommendation="sell")) + + def test_the_schema_sent_to_the_api_is_derived_from_the_model(self): + assert api_schema(AdjudicationVerdict) == SCHEMA + assert set(SCHEMA["required"]) == set(AdjudicationVerdict.model_fields) + assert set(SCHEMA["properties"]) == set(AdjudicationVerdict.model_fields) + assert SCHEMA["properties"]["direction"]["enum"] == ["supports", "contradicts", "none"] + assert SCHEMA["additionalProperties"] is False + + def test_the_schema_carries_no_keyword_the_api_rejects(self): + rejected = {"minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "minLength"} + + def keys(node): + if isinstance(node, dict): + for k, v in node.items(): + yield k + yield from keys(v) + elif isinstance(node, list): + for item in node: + yield from keys(item) + + assert rejected.isdisjoint(set(keys(SCHEMA))) + # The ranges still hold on receipt, where pydantic enforces them. + assert "0 to 1" in SCHEMA["properties"]["magnitude"]["description"] + + +class TestJudge: + def test_a_valid_evidence_verdict_is_returned_with_its_cost(self): + client = FakeClient(_verdict()) + judgement = ClaudeAdjudicator(client).judge(_view(), _watch()) + + assert judgement.outcome == "evidence" + assert judgement.verdict is not None + assert judgement.verdict.magnitude == 0.7 + assert judgement.error is None + assert judgement.audit_id == "audit-1" + assert (judgement.input_tokens, judgement.output_tokens) == (120, 30) + + def test_the_call_uses_the_versioned_effort_cap_and_schema(self): + client = FakeClient(_verdict()) + ClaudeAdjudicator(client).judge(_view(), _watch()) + + (call,) = client.calls + assert call["effort"] == EFFORT + assert call["max_tokens"] == MAX_TOKENS + assert call["output_schema"] is SCHEMA + + def test_a_reply_cut_off_at_max_tokens_is_a_failure_that_names_the_cause(self): + client = FakeClient(('{"is_evidence": true', "max_tokens")) + judgement = ClaudeAdjudicator(client).judge(_view(), _watch()) + + assert judgement.outcome == "failed" + assert "max_tokens" in (judgement.error or "") + assert judgement.audit_id == "audit-1" + + def test_a_clause_index_the_watch_does_not_have_is_a_failure(self): + client = FakeClient(_verdict(satisfies_clause=7)) + judgement = ClaudeAdjudicator(client).judge(_view(), _watch()) + + assert judgement.outcome == "failed" + assert "satisfies_clause 7" in (judgement.error or "") + + def test_a_missing_key_raises_before_the_call_and_is_not_a_verdict(self, memory_keyring): + with pytest.raises(credentials.MissingCredential): + ClaudeAdjudicator().judge(_view(), _watch()) + + def test_a_none_verdict_is_recorded_as_none(self): + client = FakeClient(_verdict(is_evidence=False, direction="none", satisfies_clause=-1)) + judgement = ClaudeAdjudicator(client).judge(_view(), _watch()) + + assert judgement.outcome == "none" + assert judgement.error is None + + def test_malformed_json_is_a_failure_with_the_cost_kept(self): + client = FakeClient("not json at all") + judgement = ClaudeAdjudicator(client).judge(_view(), _watch()) + + assert judgement.outcome == "failed" + assert judgement.verdict is None + assert judgement.error is not None and judgement.error.startswith("invalid verdict") + assert judgement.audit_id == "audit-1" + assert judgement.input_tokens == 120 + + def test_a_refusal_or_api_error_is_a_failure_with_its_cost_and_is_not_retried(self): + refusal = ModelCallFailed( + "Model declined the request (category: x)", + audit_id="audit-r", + outcome="answered", + input_tokens=400, + output_tokens=2, + stop_reason="refusal", + ) + client = FakeClient(refusal, _verdict()) + judgement = ClaudeAdjudicator(client).judge(_view(), _watch()) + + assert judgement.outcome == "failed" + assert judgement.error == "Model declined the request (category: x)" + assert judgement.audit_id == "audit-r" + assert (judgement.input_tokens, judgement.output_tokens) == (400, 2) + assert len(client.calls) == 1, "a failed call must not be retried" + assert client.scripted == [_verdict()], "the second scripted answer was never consumed" + + def test_a_rejected_request_aborts_rather_than_becoming_a_verdict(self): + """A 400 or 401 is the operator's problem; no pair may be marked failed by it.""" + rejected = ModelCallFailed("BadRequestError: schema", audit_id="a", outcome="rejected") + client = FakeClient(rejected, _verdict()) + + with pytest.raises(ModelCallFailed, match="schema"): + ClaudeAdjudicator(client).judge(_view(), _watch()) + + def test_an_unavailable_api_aborts_rather_than_burning_the_pair(self): + """An outage is not an answer; the pair stays pending for a later run.""" + outage = ModelCallFailed("APIConnectionError", audit_id="a", outcome="unavailable") + + with pytest.raises(ModelCallFailed, match="APIConnectionError"): + ClaudeAdjudicator(FakeClient(outage, _verdict())).judge(_view(), _watch()) + + def test_a_reply_cut_off_during_thinking_names_max_tokens(self): + cut = ModelCallFailed( + "No text block in response; got blocks: ['thinking']", + audit_id="a", + outcome="answered", + input_tokens=9, + output_tokens=16000, + stop_reason="max_tokens", + ) + judgement = ClaudeAdjudicator(FakeClient(cut)).judge(_view(), _watch()) + + assert judgement.outcome == "failed" + assert (judgement.error or "").startswith(f"reply cut off at max_tokens={MAX_TOKENS}") + + def test_the_fingerprint_moves_when_what_pydantic_accepts_changes(self, monkeypatch): + """Bounds are stripped from the schema the API sees but change what is accepted back.""" + from src.evidence import claude_adjudicator as module + + original = module.AdjudicationVerdict.model_json_schema + monkeypatch.setattr( + module.AdjudicationVerdict, + "model_json_schema", + classmethod(lambda cls, **kw: {**original(**kw), "properties": {"changed": True}}), + ) + + assert module._fingerprint() != PROMPT_FINGERPRINT # noqa: SLF001 + + def test_an_unexpected_exception_is_not_swallowed_into_a_verdict(self): + """Only the typed model failure is recorded; a bug propagates.""" + client = FakeClient(TypeError("a programming error")) + + with pytest.raises(TypeError): + ClaudeAdjudicator(client).judge(_view(), _watch()) + + def test_a_validation_failure_is_not_coerced_into_a_verdict(self): + client = FakeClient(_verdict(is_evidence=True, direction="none")) + judgement = ClaudeAdjudicator(client).judge(_view(), _watch()) + + assert judgement.outcome == "failed" + assert "must carry a direction" in (judgement.error or "") + + +class TestProtocol: + def test_adjudicate_returns_a_verdict_per_evidence_answer(self): + client = FakeClient(_verdict(), _verdict(is_evidence=False, direction="none")) + verdicts = ClaudeAdjudicator(client).adjudicate(_view(), [_watch(), _watch(id="other")]) + + assert verdicts == [ + Verdict( + watch_id="conmon-scope-expands", + direction="supports", + magnitude=0.7, + rationale="The text says scope expanded.", + ) + ] + + def test_adjudicate_raises_on_a_failure_rather_than_dropping_the_pair(self): + client = FakeClient("garbage") + + with pytest.raises(AdjudicationFailed, match="failed"): + ClaudeAdjudicator(client).adjudicate(_view(), [_watch()]) + + +def test_only_the_adjudicator_constructs_a_client(): + """ + Invariant 4 as a tree property: one module makes model requests, and it + is this one. ``src/llm/claude_client.py`` defines the class and is excluded. + """ + import re + from pathlib import Path + + # A literal-token check: a subclass or an alias would slip past it, and + # the companion test in tests/llm/test_claude_client.py pins the SDK + # constructor the same way. Both are gates against habit, not adversaries. + root = Path(__file__).resolve().parents[2] / "src" + pattern = re.compile(r"\bClaudeClient\(") + allowed = {root / "llm" / "claude_client.py", root / "evidence" / "claude_adjudicator.py"} + offenders = [ + str(p.relative_to(root)) + for p in sorted(root.rglob("*.py")) + if p not in allowed and pattern.search(p.read_text(encoding="utf-8")) + ] + assert offenders == [], f"a client is constructed outside the adjudicator: {offenders}" diff --git a/tests/evidence/test_replay.py b/tests/evidence/test_replay.py index 08ea1b3..b03123d 100644 --- a/tests/evidence/test_replay.py +++ b/tests/evidence/test_replay.py @@ -29,7 +29,7 @@ stored_evidence, ) -from .stubs import CountingAdjudicator, KeywordAdjudicator +from .stubs import CountingAdjudicator, KeywordAdjudicator, add_routes class TestReplayIsDeterministic: @@ -205,11 +205,23 @@ def test_evidence_rows_are_rebuilt_from_observations_alone( class TestRebuildScope: - def test_limit_narrows_the_corpus(self, test_session, watches, observations): + def test_limit_counts_routed_observations_so_a_bounded_replay_judges_something( + self, test_session, watches, observations + ): + """ + Two of the four observations are routed. limit=1 must judge the first + routed one, not the first stored one (which may route to nothing). + """ everything = rebuild(test_session, KeywordAdjudicator("v1")) - assert len(rebuild(test_session, KeywordAdjudicator("v1"), limit=1)) <= len(everything) + bounded = rebuild(test_session, KeywordAdjudicator("v1"), limit=1) + + assert len(everything) == 2 + assert len(bounded) == 1 + assert bounded[0] in everything - def test_an_empty_watch_set_produces_no_evidence(self, test_session, observations): + def test_an_empty_watch_set_produces_no_evidence(self, test_session, source): + """No watches means nothing routes, so the adjudicator is never asked.""" + add_routes(test_session) assert rebuild(test_session, KeywordAdjudicator("v1")) == [] def test_the_adjudicator_sees_only_the_stored_payload( @@ -258,14 +270,14 @@ def test_rebinding_a_version_is_refused(self): with pytest.raises(ValueError, match="already registered"): register(NULL_PROMPT_VERSION, NullAdjudicator) - def test_the_registry_ships_no_llm_adjudicator(self): + def test_the_registry_ships_exactly_one_model_adjudicator(self): """ - The adjudication prompt is backlog task 016, not this task. - - Asserted so that a shipped placeholder cannot quietly become the thing - producing evidence. + Invariant 4: one stochastic component. Since backlog task 029 + (2026-09-22) that is ``claude-v1``; the null adjudicator is the other + entry and finds nothing. A second model version is a deliberate + addition to this list, not a drift. """ - assert known_prompt_versions() == [NULL_PROMPT_VERSION] + assert known_prompt_versions() == ["claude-v1", NULL_PROMPT_VERSION] def test_an_adjudicator_can_be_loaded_by_path(self): adjudicator = load_adjudicator("tests.evidence.stubs:make_v1") @@ -288,3 +300,41 @@ def test_replay_needs_no_api_key(self, test_session, watches, observations, monk """ monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False) assert rebuild(test_session, KeywordAdjudicator("v1")) + + +class TestClosedWatches: + """Task 030: retired and resolved watches are outside a replay; expired ones are not.""" + + def test_rebuild_skips_a_retired_watch_and_keeps_an_expired_one( + self, test_session, watches, observations + ): + from datetime import date, datetime + + from src.database.models import Watch + + test_session.get(Watch, "conmon-scope-expands").retired_at = datetime(2026, 8, 30) + test_session.get(Watch, "hiring-market-tightens").expires = date(2020, 1, 1) + test_session.flush() + + rows = rebuild(test_session, KeywordAdjudicator("v1")) + + assert [r.watch_id for r in rows] == ["hiring-market-tightens"] + + def test_commit_never_deletes_a_closed_watch_s_stored_rows( + self, test_session, watches, observations + ): + from datetime import datetime + + from src.database.models import Evidence, Watch + + commit(test_session, "v1", rebuild(test_session, KeywordAdjudicator("v1"))) + assert test_session.query(Evidence).count() == 2 + test_session.get(Watch, "conmon-scope-expands").retired_at = datetime(2026, 8, 30) + test_session.flush() + + written = commit(test_session, "v1", rebuild(test_session, KeywordAdjudicator("v1"))) + + assert written == {"inserted": 0, "deleted": 0} + assert test_session.query(Evidence).count() == 2 + assert len(stored_evidence(test_session, "v1")) == 1 + assert len(stored_evidence(test_session, "v1", open_only=False)) == 2 diff --git a/tests/llm/test_audit.py b/tests/llm/test_audit.py new file mode 100644 index 0000000..f3d4643 --- /dev/null +++ b/tests/llm/test_audit.py @@ -0,0 +1,71 @@ +""" +The audit log: written before the send, one file per day, JSON lines. +""" + +import json +from pathlib import Path + +import pytest + +from src.config.settings import settings +from src.llm import audit + + +@pytest.fixture +def audit_dir(tmp_path, monkeypatch): + target = tmp_path / "llm-audit" + monkeypatch.setattr(settings, "llm_audit_dir", target) + return target + + +def _lines(directory: Path) -> list[dict]: + files = sorted(directory.glob("*.jsonl")) + assert files, "no audit file was written" + return [json.loads(line) for file in files for line in file.read_text().splitlines()] + + +class TestRecordRequest: + def test_writes_the_whole_request_and_its_hash(self, audit_dir): + request = {"model": "m", "system": "s", "messages": [{"role": "user", "content": "hi"}]} + + entry_id = audit.record_request("triage", request) + + (line,) = _lines(audit_dir) + assert line["id"] == entry_id + assert line["event"] == "request" + assert line["role"] == "triage" + assert line["request"] == request + assert len(line["payload_sha256"]) == 64 + assert line["at"] + + def test_the_same_request_has_the_same_hash_and_a_different_id(self, audit_dir): + request = {"model": "m", "messages": []} + + first = audit.record_request("triage", request) + second = audit.record_request("triage", dict(reversed(list(request.items())))) + + a, b = _lines(audit_dir) + assert first != second + assert a["payload_sha256"] == b["payload_sha256"] + + def test_creates_the_directory(self, audit_dir): + assert not audit_dir.exists() + audit.record_request("triage", {}) + assert audit_dir.is_dir() + + +class TestRecordResponseAndError: + def test_response_and_error_share_the_request_id(self, audit_dir): + entry_id = audit.record_request("synthesis", {"model": "m"}) + audit.record_response( + entry_id, model="m", stop_reason="end_turn", usage={"input_tokens": 3} + ) + audit.record_error(entry_id, RuntimeError("boom")) + + request, response, error = _lines(audit_dir) + assert request["id"] == response["id"] == error["id"] == entry_id + assert response["event"] == "response" + assert response["usage"] == {"input_tokens": 3} + assert response["stop_reason"] == "end_turn" + assert error["event"] == "error" + assert error["error"] == "RuntimeError: boom" diff --git a/tests/llm/test_claude_client.py b/tests/llm/test_claude_client.py new file mode 100644 index 0000000..a21f826 --- /dev/null +++ b/tests/llm/test_claude_client.py @@ -0,0 +1,279 @@ +""" +The client: keychain key, role-chosen model, and an audited send path. + +No test here makes a network call. The SDK's ``messages.create`` is replaced +with a stub that returns a response-shaped object, so what is under test is +what the client does around the call: what it sends, what it records, what it +returns, and what it refuses. Synchronous since backlog task 029 (2026-09-22). +""" + +import json +from types import SimpleNamespace + +import anthropic +import httpx2 +import pytest + +from src.config import credentials +from src.config.settings import settings +from src.llm.claude_client import ROLES, ClaudeClient, ModelCallFailed, ModelResponse + +# Not a credential: the SDK is stubbed and nothing here reaches a network. +FAKE_KEY = "sk-test" # pragma: allowlist secret +_REQUEST = httpx2.Request("POST", "https://api.example/v1/messages") + + +@pytest.fixture +def audit_dir(tmp_path, monkeypatch): + target = tmp_path / "llm-audit" + monkeypatch.setattr(settings, "llm_audit_dir", target) + return target + + +def _audit_events(audit_dir) -> list[dict]: + return [ + json.loads(line) + for file in sorted(audit_dir.glob("*.jsonl")) + for line in file.read_text().splitlines() + ] + + +def _response(*, text="answer", stop_reason="end_turn", model="served-model", thinking=True): + blocks = [] + if thinking: + blocks.append(SimpleNamespace(type="thinking", thinking="...")) + blocks.append(SimpleNamespace(type="text", text=text)) + return SimpleNamespace( + content=blocks, + stop_reason=stop_reason, + stop_details=None, + model=model, + usage=SimpleNamespace( + input_tokens=11, + output_tokens=7, + cache_read_input_tokens=0, + cache_creation_input_tokens=None, + ), + ) + + +@pytest.fixture +def client(audit_dir): + return ClaudeClient("triage", api_key=FAKE_KEY, model="test-model") + + +def _stub_create(client, response=None, error=None): + """Replace the SDK call; record what it was called with.""" + calls = [] + + def create(**kwargs): + calls.append(kwargs) + if error is not None: + raise error + return response + + client.client.messages.create = create + return calls + + +class TestConstruction: + def test_the_key_comes_from_the_keychain(self, memory_keyring, audit_dir): + credentials.write(credentials.ANTHROPIC, FAKE_KEY) + + assert ClaudeClient("triage").api_key == FAKE_KEY + + def test_no_key_in_the_keychain_fails_at_construction(self, memory_keyring, audit_dir): + with pytest.raises(credentials.MissingCredential): + ClaudeClient("triage") + + @pytest.mark.parametrize("role", sorted(ROLES)) + def test_the_model_is_chosen_by_role_from_settings(self, role, audit_dir, monkeypatch): + monkeypatch.setattr(settings, ROLES[role], f"model-for-{role}") + + assert ClaudeClient(role, api_key=FAKE_KEY).model == f"model-for-{role}" + + def test_an_unknown_role_is_refused(self, audit_dir): + with pytest.raises(ValueError, match="role"): + ClaudeClient("summarise", api_key=FAKE_KEY) + + +class TestSend: + def test_returns_text_and_usage(self, client): + _stub_create(client, _response()) + + result = client.analyze("sys", "hello") + + assert isinstance(result, ModelResponse) + assert result.text == "answer" + assert result.model == "served-model" + assert result.stop_reason == "end_turn" + assert (result.input_tokens, result.output_tokens) == (11, 7) + assert result.cache_creation_input_tokens == 0 # None from the API reads as zero + + def test_effort_goes_in_output_config_not_extra_body(self, client): + calls = _stub_create(client, _response()) + + client.analyze("sys", "hello", effort="low", max_tokens=99) + + (sent,) = calls + assert sent["output_config"] == {"effort": "low"} + assert "extra_body" not in sent + assert sent["max_tokens"] == 99 + assert sent["model"] == "test-model" + assert sent["messages"] == [{"role": "user", "content": "hello"}] + + def test_a_schema_goes_in_output_config_format_as_a_request_parameter(self, client): + """Structured output is a request parameter, not a parsing convention.""" + calls = _stub_create(client, _response(text='{"ok": true}')) + schema = {"type": "object", "properties": {"ok": {"type": "boolean"}}} + + client.analyze("sys", "hello", output_schema=schema) + + (sent,) = calls + assert sent["output_config"] == { + "effort": "high", + "format": {"type": "json_schema", "schema": schema}, + } + + def test_an_invalid_effort_is_refused_before_anything_is_sent(self, client, audit_dir): + calls = _stub_create(client, _response()) + + with pytest.raises(ValueError, match="effort"): + client.analyze("sys", "hello", effort="maximum") + + assert calls == [] + assert not audit_dir.exists() + + def test_text_is_selected_by_block_type_not_position(self, client): + """2026-08-26: content[0] is a ThinkingBlock on thinking models.""" + _stub_create(client, _response(thinking=True)) + + assert client.analyze("sys", "hello").text == "answer" + + def test_a_refusal_is_raised_not_returned_as_empty(self, client): + _stub_create(client, _response(stop_reason="refusal")) + + with pytest.raises(ModelCallFailed, match="declined") as excinfo: + client.analyze("sys", "hello") + + # The failure carries what the audit log recorded: the id and the cost. + assert excinfo.value.audit_id + assert (excinfo.value.input_tokens, excinfo.value.output_tokens) == (11, 7) + assert excinfo.value.stop_reason == "refusal" + assert excinfo.value.outcome == "answered" + + def test_an_api_error_is_a_typed_failure_carrying_its_audit_id(self, client): + _stub_create(client, error=anthropic.APITimeoutError(request=_REQUEST)) + + with pytest.raises(ModelCallFailed, match="APITimeoutError") as excinfo: + client.analyze("sys", "hello") + + assert excinfo.value.audit_id + assert (excinfo.value.input_tokens, excinfo.value.output_tokens) == (0, 0) + assert excinfo.value.outcome == "unavailable" + + @pytest.mark.parametrize( + "status, outcome", + [ + (400, "rejected"), + (401, "rejected"), + (403, "rejected"), + (404, "rejected"), + (413, "answered"), + (429, "unavailable"), + (500, "unavailable"), + (529, "unavailable"), + ], + ) + def test_api_status_errors_are_classified_by_what_they_mean(self, client, status, outcome): + """400-404 is the operator's request; 413 is this pair; the rest is the API's day.""" + response = httpx2.Response(status, request=_REQUEST) + error = client.client._make_status_error("boom", body=None, response=response) # noqa: SLF001 + _stub_create(client, error=error) + + with pytest.raises(ModelCallFailed) as excinfo: + client.analyze("sys", "hello") + + assert excinfo.value.outcome == outcome + assert excinfo.value.misconfigured is (outcome == "rejected") + + def test_a_connection_error_is_unavailable_not_a_verdict(self, client): + _stub_create(client, error=anthropic.APIConnectionError(request=_REQUEST)) + + with pytest.raises(ModelCallFailed) as excinfo: + client.analyze("sys", "hello") + + assert excinfo.value.outcome == "unavailable" + + def test_an_exception_that_is_not_an_api_error_is_audited_and_re_raised( + self, client, audit_dir + ): + """A TypeError from a kwarg the SDK no longer accepts is a bug, not a verdict.""" + _stub_create(client, error=TypeError("create() got an unexpected keyword argument")) + + with pytest.raises(TypeError): + client.analyze("sys", "hello") + + request, error = _audit_events(audit_dir) + assert request["event"] == "request" + assert error["event"] == "error" + assert "TypeError" in error["error"] + + +class TestAudit: + def test_request_is_logged_before_the_send_and_response_after(self, client, audit_dir): + calls = _stub_create(client, _response()) + + result = client.analyze("sys", "hello", effort="medium") + + request, response = _audit_events(audit_dir) + assert request["event"] == "request" + assert request["id"] == result.audit_id + assert request["role"] == "triage" + assert request["request"] == calls[0] + assert response["event"] == "response" + assert response["id"] == result.audit_id + assert response["usage"]["input_tokens"] == 11 + assert response["stop_reason"] == "end_turn" + assert response["model"] == "served-model" + + def test_a_failed_send_leaves_the_request_and_an_error_line(self, client, audit_dir): + _stub_create( + client, error=anthropic.APIConnectionError(message="no route", request=_REQUEST) + ) + + with pytest.raises(ModelCallFailed): + client.analyze("sys", "hello") + + request, error = _audit_events(audit_dir) + assert request["event"] == "request" + assert error["event"] == "error" + assert error["id"] == request["id"] + assert "no route" in error["error"] + + def test_a_refusal_is_audited_as_a_response_before_it_is_raised(self, client, audit_dir): + _stub_create(client, _response(stop_reason="refusal")) + + with pytest.raises(ModelCallFailed): + client.analyze("sys", "hello") + + _request, response = _audit_events(audit_dir) + assert response["stop_reason"] == "refusal" + + +def test_only_the_client_constructs_a_model_request(): + """ + One module builds requests. Checked against the tree, not intentions, the + same way tests/sources/test_observation.py checks the observation write path. + """ + import re + from pathlib import Path + + root = Path(__file__).resolve().parents[2] / "src" + pattern = re.compile(r"\bAnthropic\(|messages\.create\(") + offenders = [ + str(p.relative_to(root)) + for p in sorted(root.rglob("*.py")) + if p != root / "llm" / "claude_client.py" and pattern.search(p.read_text(encoding="utf-8")) + ] + assert offenders == [], f"model requests are constructed outside the client: {offenders}" diff --git a/tests/matching/test_coverage_probe.py b/tests/matching/test_coverage_probe.py deleted file mode 100644 index 843c592..0000000 --- a/tests/matching/test_coverage_probe.py +++ /dev/null @@ -1,480 +0,0 @@ -""" -Tests for running coverage probes against the corpus. - -Every corpus here is synthetic and built by the test that reads it. None of it -touches the live database, and no test names an event that has to still be in -retention: this is a test of the matcher and the verdict logic, not of what the -operator's corpus happens to hold today. Pinning live events into CI would make -the suite fail for reasons that have nothing to do with the code under test. - -The collision surface is the point of interest, and it is measured rather than -asserted from intuition. On this repository's corpus on 2026-08-27, of 54,044 -stored articles 657 titles contain the substring ``nist`` and exactly 4 are -about NIST. :class:`TestSubstringMatchingWouldLie` reproduces that ratio in -miniature and shows both matchers side by side. -""" - -from datetime import date, datetime - -import pytest -from sqlalchemy.orm import sessionmaker - -from src.database.models import Article, RSSFeed -from src.matching.coverage_probe import ( - STATUS_INCONCLUSIVE, - STATUS_MATCHED, - STATUS_UNMATCHED, - compile_probe, - run_coverage_probes, -) -from src.matching.terms import CoverageProbe - -# Titles that contain "nist" as a substring and are about nothing of the kind. -# Drawn from the words the real collision was made of: administration, minister, -# Afghanistan, communist, sinister, columnist, agonist. -NIST_COLLISIONS = [ - "The administration reshuffles its priorities", - "Prime minister addresses the assembly", - "Afghanistan aid package clears committee", - "A communist party congress opens", - "A sinister turn in the negotiations", - "Our columnist on the week in politics", - "Beta agonist trial results published", - "Administrative law judges face a backlog", - "Ministry of Defence confirms the order", -] -NIST_REAL = [ - "NIST is rethinking its role in analyzing software vulnerabilities", - "NIST and MITRE partner to test AI defense technology", -] - - -def probe(**overrides): - fields = { - "date": date(2026, 8, 24), - "what": "an event", - "terms": ("NIST",), - "any_of": (("vulnerabilit*", "partner*"),), - "window_days": 14, - } - fields.update(overrides) - return CoverageProbe(**fields) - - -def text_of(title): - return title - - -class TestTermMatching: - """Pure matching, no database.""" - - def test_a_required_term_must_be_present(self): - compiled = compile_probe(probe(terms=("FedRAMP", "PMO"), any_of=())) - assert compiled.matches("The FedRAMP PMO published guidance") - assert not compiled.matches("The FedRAMP program published guidance") - - def test_each_any_of_group_needs_one_member(self): - compiled = compile_probe( - probe(terms=("FedRAMP",), any_of=(("director", "administrator"), ("reinstat*",))) - ) - assert compiled.matches("FedRAMP director reinstated after review") - assert compiled.matches("FedRAMP administrator reinstatement confirmed") - assert not compiled.matches("FedRAMP director named after review") - - def test_missing_reports_which_requirement_went_unmet(self): - compiled = compile_probe(probe(terms=("FedRAMP",), any_of=(("director", "administrator"),))) - absent, unsatisfied = compiled.missing("CISA director named") - assert absent == ("FedRAMP",) - assert unsatisfied == () - - absent, unsatisfied = compiled.missing("FedRAMP authorizations paused") - assert absent == () - assert unsatisfied == (("director", "administrator"),) - - -class TestSubstringMatchingWouldLie: - """ - The word-boundary requirement, shown biting. - - Both matchers are run over the same nine collisions and two real articles. - The substring matcher reports 11 of 11; the probe matcher reports 2 of 11. - """ - - def test_substring_matching_reports_every_collision(self): - naive = [t for t in NIST_COLLISIONS + NIST_REAL if "nist" in t.lower()] - assert len(naive) == 11 - - def test_probe_matching_reports_only_the_real_ones(self): - compiled = compile_probe(probe(terms=("NIST",), any_of=(("rethinking", "partner*"),))) - matched = [t for t in NIST_COLLISIONS + NIST_REAL if compiled.matches(text_of(t))] - assert matched == NIST_REAL - - @pytest.mark.parametrize("title", NIST_COLLISIONS) - def test_no_collision_matches_even_the_bare_term(self, title): - """For these lowercase collisions it is the case rule, not the boundary, that rejects them: every term here is shouted, so the compiled pattern is case-sensitive and never reaches the anchors. Verified 2026-08-27 by deleting LEFT_BOUNDARY/RIGHT_BOUNDARY from entity_matcher and re-running this class -- all 12 still passed. See TestBoundariesAreLoadBearingForShoutedTermsToo, which holds case constant so only the anchor can refuse the match.""" - compiled = compile_probe(probe(terms=("NIST", "the"), any_of=())) - assert not compiled.matches(title) - - def test_an_acronym_only_matches_when_it_is_shouted(self): - """Inherited from entity matching: BOD is a directive, bod is not.""" - compiled = compile_probe(probe(terms=("BOD", "issued"), any_of=())) - assert compiled.matches("CISA issued BOD 22-01") - assert not compiled.matches("A bod issued a statement") - - -# All-caps collisions, for holding case constant while the boundary is tested. -# Each headline embeds a shouted probe term inside a longer shouted word, so -# case-sensitivity cannot be the thing that rejects it. The words are the ones -# the hazard is actually made of: DOPMA is the Defense Officer Personnel -# Management Act, PRECISA is ordinary Portuguese, and an all-caps headline is a -# normal thing for a wire feed to emit. -SHOUTED_COLLISIONS = [ - # (probe term, second required term that IS present, headline) - ("OPM", "REPORT", "COMPTROLLER REPORT ON DOPMA REFORM ADVANCES"), - ("OPM", "REPORT", "AGENCY REPORT NAMES TOPMOST PRIORITIES"), - ("BOD", "CISA", "BODY CAMERA RULE ADVANCES AT CISA"), - ("BOD", "CISA", "CISA ISSUES BODY CAMERA GUIDANCE"), - ("OMB", "FBI", "FBI CONFIRMS BOMBING SUSPECT IN CUSTODY"), - ("CISA", "RELATORIO", "GOVERNO PRECISA DE NOVO RELATORIO SOBRE SEGURANCA"), -] - - -class TestBoundariesAreLoadBearingForShoutedTermsToo: - """ - The boundary isolated from the case rule. - - Every collision in :data:`NIST_COLLISIONS` is lowercase, so a shouted term - like ``NIST`` is already rejected by case-sensitivity before the boundary - anchors are consulted -- those cases would stay green if the anchors were - deleted outright. That is not a hypothetical gap: the shipped beat's probes - are shouted (``OPM``, ``CISA``), so it is exactly the term type in - production whose anchoring would go unguarded. - - Here the headline and the term are both ALL CAPS. Case is held constant, so - the boundary anchor is the only thing left that can reject the match. Each - case was checked against the production regex with the anchors stripped and - case matching unchanged: all six then match, which is what makes these - assertions load-bearing rather than incidental. - """ - - @pytest.mark.parametrize(("term", "other", "title"), SHOUTED_COLLISIONS) - def test_a_shouted_term_inside_a_shouted_word_is_not_a_match(self, term, other, title): - compiled = compile_probe(probe(terms=(term, other), any_of=())) - assert not compiled.matches(title) - - @pytest.mark.parametrize(("term", "other", "title"), SHOUTED_COLLISIONS) - def test_the_second_required_term_is_present_so_only_the_collision_fails( - self, term, other, title - ): - """ - Pins *why* the case above fails. Without this, a headline that simply - lacked both terms would satisfy the assertion and prove nothing about - the boundary. - """ - compiled = compile_probe(probe(terms=(term, other), any_of=())) - absent, _ = compiled.missing(title) - assert absent == (term,) - - @pytest.mark.parametrize( - ("term", "other", "title"), - [ - ("OPM", "REPORT", "OPM REPORT ON DOPMA REFORM ADVANCES"), - ("BOD", "CISA", "CISA ISSUES BOD 22-01"), - ("OMB", "FBI", "FBI CITES OMB MEMO M-26-01"), - ("CISA", "RELATORIO", "CISA PUBLICA NOVO RELATORIO SOBRE SEGURANCA"), - ], - ) - def test_the_same_probe_still_matches_the_term_standing_alone(self, term, other, title): - """ - The other half of the claim: the anchors reject the collision without - rejecting the event. A matcher that failed both would pass the tests - above and be useless. - """ - compiled = compile_probe(probe(terms=(term, other), any_of=())) - assert compiled.matches(title) - - def test_the_right_hand_anchor_is_exercised_at_position_zero(self): - """ - ``BODY CAMERA...`` puts the collision at offset 0, where there is no - preceding character for the left-hand lookbehind to reject. Only the - right-hand anchor can refuse it. - """ - compiled = compile_probe(probe(terms=("BOD",), any_of=())) - assert not compiled.matches("BODY CAMERA RULE ADVANCES") - assert compiled.matches("BOD 22-01 ADVANCES") - - -class TestStems: - def test_a_stem_must_be_marked(self): - assert not compile_probe(probe(terms=("reinstat", "x"), any_of=())).matches( - "x reinstated today" - ) - assert compile_probe(probe(terms=("reinstat*", "x"), any_of=())).matches( - "x reinstated today" - ) - - def test_a_stem_still_has_to_start_a_word(self): - """The left boundary is what does the collision filtering; a stem keeps it.""" - compiled = compile_probe(probe(terms=("ramp*", "the"), any_of=())) - assert not compiled.matches("the FedRAMP authorization") - assert compiled.matches("the ramp-up of authorizations") - - -# --------------------------------------------------------------------------- -# Corpus-backed verdicts -# --------------------------------------------------------------------------- - -FEED_URL = "https://example.test/beat-feed" -FEED_NAME = "In-Beat Wire" -OTHER_URL = "https://example.test/other-feed" -OTHER_NAME = "Out-of-Beat Wire" - - -@pytest.fixture -def session(test_engine): - maker = sessionmaker(bind=test_engine) - db = maker() - yield db - db.close() - - -@pytest.fixture -def corpus(session): - """Two sources, empty. Tests add the articles they need.""" - in_beat = RSSFeed(url=FEED_URL, name=FEED_NAME, category="test") - outside = RSSFeed(url=OTHER_URL, name=OTHER_NAME, category="test") - session.add_all([in_beat, outside]) - session.commit() - return in_beat, outside - - -def add_article(session, feed, title, when, body=""): - session.add( - Article( - feed_id=feed.id, - guid=f"{feed.id}-{title}", - title=title, - description="", - normalized_content=body, - published_date=when, - ) - ) - session.commit() - - -def run(session, probes, feed_urls=(FEED_URL,)): - """ - Run a probe set against an explicit feed selection. - - Before task 012 this built a ``BeatConfig`` and let ``run_coverage_probes`` - resolve its feeds. Beats are gone and the scope is now passed directly, so - the helper is the call itself. - """ - return run_coverage_probes(session, tuple(probes), list(feed_urls), subject="test-subject") - - -class TestVerdicts: - def test_a_match_names_the_feed_that_carried_it(self, session, corpus): - in_beat, _ = corpus - add_article( - session, in_beat, "NIST publishes vulnerability guidance", datetime(2026, 8, 25) - ) - report = run(session, [probe(terms=("NIST",), any_of=(("vulnerabilit*",),))]) - - (result,) = report.results - assert result.status == STATUS_MATCHED - assert result.match_count == 1 - assert result.matches[0].feed_name == FEED_NAME - assert result.matches[0].title == "NIST publishes vulnerability guidance" - - def test_articles_in_the_window_that_do_not_match_are_a_failure(self, session, corpus): - in_beat, _ = corpus - add_article(session, in_beat, "An unrelated procurement notice", datetime(2026, 8, 25)) - (result,) = run(session, [probe()]).results - assert result.status == STATUS_UNMATCHED - assert result.articles_in_window == 1 - assert result.missing_terms == ("NIST",) - - def test_a_match_outside_the_window_does_not_count(self, session, corpus): - in_beat, _ = corpus - add_article(session, in_beat, "NIST publishes vulnerability guidance", datetime(2026, 6, 1)) - add_article(session, in_beat, "Something else entirely", datetime(2026, 8, 25)) - (result,) = run(session, [probe()]).results - assert result.status == STATUS_UNMATCHED - - def test_a_match_on_another_beats_feed_does_not_count_but_is_reported(self, session, corpus): - in_beat, outside = corpus - add_article(session, in_beat, "An unrelated procurement notice", datetime(2026, 8, 25)) - add_article( - session, outside, "NIST publishes vulnerability guidance", datetime(2026, 8, 25) - ) - (result,) = run(session, [probe()]).results - - assert result.status == STATUS_UNMATCHED - assert result.elsewhere_count == 1 - assert result.elsewhere[0].feed_name == OTHER_NAME - assert result.elsewhere[0].in_selected_sources is False - - def test_no_one_carried_it_is_distinguishable_from_someone_else_did(self, session, corpus): - in_beat, _ = corpus - add_article(session, in_beat, "An unrelated procurement notice", datetime(2026, 8, 25)) - (result,) = run(session, [probe()]).results - assert result.status == STATUS_UNMATCHED - assert result.elsewhere == () - - def test_the_body_is_searched_not_only_the_title(self, session, corpus): - in_beat, _ = corpus - add_article( - session, - in_beat, - "This week in federal cyber", - datetime(2026, 8, 25), - body="Elsewhere, NIST said it was rethinking its vulnerability analysis role.", - ) - (result,) = run(session, [probe(any_of=(("vulnerabilit*",),))]).results - assert result.status == STATUS_MATCHED - - def test_an_undated_article_can_never_satisfy_a_probe(self, session, corpus): - """ - An article with no published_date cannot be placed in any window, so it - must not be able to turn an inconclusive probe into a pass or a failure. - """ - in_beat, _ = corpus - add_article(session, in_beat, "NIST vulnerability guidance", None) - (result,) = run(session, [probe()]).results - assert result.status == STATUS_INCONCLUSIVE - - -class TestInconclusive: - def test_a_probe_predating_the_corpus_is_inconclusive(self, session, corpus): - in_beat, _ = corpus - add_article(session, in_beat, "Recent news", datetime(2026, 8, 25)) - (result,) = run(session, [probe(date=date(2021, 11, 3))]).results - assert result.status == STATUS_INCONCLUSIVE - assert "predates the corpus" in result.reason - - def test_a_probe_the_corpus_has_not_reached_is_inconclusive(self, session, corpus): - in_beat, _ = corpus - add_article(session, in_beat, "Old news", datetime(2026, 1, 5)) - (result,) = run(session, [probe(date=date(2026, 8, 24))]).results - assert result.status == STATUS_INCONCLUSIVE - assert "has not reached the event yet" in result.reason - - def test_a_gap_in_the_middle_is_inconclusive_and_says_so(self, session, corpus): - in_beat, _ = corpus - add_article(session, in_beat, "Before", datetime(2026, 1, 5)) - add_article(session, in_beat, "After", datetime(2026, 12, 5)) - (result,) = run(session, [probe(date=date(2026, 8, 24))]).results - assert result.status == STATUS_INCONCLUSIVE - assert "gap in the corpus" in result.reason - - def test_a_beat_whose_feeds_have_no_rows_is_inconclusive_not_failed(self, session, corpus): - _, outside = corpus - add_article(session, outside, "NIST vulnerability guidance", datetime(2026, 8, 25)) - (result,) = run(session, [probe()]).results - assert result.status == STATUS_INCONCLUSIVE - assert not result.conclusive - - -class TestInconclusiveDoesNotShrinkTheProbeSet: - """ - The landmine: a probe set that quietly decays to the events still in - retention is a green light that means nothing. The counts must always sum - back to the number of probes the beat declared. - """ - - @pytest.fixture - def mixed(self, session, corpus): - in_beat, _ = corpus - add_article( - session, in_beat, "NIST publishes vulnerability guidance", datetime(2026, 8, 25) - ) - add_article(session, in_beat, "An unrelated notice", datetime(2026, 8, 26)) - return run( - session, - [ - probe(what="matches"), - probe(what="misses", terms=("FedRAMP",), any_of=(("director",),)), - probe(what="too old", date=date(2021, 11, 3)), - probe(what="also too old", date=date(2020, 1, 1)), - ], - ) - - def test_every_declared_probe_appears_in_the_results(self, mixed): - assert mixed.total == 4 - assert [r.probe.what for r in mixed.results] == [ - "matches", - "misses", - "too old", - "also too old", - ] - - def test_the_three_counts_sum_to_the_number_declared(self, mixed): - assert len(mixed.matched) + len(mixed.unmatched) + len(mixed.inconclusive) == mixed.total - assert (len(mixed.matched), len(mixed.unmatched), len(mixed.inconclusive)) == (1, 1, 2) - - def test_conclusive_is_a_smaller_set_and_says_so(self, mixed): - assert len(mixed.conclusive) == 2 - assert len(mixed.conclusive) < mixed.total - - -class TestItNeverWrites: - """ - The corpus is shared. A question about it must not alter it. - """ - - def test_running_probes_leaves_the_row_counts_alone(self, session, corpus): - in_beat, _ = corpus - add_article(session, in_beat, "NIST vulnerability guidance", datetime(2026, 8, 25)) - before = (session.query(Article).count(), session.query(RSSFeed).count()) - - run(session, [probe(), probe(date=date(2021, 1, 1))]) - - session.expire_all() - assert (session.query(Article).count(), session.query(RSSFeed).count()) == before - - def test_the_session_is_never_flushed_dirty(self, session, corpus): - """Nothing is added to the session, so a rollback loses nothing.""" - in_beat, _ = corpus - add_article(session, in_beat, "NIST vulnerability guidance", datetime(2026, 8, 25)) - run(session, [probe()]) - assert not session.new - assert not session.deleted - assert not session.dirty - - -class TestFeedScope: - def test_the_caller_names_the_scope_and_the_report_echoes_it(self, session, corpus): - """ - The feed selection is an argument, not something the matcher resolves. - - Until task 012 this took a ``BeatConfig`` and called ``resolve_feeds()`` - when ``feed_urls`` was omitted, which put beat-file loading inside the - matcher. The scope is now always the caller's, and ``feed_names`` reports - back the feeds that selection actually resolved to in the corpus. - """ - in_beat, _ = corpus - add_article( - session, in_beat, "NIST publishes vulnerability guidance", datetime(2026, 8, 25) - ) - - report = run(session, [probe(any_of=(("vulnerabilit*",),))]) - - assert report.feed_names == (FEED_NAME,) - assert report.results[0].status == STATUS_MATCHED - - def test_an_empty_scope_answers_nothing_rather_than_passing(self, session, corpus): - """No feeds searched is INCONCLUSIVE, never a clean sweep.""" - in_beat, _ = corpus - add_article( - session, in_beat, "NIST publishes vulnerability guidance", datetime(2026, 8, 25) - ) - - report = run(session, [probe()], feed_urls=()) - - assert report.feed_names == () - assert report.results[0].status == STATUS_INCONCLUSIVE - - def test_the_subject_label_is_carried_through_untouched(self, session, corpus): - report = run(session, [probe()]) - assert report.subject == "test-subject" diff --git a/tests/position/test_ledger.py b/tests/position/test_ledger.py new file mode 100644 index 0000000..4403f51 --- /dev/null +++ b/tests/position/test_ledger.py @@ -0,0 +1,249 @@ +""" +The belief ledger: append-only, operator-written, and the one definition of live. +""" + +from datetime import date, datetime + +import pytest +from sqlalchemy import text +from sqlalchemy.exc import IntegrityError + +from src.database.models import LedgerIsAppendOnly, Watch, WatchBelief +from src.position.ledger import ( + LedgerError, + current_beliefs, + live_clause, + open_clause, + record_belief, + resolve_watch, +) + +TODAY = date(2026, 9, 1) + + +def _watch(session, watch_id="w", belief=0.35, expires=date(2027, 3, 31)) -> Watch: + row = Watch( + id=watch_id, + claim="A claim.", + belief=belief, + decision_key="d", + so_what="because", + triggers=[{"terms": ["x"]}], + expires=expires, + staleness_alert_days=30, + ) + session.add(row) + session.flush() + return row + + +class TestRecordBelief: + def test_a_principal_row_is_appended_with_its_note_and_time(self, test_session): + _watch(test_session) + when = datetime(2026, 9, 1, 9, 0) + + row = record_belief( + test_session, "w", 0.6, source="principal", note=" the memo landed ", observed_at=when + ) + + assert (row.belief, row.source, row.note, row.observed_at) == ( + 0.6, + "principal", + "the memo landed", + when, + ) + + @pytest.mark.parametrize("belief", [-0.1, 1.5, "0.5", True]) + def test_a_belief_outside_the_unit_interval_or_not_a_number_is_refused( + self, test_session, belief + ): + _watch(test_session) + with pytest.raises(LedgerError): + record_belief(test_session, "w", belief, source="principal", note="why") + + @pytest.mark.parametrize("note", [None, "", " "]) + def test_an_operator_belief_without_a_note_is_refused(self, test_session, note): + _watch(test_session) + with pytest.raises(LedgerError, match="note"): + record_belief(test_session, "w", 0.5, source="principal", note=note) + + def test_an_unknown_source_is_refused(self, test_session): + _watch(test_session) + with pytest.raises(LedgerError, match="source"): + record_belief(test_session, "w", 0.5, source="model", note="n") + + def test_an_unknown_watch_is_refused(self, test_session): + with pytest.raises(LedgerError, match="no watch"): + record_belief(test_session, "nope", 0.5, source="principal", note="n") + + def test_a_retired_or_resolved_watch_takes_no_new_belief(self, test_session): + retired = _watch(test_session, "r") + retired.retired_at = datetime(2026, 8, 1) + resolved = _watch(test_session, "s") + resolve_watch(test_session, "s", outcome="yes", note="it happened") + + with pytest.raises(LedgerError, match="retired"): + record_belief(test_session, "r", 0.5, source="principal", note="n") + with pytest.raises(LedgerError, match="resolved"): + record_belief(test_session, "s", 0.5, source="principal", note="n") + assert resolved.outcome == "yes" + + def test_an_orphaned_ledger_row_is_named_not_a_key_error(self, test_session): + """SQLite is not enforcing the foreign key; a hand delete must fail by name.""" + _watch(test_session) + record_belief(test_session, "w", 0.5, source="principal", note="n") + test_session.execute(text("DELETE FROM watches WHERE id = 'w'")) + + with pytest.raises(LedgerError, match="belongs to watch 'w', which does not exist"): + current_beliefs(test_session) + + +class TestAppendOnly: + def test_the_orm_refuses_an_update(self, test_session): + _watch(test_session) + row = record_belief(test_session, "w", 0.5, source="principal", note="n") + + row.belief = 0.9 + with pytest.raises(LedgerIsAppendOnly): + test_session.flush() + test_session.rollback() + + def test_the_orm_refuses_a_delete(self, test_session): + _watch(test_session) + row = record_belief(test_session, "w", 0.5, source="principal", note="n") + + test_session.delete(row) + with pytest.raises(LedgerIsAppendOnly): + test_session.flush() + test_session.rollback() + + @pytest.mark.parametrize( + "statement", + [ + "UPDATE watch_beliefs SET belief = 0.9", + "DELETE FROM watch_beliefs", + ], + ) + def test_the_database_refuses_raw_sql_too(self, test_session, statement): + """The trigger, not the ORM, is what stops a sqlite3 shell.""" + _watch(test_session) + record_belief(test_session, "w", 0.5, source="principal", note="n") + test_session.commit() + + with pytest.raises(IntegrityError, match="append-only"): + test_session.execute(text(statement)) + test_session.rollback() + assert test_session.query(WatchBelief).count() == 1 + + +class TestCurrentBeliefs: + def test_the_latest_row_wins_and_the_registration_value_is_kept(self, test_session): + _watch(test_session, belief=0.35) + record_belief( + test_session, "w", 0.5, source="file", note=None, observed_at=datetime(2026, 8, 1) + ) + record_belief( + test_session, "w", 0.7, source="principal", note="n", observed_at=datetime(2026, 8, 2) + ) + + current = current_beliefs(test_session)["w"] + + assert (current.belief, current.source, current.registered) == (0.7, "principal", 0.35) + assert current.observed_at == datetime(2026, 8, 2) + + def test_two_rows_at_the_same_instant_resolve_by_id_and_a_back_dated_row_is_not_current( + self, test_session + ): + _watch(test_session) + same = datetime(2026, 9, 1, 9, 0) + record_belief(test_session, "w", 0.6, source="principal", note="a", observed_at=same) + record_belief(test_session, "w", 0.2, source="file", note=None, observed_at=same) + assert current_beliefs(test_session)["w"].belief == 0.2 + + record_belief( + test_session, "w", 0.9, source="principal", note="b", observed_at=datetime(2026, 8, 1) + ) + assert current_beliefs(test_session)["w"].belief == 0.2 + + def test_a_watch_with_no_ledger_row_reads_as_its_registration_belief(self, test_session): + _watch(test_session, belief=0.35) + + current = current_beliefs(test_session)["w"] + + assert (current.belief, current.source, current.registered) == (0.35, "file", 0.35) + + +class TestResolve: + def test_resolution_is_recorded_once(self, test_session): + _watch(test_session) + + row = resolve_watch(test_session, "w", outcome="no", note="deviation published") + + assert (row.outcome, row.resolution_note) == ("no", "deviation published") + assert row.resolved_at is not None + with pytest.raises(LedgerError, match="resolved"): + resolve_watch(test_session, "w", outcome="yes", note="changed my mind") + + def test_a_retired_watch_can_still_be_graded(self, test_session): + """A claim often settles after it has left the file; grading it is allowed.""" + _watch(test_session).retired_at = datetime(2026, 8, 1) + + row = resolve_watch(test_session, "w", outcome="yes", note="settled after retirement") + + assert row.outcome == "yes" + + @pytest.mark.parametrize("outcome, note", [("maybe", "n"), ("yes", ""), ("yes", " ")]) + def test_a_bad_outcome_or_blank_note_is_refused(self, test_session, outcome, note): + _watch(test_session) + with pytest.raises(LedgerError): + resolve_watch(test_session, "w", outcome=outcome, note=note) + + +class TestLiveness: + def test_live_means_open_and_not_expired(self, test_session): + _watch(test_session, "live") + _watch(test_session, "expired", expires=date(2026, 1, 1)) + _watch(test_session, "retired").retired_at = datetime(2026, 8, 1) + _watch(test_session, "resolved") + resolve_watch(test_session, "resolved", outcome="yes", note="n") + test_session.flush() + + live = {i for (i,) in test_session.query(Watch.id).filter(live_clause(TODAY))} + open_ = {i for (i,) in test_session.query(Watch.id).filter(open_clause())} + + assert live == {"live"} + assert open_ == {"live", "expired"} + + +def test_only_sync_and_the_two_commands_write_belief_or_resolution(): + """ + The writers, by construction and by name: the ledger functions themselves, + ``sync_watches`` (file beliefs), and the ``believe`` and ``resolve`` + commands. Any other module that constructs a ledger row, calls the ledger + functions, assigns the resolution columns, or bulk-updates them fails here. + A ``class WatchBelief(`` statement is a definition, not a construction, and + is excluded by the lookbehind rather than by exempting its whole file. + """ + import re + from pathlib import Path + + root = Path(__file__).resolve().parents[2] / "src" + patterns = [ + re.compile(r"(? - - -
Site Header
- -
-
-

Article Title

-

This is the main article content.

-

It has multiple paragraphs.

-
-
- -
Site Footer
- - - - """ - - -@pytest.fixture -def clean_text_content(): - """Expected clean text after HTML normalization""" - return "Article Title This is the main article content. It has multiple paragraphs." - - -_UNSET = object() # Sentinel for unset values - - -@pytest.fixture -def sample_article_factory(): - """Factory for creating mock Article objects for testing""" - - def create_article( - id=1, - title="Test Article", - url="https://example.com/article", - description="Test description", - content="

Test content

", - normalized_content="Test content", - published_date=_UNSET, - fetched_at=_UNSET, - feed_id=1, - guid="test-guid-1", - priority_score=0.5, - priority_metadata=None, - filtered=False, - filter_reason=None, - ): - article = MagicMock() - article.id = id - article.title = title - article.url = url - article.description = description - article.content = content - article.normalized_content = normalized_content - # Use default datetime only if not explicitly passed - article.published_date = datetime.utcnow() if published_date is _UNSET else published_date - article.fetched_at = datetime.utcnow() if fetched_at is _UNSET else fetched_at - article.feed_id = feed_id - article.guid = guid - article.priority_score = priority_score - article.priority_metadata = priority_metadata - article.word_count = len(normalized_content.split()) if normalized_content else 0 - article.language = "en" - article.filtered = filtered - article.filter_reason = filter_reason - return article - - return create_article - - -@pytest.fixture -def duplicate_article_pair(sample_article_factory): - """Create a pair of duplicate articles with same content""" - now = datetime.utcnow() - original = sample_article_factory( - id=1, - title="Breaking News: Major Event", - url="https://source1.com/news", - normalized_content="This is the breaking news content about a major event.", - fetched_at=now - timedelta(hours=1), - ) - duplicate = sample_article_factory( - id=2, - title="Breaking News: Major Event", - url="https://source2.com/news", - normalized_content="This is the breaking news content about a major event.", - fetched_at=now, - ) - return original, duplicate - - -@pytest.fixture -def near_duplicate_pair(sample_article_factory): - """Create a pair of near-duplicate articles with same URL""" - now = datetime.utcnow() - original = sample_article_factory( - id=1, - title="Original Article Title", - url="https://example.com/same-url", - normalized_content="Original content here.", - fetched_at=now - timedelta(hours=1), - ) - duplicate = sample_article_factory( - id=2, - title="Original Article Title", - url="https://example.com/same-url", - normalized_content="Slightly modified content.", - fetched_at=now, - ) - return original, duplicate - - -@pytest.fixture -def sports_article(sample_article_factory): - """Article with sports content""" - return sample_article_factory( - id=10, - title="NFL Playoff Preview: Quarterback Battle Expected", - description="The upcoming NFL playoff game features star quarterbacks", - normalized_content="Football fans eagerly await the NFL playoffs.", - ) - - -@pytest.fixture -def clickbait_article(sample_article_factory): - """Article with clickbait title""" - return sample_article_factory( - id=11, - title="You Won't Believe What Happens Next!!!", - description="Shocking revelation", - normalized_content="Normal content here.", - ) - - -@pytest.fixture -def entertainment_article(sample_article_factory): - """Article with entertainment content""" - return sample_article_factory( - id=12, - title="Celebrity Red Carpet Fashion at the Oscars", - description="Hollywood stars dazzle at awards ceremony", - normalized_content="Movie star fashion trends.", - ) - - -@pytest.fixture -def normal_article(sample_article_factory): - """Normal news article that should not be filtered""" - return sample_article_factory( - id=13, - title="City Council Approves New Infrastructure Plan", - description="Local government invests in transportation", - normalized_content="The city council voted to approve the new infrastructure plan.", - ) - - -@pytest.fixture -def mock_user_profile(): - """Mock user profile for content filtering""" - profile = MagicMock() - profile.get_excluded_topics.return_value = ["crypto", "nft"] - return profile diff --git a/tests/processors/test_content_filter.py b/tests/processors/test_content_filter.py deleted file mode 100644 index c36ec84..0000000 --- a/tests/processors/test_content_filter.py +++ /dev/null @@ -1,247 +0,0 @@ -""" -Tests for Content Filter -""" - -import pytest - -from src.processors.content_filter import ContentFilter - - -class TestContentFilterInit: - """Tests for ContentFilter initialization""" - - def test_init_without_profile(self): - """Should initialize without user profile""" - filter = ContentFilter() - - assert filter.user_profile is None - assert filter.excluded_topics == [] - - def test_init_with_profile(self, mock_user_profile): - """Should extract excluded topics from profile""" - filter = ContentFilter(user_profile=mock_user_profile) - - assert filter.user_profile == mock_user_profile - assert "crypto" in filter.excluded_topics - assert "nft" in filter.excluded_topics - - -class TestShouldFilter: - """Tests for should_filter method""" - - def test_should_filter_sports_content(self): - """Should filter sports content with 2+ keywords""" - filter = ContentFilter() - - should_filter, reason = filter.should_filter( - title="NFL Quarterback Throws Touchdown in Playoff Game", - description="Football action", - ) - - assert should_filter is True - assert reason == "sports" - - def test_should_not_filter_single_sports_keyword(self): - """Should not filter with only one sports keyword""" - filter = ContentFilter() - - should_filter, reason = filter.should_filter( - title="The Football Stadium as Urban Architecture", - description="Design analysis", - ) - - assert should_filter is False - - def test_should_filter_clickbait(self): - """Should filter clickbait titles""" - filter = ContentFilter() - - should_filter, reason = filter.should_filter( - title="You Won't Believe What This Expert Discovered", - description="Normal content", - ) - - assert should_filter is True - assert reason == "clickbait" - - def test_should_filter_excessive_exclamation(self): - """Should filter titles with excessive punctuation""" - filter = ContentFilter() - - should_filter, reason = filter.should_filter( - title="Amazing Discovery!! Shocking News!!", - description="Normal content", - ) - - assert should_filter is True - assert reason == "clickbait" - - def test_should_filter_excessive_question_marks(self): - """Should filter titles with excessive question marks""" - filter = ContentFilter() - - should_filter, reason = filter.should_filter( - title="Is This Real?? Can You Believe??", - description="Normal content", - ) - - assert should_filter is True - assert reason == "clickbait" - - def test_should_filter_all_caps_words(self): - """Should filter titles with excessive ALL CAPS""" - filter = ContentFilter() - - should_filter, reason = filter.should_filter( - title="THIS SHOCKING NEWS WILL CHANGE Everything", - description="Normal content", - ) - - assert should_filter is True - assert reason == "clickbait" - - def test_should_not_filter_acronyms(self): - """Should not filter legitimate acronyms (<=3 chars)""" - filter = ContentFilter() - - should_filter, reason = filter.should_filter( - title="FBI and CIA Release Joint Report on Security", - description="Government agencies", - ) - - assert should_filter is False - - def test_should_filter_listicle_pattern(self): - """Should filter listicle clickbait patterns""" - filter = ContentFilter() - - should_filter, reason = filter.should_filter( - title="10 Reasons You Need to Read This Now", - description="Normal content", - ) - - assert should_filter is True - assert reason == "clickbait" - - def test_should_filter_entertainment(self): - """Should filter entertainment content""" - filter = ContentFilter() - - should_filter, reason = filter.should_filter( - title="Celebrity Fashion at the Oscars Red Carpet", - description="Hollywood event", - ) - - assert should_filter is True - assert reason == "entertainment" - - def test_should_filter_user_excluded_topic(self, mock_user_profile): - """Should filter user-specified excluded topics""" - filter = ContentFilter(user_profile=mock_user_profile) - - should_filter, reason = filter.should_filter( - title="New Crypto Trading Platform Launches", - description="Cryptocurrency news", - ) - - assert should_filter is True - assert reason == "excluded_topic:crypto" - - def test_should_not_filter_normal_content(self): - """Should not filter normal news content""" - filter = ContentFilter() - - should_filter, reason = filter.should_filter( - title="City Council Approves New Infrastructure Plan", - description="Local government news", - ) - - assert should_filter is False - assert reason is None - - -class TestFilterArticles: - """Tests for filtering article lists""" - - def test_filter_articles_separates_kept_and_filtered(self, sports_article, normal_article): - """Should separate kept and filtered articles""" - filter = ContentFilter() - - kept, filtered = filter.filter_articles([sports_article, normal_article]) - - assert len(kept) == 1 - assert len(filtered) == 1 - assert normal_article in kept - assert sports_article in filtered - - def test_filter_articles_marks_filtered_flag(self, sports_article): - """Should set filtered flag on filtered articles""" - filter = ContentFilter() - - _kept, filtered = filter.filter_articles([sports_article]) - - assert sports_article.filtered is True - assert sports_article.filter_reason == "sports" - - def test_filter_articles_empty_list(self): - """Should handle empty list""" - filter = ContentFilter() - - kept, filtered = filter.filter_articles([]) - - assert kept == [] - assert filtered == [] - - def test_filter_articles_all_kept(self, normal_article, sample_article_factory): - """Should keep all non-matching articles""" - filter = ContentFilter() - article2 = sample_article_factory( - id=20, title="Another Normal Article", description="More news" - ) - - kept, filtered = filter.filter_articles([normal_article, article2]) - - assert len(kept) == 2 - assert len(filtered) == 0 - - -class TestGetFilterStats: - """Tests for filter statistics""" - - def test_get_filter_stats_basic(self, sports_article, clickbait_article, normal_article): - """Should return filtering statistics""" - filter = ContentFilter() - - # Pre-filter to set flags - filter.filter_articles([sports_article, clickbait_article, normal_article]) - - stats = filter.get_filter_stats([sports_article, clickbait_article, normal_article]) - - assert stats["total_articles"] == 3 - assert stats["filtered_count"] == 2 - assert stats["kept_count"] == 1 - assert stats["filter_rate"] == pytest.approx(2 / 3, rel=0.01) - assert "sports" in stats["reasons"] - assert "clickbait" in stats["reasons"] - - def test_get_filter_stats_empty_list(self): - """Should handle empty list without division error""" - filter = ContentFilter() - - stats = filter.get_filter_stats([]) - - assert stats["total_articles"] == 0 - assert stats["filter_rate"] == 0 - - def test_get_filter_stats_no_filtered(self, normal_article, sample_article_factory): - """Should handle no filtered articles""" - filter = ContentFilter() - article2 = sample_article_factory(id=21, title="News Update", description="News") - - filter.filter_articles([normal_article, article2]) - - stats = filter.get_filter_stats([normal_article, article2]) - - assert stats["filtered_count"] == 0 - assert stats["filter_rate"] == 0 - assert stats["reasons"] == {} diff --git a/tests/processors/test_deduplicator.py b/tests/processors/test_deduplicator.py deleted file mode 100644 index a33f808..0000000 --- a/tests/processors/test_deduplicator.py +++ /dev/null @@ -1,379 +0,0 @@ -""" -Tests for Article Deduplicator -""" - -from unittest.mock import MagicMock, patch - -from src.processors.deduplicator import ArticleDeduplicator, run_deduplication - - -class TestArticleDeduplicatorInit: - """Tests for ArticleDeduplicator initialization""" - - def test_init_default_values(self): - """Should initialize with default values""" - deduplicator = ArticleDeduplicator() - - assert deduplicator.similarity_threshold == 0.85 - assert deduplicator.time_window_hours == 72 - - def test_init_custom_values(self): - """Should accept custom values""" - deduplicator = ArticleDeduplicator(similarity_threshold=0.9, time_window_hours=48) - - assert deduplicator.similarity_threshold == 0.9 - assert deduplicator.time_window_hours == 48 - - -class TestGenerateContentHash: - """Tests for content hash generation""" - - def test_generate_content_hash_basic(self): - """Should generate consistent hash for same content""" - deduplicator = ArticleDeduplicator() - - hash1 = deduplicator.generate_content_hash("Title", "Content") - hash2 = deduplicator.generate_content_hash("Title", "Content") - - assert hash1 == hash2 - assert len(hash1) == 32 # MD5 hex digest length - - def test_generate_content_hash_different_content(self): - """Should generate different hash for different content""" - deduplicator = ArticleDeduplicator() - - hash1 = deduplicator.generate_content_hash("Title", "Content A") - hash2 = deduplicator.generate_content_hash("Title", "Content B") - - assert hash1 != hash2 - - def test_generate_content_hash_empty_title(self): - """Should return empty string for empty title""" - deduplicator = ArticleDeduplicator() - - result = deduplicator.generate_content_hash("", "Content") - - assert result == "" - - def test_generate_content_hash_empty_content(self): - """Should return empty string for empty content""" - deduplicator = ArticleDeduplicator() - - result = deduplicator.generate_content_hash("Title", "") - - assert result == "" - - def test_generate_content_hash_none_values(self): - """Should return empty string for None values""" - deduplicator = ArticleDeduplicator() - - result = deduplicator.generate_content_hash(None, None) - - assert result == "" - - def test_generate_content_hash_normalized(self): - """Should normalize text before hashing (case, punctuation)""" - deduplicator = ArticleDeduplicator() - - hash1 = deduplicator.generate_content_hash("Test Title!", "Content.") - hash2 = deduplicator.generate_content_hash("test title", "content") - - assert hash1 == hash2 - - -class TestGenerateTitleHash: - """Tests for title hash generation""" - - def test_generate_title_hash_basic(self): - """Should generate consistent hash for same title""" - deduplicator = ArticleDeduplicator() - - hash1 = deduplicator.generate_title_hash("Breaking News") - hash2 = deduplicator.generate_title_hash("Breaking News") - - assert hash1 == hash2 - - def test_generate_title_hash_empty(self): - """Should return empty string for empty title""" - deduplicator = ArticleDeduplicator() - - result = deduplicator.generate_title_hash("") - - assert result == "" - - def test_generate_title_hash_none(self): - """Should return empty string for None""" - deduplicator = ArticleDeduplicator() - - result = deduplicator.generate_title_hash(None) - - assert result == "" - - def test_generate_title_hash_normalized(self): - """Should normalize title before hashing""" - deduplicator = ArticleDeduplicator() - - hash1 = deduplicator.generate_title_hash("Breaking News!") - hash2 = deduplicator.generate_title_hash("breaking news") - - assert hash1 == hash2 - - -class TestNormalizeText: - """Tests for text normalization""" - - def test_normalize_text_lowercase(self): - """Should convert to lowercase""" - deduplicator = ArticleDeduplicator() - - result = deduplicator._normalize_text("UPPERCASE TEXT") - - assert result == "uppercase text" - - def test_normalize_text_removes_punctuation(self): - """Should remove punctuation""" - deduplicator = ArticleDeduplicator() - - result = deduplicator._normalize_text("Hello, World!") - - assert result == "hello world" - - def test_normalize_text_collapses_whitespace(self): - """Should collapse multiple whitespace""" - deduplicator = ArticleDeduplicator() - - result = deduplicator._normalize_text("Multiple spaces here") - - assert result == "multiple spaces here" - - def test_normalize_text_strips_edges(self): - """Should strip leading/trailing whitespace""" - deduplicator = ArticleDeduplicator() - - result = deduplicator._normalize_text(" Text with spaces ") - - assert result == "text with spaces" - - def test_normalize_text_empty(self): - """Should return empty string for empty input""" - deduplicator = ArticleDeduplicator() - - result = deduplicator._normalize_text("") - - assert result == "" - - def test_normalize_text_none(self): - """Should return empty string for None""" - deduplicator = ArticleDeduplicator() - - result = deduplicator._normalize_text(None) - - assert result == "" - - -class TestFindExactDuplicates: - """Tests for exact duplicate detection""" - - def test_find_exact_duplicates_no_title(self, sample_article_factory): - """Should return empty list for article without title""" - deduplicator = ArticleDeduplicator() - article = sample_article_factory(title="", normalized_content="Content") - mock_db = MagicMock() - - result = deduplicator.find_exact_duplicates(article, mock_db) - - assert result == [] - - def test_find_exact_duplicates_no_content(self, sample_article_factory): - """Should return empty list for article without content""" - deduplicator = ArticleDeduplicator() - article = sample_article_factory(title="Title", normalized_content="") - mock_db = MagicMock() - - result = deduplicator.find_exact_duplicates(article, mock_db) - - assert result == [] - - -class TestFindNearDuplicates: - """Tests for near-duplicate detection""" - - def test_find_near_duplicates_no_title(self, sample_article_factory): - """Should return empty list for article without title""" - deduplicator = ArticleDeduplicator() - article = sample_article_factory(title="") - mock_db = MagicMock() - - result = deduplicator.find_near_duplicates(article, mock_db) - - assert result == [] - - -class TestMarkAsDuplicate: - """Tests for marking articles as duplicates""" - - def test_mark_as_duplicate_exact(self, duplicate_article_pair): - """Should mark exact duplicate correctly""" - deduplicator = ArticleDeduplicator() - original, duplicate = duplicate_article_pair - mock_db = MagicMock() - - deduplicator.mark_as_duplicate(original, duplicate, mock_db) - - assert duplicate.priority_metadata["is_duplicate"] is True - assert duplicate.priority_metadata["duplicate_of"] == original.id - assert duplicate.priority_metadata["duplicate_type"] == "exact" - assert duplicate.priority_score == 0.1 - - def test_mark_as_duplicate_near(self, near_duplicate_pair): - """Should mark near duplicate correctly""" - deduplicator = ArticleDeduplicator() - original, duplicate = near_duplicate_pair - mock_db = MagicMock() - - deduplicator.mark_as_duplicate(original, duplicate, mock_db) - - assert duplicate.priority_metadata["is_duplicate"] is True - assert duplicate.priority_metadata["duplicate_type"] == "near" - - def test_mark_as_duplicate_initializes_metadata(self, sample_article_factory): - """Should initialize metadata if None""" - deduplicator = ArticleDeduplicator() - original = sample_article_factory(id=1) - duplicate = sample_article_factory(id=2, priority_metadata=None) - mock_db = MagicMock() - - deduplicator.mark_as_duplicate(original, duplicate, mock_db) - - assert duplicate.priority_metadata is not None - - -class TestIsExactDuplicate: - """Tests for exact duplicate check""" - - def test_is_exact_duplicate_true(self, duplicate_article_pair): - """Should return True for exact duplicates""" - deduplicator = ArticleDeduplicator() - original, duplicate = duplicate_article_pair - - result = deduplicator._is_exact_duplicate(original, duplicate) - - assert result is True - - def test_is_exact_duplicate_false(self, sample_article_factory): - """Should return False for different content""" - deduplicator = ArticleDeduplicator() - article1 = sample_article_factory(title="Title A", normalized_content="Content A") - article2 = sample_article_factory(title="Title B", normalized_content="Content B") - - result = deduplicator._is_exact_duplicate(article1, article2) - - assert result is False - - def test_is_exact_duplicate_missing_fields(self, sample_article_factory): - """Should return False if missing required fields""" - deduplicator = ArticleDeduplicator() - article1 = sample_article_factory(title="", normalized_content="Content") - article2 = sample_article_factory(title="Title", normalized_content="Content") - - result = deduplicator._is_exact_duplicate(article1, article2) - - assert result is False - - -class TestDeduplicateRecentArticles: - """Tests for deduplicating recent articles""" - - @patch("src.processors.deduplicator.get_db") - def test_deduplicate_returns_stats(self, mock_get_db): - """Should return deduplication statistics""" - mock_db = MagicMock() - mock_get_db.return_value.__enter__ = MagicMock(return_value=mock_db) - mock_get_db.return_value.__exit__ = MagicMock(return_value=False) - - mock_query = MagicMock() - mock_db.query.return_value = mock_query - mock_query.filter.return_value = mock_query - mock_query.order_by.return_value = mock_query - mock_query.all.return_value = [] - - deduplicator = ArticleDeduplicator() - - result = deduplicator.deduplicate_recent_articles(hours=24) - - assert "processed_articles" in result - assert "url_duplicates" in result - assert "exact_duplicates" in result - assert "title_duplicates" in result - assert "total_duplicates" in result - - -class TestGetDuplicateStatistics: - """Tests for duplicate statistics""" - - @patch("src.processors.deduplicator.get_db") - def test_get_duplicate_statistics_returns_dict(self, mock_get_db): - """Should return statistics dictionary""" - mock_db = MagicMock() - mock_get_db.return_value.__enter__ = MagicMock(return_value=mock_db) - mock_get_db.return_value.__exit__ = MagicMock(return_value=False) - - mock_query = MagicMock() - mock_db.query.return_value = mock_query - mock_query.count.return_value = 100 - mock_query.all.return_value = [] - - deduplicator = ArticleDeduplicator() - - result = deduplicator.get_duplicate_statistics() - - assert "total_articles" in result - assert "duplicate_articles" in result - assert "original_articles" in result - assert "unique_articles" in result - assert "duplication_rate" in result - - @patch("src.processors.deduplicator.get_db") - def test_get_duplicate_statistics_zero_articles(self, mock_get_db): - """Should handle zero articles without division error""" - mock_db = MagicMock() - mock_get_db.return_value.__enter__ = MagicMock(return_value=mock_db) - mock_get_db.return_value.__exit__ = MagicMock(return_value=False) - - mock_query = MagicMock() - mock_db.query.return_value = mock_query - mock_query.count.return_value = 0 - mock_query.all.return_value = [] - - deduplicator = ArticleDeduplicator() - - result = deduplicator.get_duplicate_statistics() - - assert result["duplication_rate"] == 0.0 - - -class TestRunDeduplication: - """Tests for convenience function""" - - @patch("src.processors.deduplicator.ArticleDeduplicator") - def test_run_deduplication_creates_deduplicator(self, mock_class): - """Should create ArticleDeduplicator and call method""" - mock_instance = MagicMock() - mock_class.return_value = mock_instance - mock_instance.deduplicate_recent_articles.return_value = {} - - run_deduplication(hours=12) - - mock_class.assert_called_once() - mock_instance.deduplicate_recent_articles.assert_called_with(hours=12) - - @patch("src.processors.deduplicator.ArticleDeduplicator") - def test_run_deduplication_default_hours(self, mock_class): - """Should default to 24 hours""" - mock_instance = MagicMock() - mock_class.return_value = mock_instance - mock_instance.deduplicate_recent_articles.return_value = {} - - run_deduplication() - - mock_instance.deduplicate_recent_articles.assert_called_with(hours=24) diff --git a/data/forecasts/.gitkeep b/tests/routing/__init__.py similarity index 100% rename from data/forecasts/.gitkeep rename to tests/routing/__init__.py diff --git a/tests/routing/test_compile.py b/tests/routing/test_compile.py new file mode 100644 index 0000000..5128c59 --- /dev/null +++ b/tests/routing/test_compile.py @@ -0,0 +1,104 @@ +""" +Trigger clause semantics, as the watch file promises them. + +AND across a clause's populated fields, OR within a field, any clause fires +the watch, word boundaries and the shouted-term case rule throughout. Every +test here is a sentence from ``config/watches.example.yaml``'s comment block +turned into an assertion. +""" + +import pytest + +from src.routing import TriggerCompileError, compile_triggers + + +def first(triggers, text, source="Any Source"): + return compile_triggers("w", triggers).first_match(text, source) + + +class TestFieldSemantics: + def test_any_term_in_a_field_matches(self): + clauses = [{"terms": ["continuous monitoring", "ConMon"]}] + assert first(clauses, "The ConMon scope grew.") == 0 + assert first(clauses, "Continuous monitoring expanded.") == 0 + + def test_every_populated_field_in_a_clause_must_match(self): + clauses = [{"entities": ["FedRAMP PMO"], "terms": ["continuous monitoring"]}] + assert first(clauses, "FedRAMP PMO expanded continuous monitoring.") == 0 + assert first(clauses, "FedRAMP PMO published guidance.") is None + assert first(clauses, "Continuous monitoring is hard.") is None + + def test_any_clause_fires_and_the_first_is_recorded(self): + clauses = [ + {"terms": ["Rev 5"]}, + {"sources": ["Federal Register"], "terms": ["FedRAMP"]}, + ] + assert first(clauses, "FedRAMP notice", source="Federal Register") == 1 + assert first(clauses, "Rev 5 and FedRAMP", source="Federal Register") == 0 + + def test_sources_match_the_name_case_insensitively_and_exactly(self): + clauses = [{"sources": ["Federal Register"], "terms": ["FedRAMP"]}] + assert first(clauses, "FedRAMP", source="federal register") == 0 + assert first(clauses, "FedRAMP", source="Federal Register - Documents API") is None + + def test_a_sources_only_clause_routes_everything_from_that_source(self): + clauses = [{"sources": ["Federal Register"]}] + assert first(clauses, "anything at all", source="Federal Register") == 0 + assert first(clauses, "anything at all", source="AP") is None + + +class TestBoundariesAndCase: + """ + The two rules that cost a day to find. Word boundaries: of 55,249 + articles, 5,364 contained the substring ``nist`` and 73 matched at a word + boundary. Case: ``BOD`` is a directive; ``body`` is not. + """ + + def test_a_term_inside_a_longer_word_does_not_match(self): + assert first([{"terms": ["CISA"]}], "precisa") is None + assert first([{"terms": ["NIST"]}], "the administration said") is None + assert first([{"terms": ["CISA"]}], "CISA-issued directive") == 0 + + def test_a_shouted_term_is_case_sensitive(self): + assert first([{"entities": ["BOD"]}], "the body politic") is None + assert first([{"entities": ["BOD"]}], "BOD 23-01") == 0 + assert first([{"terms": ["OMB"]}], "combat readiness") is None + + def test_a_mixed_case_term_is_case_insensitive(self): + assert first([{"terms": ["FedRAMP"]}], "FEDRAMP marketplace") == 0 + assert first([{"terms": ["continuous monitoring"]}], "CONTINUOUS MONITORING") == 0 + + def test_whitespace_inside_a_term_survives_a_line_wrap(self): + assert first([{"terms": ["continuous monitoring"]}], "continuous\nmonitoring") == 0 + + def test_entities_compile_exactly_as_terms_do(self): + as_term = compile_triggers("a", [{"terms": ["FedRAMP PMO"]}]) + as_entity = compile_triggers("b", [{"entities": ["FedRAMP PMO"]}]) + for text in ("fedramp pmo said", "the FedRAMP PMO", "FedRAMP PMOs"): + assert (as_term.first_match(text, "s") is None) == ( + as_entity.first_match(text, "s") is None + ) + + +class TestRefusal: + """A stored row can be written by hand; the compiler refuses what the loader would.""" + + @pytest.mark.parametrize( + "triggers", + [ + None, + [], + [{}], + [{"terms": []}], + [{"terms": "a sentence, not a list"}], + [{"topic": ["unknown field"]}], + ["prose clause"], + ], + ) + def test_uncompilable_triggers_raise(self, triggers): + with pytest.raises(TriggerCompileError): + compile_triggers("w", triggers) + + def test_the_error_names_the_watch_and_the_clause(self): + with pytest.raises(TriggerCompileError, match=r"watch 'w' clause 1"): + compile_triggers("w", [{"terms": ["ok"]}, {"nope": ["x"]}]) diff --git a/tests/routing/test_no_llm.py b/tests/routing/test_no_llm.py new file mode 100644 index 0000000..374282b --- /dev/null +++ b/tests/routing/test_no_llm.py @@ -0,0 +1,51 @@ +""" +Tier 1 makes no model call, proved by making one impossible. + +The import of ``src.llm`` and of the ``anthropic`` package is blocked for the +duration of the test with a meta-path finder that raises, every already-loaded +copy is evicted first, and the full routing path is then driven from a fresh +import. A routing tier that reached for a model, even lazily, would fail here. +""" + +import importlib +import sys +from datetime import date, datetime + +import pytest + +from ..evidence.stubs import add_observations, add_watches + +BLOCKED = ("src.llm", "anthropic") + + +class _Blocker: + def find_spec(self, name, path=None, target=None): + if name in BLOCKED or any(name.startswith(prefix + ".") for prefix in BLOCKED): + raise ImportError(f"{name} is blocked: Tier 1 must not import it") + return None + + +@pytest.fixture +def no_llm(monkeypatch): + for name in list(sys.modules): + if name in BLOCKED or any(name.startswith(prefix + ".") for prefix in BLOCKED): + monkeypatch.delitem(sys.modules, name, raising=False) + for name in list(sys.modules): + if name.startswith("src.routing"): + monkeypatch.delitem(sys.modules, name, raising=False) + monkeypatch.setattr(sys, "meta_path", [_Blocker(), *sys.meta_path]) + yield + + +def test_the_full_routing_path_runs_with_the_model_client_unimportable(no_llm, test_session): + with pytest.raises(ImportError): + importlib.import_module("src.llm") + + routing = importlib.import_module("src.routing") + add_watches(test_session) + add_observations(test_session) + + report = routing.route(test_session, since=datetime(2026, 8, 1), today=date(2026, 9, 1)) + + assert report.routed == 2 + assert not any(name.startswith("src.llm") for name in sys.modules) diff --git a/tests/routing/test_regression.py b/tests/routing/test_regression.py new file mode 100644 index 0000000..5bef0dc --- /dev/null +++ b/tests/routing/test_regression.py @@ -0,0 +1,158 @@ +""" +The routing gate: whole words route, look-alikes do not, and nothing else does. + +A routing predicate that is too loose does not fail, it bills: every routed +pair becomes a model call. So the property is pinned with a number rather than +a dashboard. A thousand synthetic observations against five watches carry +exactly twenty planted whole-word matches and one hundred planted look-alikes +-- mostly the trigger term inside a longer word, in shouted and mixed case, +plus a few whole-word case variants of a shouted acronym -- and exactly the +twenty planted items must route, checked by identity and not by count. + +Verified on 2026-09-22 (backlog task 028) by emptying ``LEFT_BOUNDARY`` and +``RIGHT_BOUNDARY`` in ``src/matching/entity_matcher.py`` and running this +file: it failed with 61 routed. Task 010 found a boundary +test that passed for the wrong reason -- shouted terms were rejected by +case-sensitivity before the anchors were consulted -- which is why the +look-alikes here include ``PRECISA`` and ``COMBAT`` in capitals, which only +the anchors reject, and not only ``precisa``. +""" + +from datetime import date, datetime + +from src.database.models import Observation, Route, Watch +from src.routing import route +from src.sources.base import RawItem +from src.sources.store import ensure_source, store_items + +TODAY = date(2026, 9, 1) +SINCE = datetime(2026, 8, 1) + +WATCHES = { + "cisa-directive": ("CISA", "BOD"), + "nist-baseline": ("NIST",), + "fedramp-scope": ("FedRAMP", "continuous monitoring"), + "omb-memo": ("OMB",), + "hiring": ("compliance engineer",), +} + +# One planted match per (watch, term), whole words, twenty in all. +PLANTED = [ + "CISA issued a directive today.", + "The BOD requires patching within 30 days.", + "CISA and BOD both appear here.", + "A directive from CISA, again.", + "NIST published the revision.", + "The baseline is NIST's.", + "NIST SP 800-53 changed.", + "A NIST comment period opened.", + "FedRAMP guidance was updated.", + "Continuous monitoring scope grew.", + "FedRAMP and continuous monitoring together.", + "fedramp in lower case still counts.", + "OMB released a memo.", + "The OMB memorandum M-26-01.", + "OMB, in a memo, said so.", + "OMB guidance again.", + "Hiring a compliance engineer.", + "The compliance engineer role is open.", + "A senior compliance engineer left.", + "Compliance Engineer, capitalised, counts.", +] +assert len(PLANTED) == 20 + +# Look-alikes, in two kinds. The lower-case ones (``precisa``, ``combat``) are +# rejected by the case rule before the anchors are consulted, which is the +# trap task 010 found. The SHOUTED ones (``PRECISA``, ``COMBAT``, ``BODY``) +# contain the acronym exactly and are rejected by the anchors alone; without +# them, they route. The mixed-case terms are case-insensitive, so +# ``FedRAMPed`` and ``noncompliance engineering`` also rest on the anchors. +LOOKALIKES = [ + "precisa", + "PRECISA", + "Cisak said", + "cisa lower is not the agency", + "the body politic", + "THE BODY POLITIC", + "bodice", + "administration", + "the minister spoke", + "NISTY WEATHER", + "communist", + "FedRAMPed through", + "combat", + "COMBAT READINESS", + "OMBUDSMAN", + "bombing", + "thrombosis", + "compliance engineers' union", + "noncompliance engineering", +] + + +def _corpus(session): + source = ensure_source(session, "Synthetic", "https://example.org/synthetic", "misc") + items = [] + n = 0 + for text in PLANTED: + items.append(_item(n, text)) + n += 1 + for i in range(100): + items.append(_item(n, LOOKALIKES[i % len(LOOKALIKES)] + f" ({i})")) + n += 1 + while n < 1000: + items.append(_item(n, f"Filler item {n} about the county fair and {n * 31} pies.")) + n += 1 + store_items(session, source, items) + session.flush() + + +def _item(n: int, text: str) -> RawItem: + return RawItem( + guid=f"s{n}", + url=f"https://example.org/s{n}", + title=text, + normalized_content=f"{text} Body of item {n}.", + published_date=datetime(2026, 8, 20), + ) + + +def _watches(session): + for watch_id, terms in WATCHES.items(): + session.add( + Watch( + id=watch_id, + claim=f"{watch_id} claim", + belief=0.5, + decision_key="d", + so_what="because", + triggers=[{"terms": list(terms)}], + expires=date(2027, 1, 1), + staleness_alert_days=30, + ) + ) + session.flush() + + +def test_exactly_the_planted_whole_word_matches_route(test_session): + _watches(test_session) + _corpus(test_session) + + report = route(test_session, since=SINCE, today=TODAY) + + assert report.observations == 1000 + assert report.routed == 20 + planted_hashes = { + h + for h, payload in test_session.query(Observation.content_hash, Observation.payload) + if payload["guid"] in {f"s{n}" for n in range(len(PLANTED))} + } + routed_hashes = {h for (h,) in test_session.query(Route.observation_hash)} + assert routed_hashes == planted_hashes + assert {w.watch_id: w.total for w in report.watches} == { + "cisa-directive": 4, + "nist-baseline": 4, + "fedramp-scope": 4, + "omb-memo": 4, + "hiring": 4, + } diff --git a/tests/routing/test_route.py b/tests/routing/test_route.py new file mode 100644 index 0000000..7c25980 --- /dev/null +++ b/tests/routing/test_route.py @@ -0,0 +1,227 @@ +""" +The router over a stored corpus: what routes, idempotency, the unrouted report. + +The corpus and watches come from tests/evidence/stubs.py, the same fixture the +replay tests use, so routing and replay cannot drift apart about what the +corpus contains. Two of the four items carry a watch's terms; two carry +nothing any watch is written for. +""" + +from datetime import date, datetime + +import pytest + +from src.database.models import Observation, Route, Watch +from src.routing import RoutingReport, live_watches, route +from src.sources.base import RawItem +from src.sources.store import ensure_source, store_items + +from ..evidence.stubs import add_observations, add_watches + +TODAY = date(2026, 9, 1) +SINCE = datetime(2026, 8, 1) + + +@pytest.fixture +def corpus(test_session): + add_watches(test_session) + add_observations(test_session) + return test_session + + +def _routes(session) -> set[tuple[str, str]]: + return {(r.observation_hash, r.watch_id) for r in session.query(Route).all()} + + +def _hash_of(session, guid: str) -> str: + for h, payload in session.query(Observation.content_hash, Observation.payload).all(): + if payload["guid"] == guid: + return h + raise AssertionError(guid) + + +class TestRouting: + def test_routes_the_items_that_carry_a_trigger_and_nothing_else(self, corpus): + report = route(corpus, since=SINCE, today=TODAY) + + assert _routes(corpus) == { + (_hash_of(corpus, "doc-1"), "conmon-scope-expands"), + (_hash_of(corpus, "doc-2"), "hiring-market-tightens"), + } + assert report.observations == 4 + assert report.routed == 2 + assert report.unrouted == 2 + assert report.written is True + + def test_records_the_first_clause_that_fired(self, corpus): + """A watch whose second clause is the one that matches records index 1.""" + corpus.add( + Watch( + id="fruit", + claim="Fall fruit guidance changes.", + belief=0.5, + decision_key="d", + so_what="because", + triggers=[{"terms": ["nothing-that-appears"]}, {"terms": ["persimmons"]}], + expires=date(2027, 1, 1), + staleness_alert_days=30, + ) + ) + corpus.flush() + + route(corpus, since=SINCE, today=TODAY) + + rows = corpus.query(Route.watch_id, Route.clause_index).order_by(Route.watch_id).all() + assert [(w, c) for w, c in rows] == [ + ("conmon-scope-expands", 0), + ("fruit", 1), + ("hiring-market-tightens", 0), + ] + + def test_routing_twice_produces_one_link_per_pair(self, corpus): + first = route(corpus, since=SINCE, today=TODAY) + second = route(corpus, since=SINCE, today=TODAY) + + assert corpus.query(Route).count() == 2 + assert [w.new for w in first.watches] == [1, 1] + assert [w.new for w in second.watches] == [0, 0] + assert [w.total for w in second.watches] == [1, 1] + + def test_a_dry_run_computes_the_same_report_and_writes_nothing(self, corpus): + dry = route(corpus, since=SINCE, today=TODAY, write=False) + assert corpus.query(Route).count() == 0 + assert dry.written is False + + wet = route(corpus, since=SINCE, today=TODAY) + assert [(w.watch_id, w.new, w.total) for w in dry.watches] == [ + (w.watch_id, w.new, w.total) for w in wet.watches + ] + assert (dry.unrouted, dry.unrouted_by_source, dry.clusters, dry.clusters_omitted) == ( + wet.unrouted, + wet.unrouted_by_source, + wet.clusters, + wet.clusters_omitted, + ) + + def test_a_retired_or_resolved_watch_is_not_live(self, corpus): + from src.position.ledger import resolve_watch + + corpus.get(Watch, "conmon-scope-expands").retired_at = datetime(2026, 8, 30) + resolve_watch(corpus, "hiring-market-tightens", outcome="no", note="settled") + corpus.flush() + + assert live_watches(corpus, TODAY) == [] + report = route(corpus, since=SINCE, today=TODAY) + assert report.watches == [] + assert corpus.query(Route).count() == 0 + + def test_an_expired_watch_is_not_live(self, corpus): + assert {w.watch_id for w in live_watches(corpus, date(2027, 1, 1))} == { + "conmon-scope-expands" + } + report = route(corpus, since=SINCE, today=date(2027, 1, 1)) + assert [w.watch_id for w in report.watches] == ["conmon-scope-expands"] + + def test_rebuild_discards_links_and_routes_the_whole_corpus(self, corpus): + route(corpus, since=SINCE, today=TODAY) + stale = Route( + observation_hash=_hash_of(corpus, "doc-3"), + watch_id="conmon-scope-expands", + clause_index=0, + ) + corpus.add(stale) + corpus.flush() + + report = route(corpus, since=datetime(2030, 1, 1), today=TODAY, rebuild=True) + + assert report.rebuild is True + assert corpus.query(Route).count() == 2 + assert (_hash_of(corpus, "doc-3"), "conmon-scope-expands") not in _routes(corpus) + # Routing covered the corpus; the unrouted report covers the window, which is empty. + assert report.observations == 4 + assert report.unrouted == 0 + assert report.clusters == [] + + def test_the_window_excludes_older_items(self, corpus): + report = route(corpus, since=datetime(2026, 8, 21), today=TODAY) + # doc-1 was published 2026-08-20 and falls outside the window. + assert report.observations == 3 + assert (_hash_of(corpus, "doc-1"), "conmon-scope-expands") not in _routes(corpus) + + def test_an_undated_item_falls_back_to_when_it_was_observed(self, corpus): + source = ensure_source(corpus, "Undated Feed", "https://example.org/undated", "misc") + store_items( + corpus, + source, + [ + RawItem( + guid="u", url="https://example.org/u", title="ConMon news", published_date=None + ) + ], + ) + corpus.flush() + + report = route(corpus, since=datetime(2026, 8, 21), today=TODAY) + + assert (_hash_of(corpus, "u"), "conmon-scope-expands") in _routes(corpus) + assert report.observations == 4 + + +class TestUnroutedReport: + def test_unrouted_items_are_clustered_and_named_by_source(self, corpus): + report = route(corpus, since=SINCE, today=TODAY) + + assert report.unrouted == 2 + assert report.unrouted_by_source == [("Example Agency", 2)] + assert sum(c.size for c in report.clusters) == 2 + assert all(c.sources == ("Example Agency",) for c in report.clusters) + assert {c.title for c in report.clusters} == { + "Persimmons ripen after the first frost", + "Notice of meeting", + } + + def test_the_listing_is_bounded_and_says_what_it_left_out(self, test_session): + add_watches(test_session) + source = ensure_source(test_session, "Bulk", "https://example.org/bulk", "misc") + items = [ + RawItem( + guid=f"b{i}", + url=f"https://example.org/b{i}", + title=f"Unrelated story number {i} about {i * 7919}", + normalized_content=f"Body {i} " + " ".join(str(i * k) for k in range(1, 30)), + published_date=datetime(2026, 8, 20), + ) + for i in range(14) + ] + store_items(test_session, source, items) + test_session.flush() + + report = route(test_session, since=SINCE, today=TODAY) + + assert report.unrouted == 14 + assert len(report.clusters) == 10 + assert report.clusters_omitted == 4 + + def test_clustering_is_skipped_above_the_bound_and_says_so(self, test_session, monkeypatch): + """The pairwise grouper is O(n^2); the report refuses to run it over a corpus.""" + import importlib + + # The package re-exports the route() function under the same name as the + # submodule, so fetch the module through importlib rather than by attribute. + module = importlib.import_module("src.routing.route") + monkeypatch.setattr(module, "CLUSTER_LIMIT", 3) + add_observations(test_session) + + report = route(test_session, since=SINCE, today=TODAY) + + assert report.unrouted == 4 + assert report.clustering_skipped == 4 + assert report.clusters == [] + assert report.unrouted_by_source == [("Example Agency", 4)] + + def test_no_live_watches_means_everything_is_unrouted(self, test_session): + add_observations(test_session) + report = route(test_session, since=SINCE, today=TODAY) + assert isinstance(report, RoutingReport) + assert report.watches == [] + assert report.unrouted == 4 diff --git a/tests/rss/conftest.py b/tests/rss/conftest.py index bb9ab93..a745b31 100644 --- a/tests/rss/conftest.py +++ b/tests/rss/conftest.py @@ -67,51 +67,6 @@ def empty_rss_response(): """ -@pytest.fixture -def malformed_rss_response(): - """Malformed RSS content""" - return b" count - assert "Network error" in result["error_summary"] - assert result["error_summary"]["Network error"] == 1 - - -class TestRateLimitedFetch: - """Tests for rate-limited fetching""" - - @pytest.mark.asyncio - @patch("src.rss.parallel_fetcher.RSSFetcher") - async def test_rate_limited_fetch_success(self, mock_fetcher_class, mock_rss_feed): - """Should return FetchResult on success""" - mock_fetcher = MagicMock() - mock_fetcher.fetch_and_store_feed = AsyncMock(return_value=(True, 3, None)) - - fetcher = ParallelRSSFetcher() - - result = await fetcher._rate_limited_fetch(mock_fetcher, mock_rss_feed) - - assert isinstance(result, FetchResult) - assert result.success is True - assert result.articles_count == 3 - assert result.feed_name == mock_rss_feed.name - - @pytest.mark.asyncio - @patch("src.rss.parallel_fetcher.RSSFetcher") - async def test_rate_limited_fetch_exception(self, mock_fetcher_class, mock_rss_feed): - """Should handle exceptions during fetch""" - mock_fetcher = MagicMock() - mock_fetcher.fetch_and_store_feed = AsyncMock(side_effect=Exception("Unexpected error")) - - fetcher = ParallelRSSFetcher() - - result = await fetcher._rate_limited_fetch(mock_fetcher, mock_rss_feed) - - assert result.success is False - assert "Unexpected error" in result.error_message - - -class TestGenerateSummary: - """Tests for summary generation""" - - def test_generate_summary_basic(self): - """Should generate correct summary statistics""" - fetcher = ParallelRSSFetcher() - - results = [ - FetchResult(1, "Feed1", True, 10, None, 1.0), - FetchResult(2, "Feed2", True, 5, None, 1.5), - FetchResult(3, "Feed3", False, 0, "Error", 2.0), - ] - - summary = fetcher._generate_summary(results, total_time=5.0) - - assert summary["total_feeds"] == 3 - assert summary["successful_feeds"] == 2 - assert summary["failed_feeds"] == 1 - assert summary["total_articles"] == 15 - assert summary["total_time"] == 5.0 - assert summary["avg_fetch_time"] == 1.25 # (1.0 + 1.5) / 2 - - def test_generate_summary_all_failed(self): - """Should handle all failed feeds""" - fetcher = ParallelRSSFetcher() - - results = [ - FetchResult(1, "Feed1", False, 0, "Error 1", 1.0), - FetchResult(2, "Feed2", False, 0, "Error 2", 1.0), - ] - - summary = fetcher._generate_summary(results, total_time=2.0) - - assert summary["successful_feeds"] == 0 - assert summary["failed_feeds"] == 2 - assert summary["avg_fetch_time"] == 0.0 - - def test_generate_summary_empty_feeds(self): - """Should track empty feeds separately""" - fetcher = ParallelRSSFetcher() - - results = [ - FetchResult(1, "Feed1", True, 10, None, 1.0), - FetchResult(2, "EmptyFeed", True, 0, None, 1.0), - ] - - summary = fetcher._generate_summary(results, total_time=2.0) - - assert "EmptyFeed" in summary["empty_feeds"] - assert summary["successful_feeds"] == 2 - - def test_generate_summary_error_grouping(self): - """Should group errors by type""" - fetcher = ParallelRSSFetcher() - - results = [ - FetchResult(1, "Feed1", False, 0, "HTTP error: 404", 1.0), - FetchResult(2, "Feed2", False, 0, "HTTP error: 500", 1.0), - FetchResult(3, "Feed3", False, 0, "Timeout error", 1.0), - ] - - summary = fetcher._generate_summary(results, total_time=3.0) - - assert "HTTP error" in summary["error_summary"] - assert summary["error_summary"]["HTTP error"] == 2 - assert summary["error_summary"]["Timeout error"] == 1 - - -class TestEmptyResults: - """Tests for empty results structure""" - - def test_empty_results_structure(self): - """Should return correct empty results structure""" - fetcher = ParallelRSSFetcher() - - result = fetcher._empty_results() - - assert result["total_feeds"] == 0 - assert result["successful_feeds"] == 0 - assert result["failed_feeds"] == 0 - assert result["total_articles"] == 0 - assert result["total_time"] == 0.0 - assert result["avg_fetch_time"] == 0.0 - assert result["articles_per_second"] == 0.0 - assert result["feeds_per_second"] == 0.0 - assert result["error_summary"] == {} - assert result["empty_feeds"] == [] - assert result["failed_feeds_list"] == [] - assert "timestamp" in result - - -class TestFetchAllActiveFeeds: - """ - The convenience entry point refuses too (task 025, 2026-08-31). - - It is closed at the top rather than left to fail per-feed underneath: - ``_rate_limited_fetch`` catches every exception and folds it into the - summary dict, so a raise further down would return normally with zero - articles and a zero exit code -- indistinguishable from "the feeds were - quiet today", which is the silent failure this task removes. - """ - - @pytest.mark.asyncio - async def test_fetch_all_active_feeds_refuses(self): - with pytest.raises(LegacyWritePathClosed, match="legacy RSS write path is closed"): - await fetch_all_active_feeds() - - @pytest.mark.asyncio - async def test_it_refuses_before_reading_the_database(self): - """ - No session is opened, so there is nothing to mock away. - - The module no longer imports ``get_db`` at all, which is the strongest - available statement that this function cannot reach the database: the - old tests for it had to patch ``src.rss.parallel_fetcher.get_db``, and - that name is now absent. - """ - import src.rss.parallel_fetcher as module - - assert not hasattr(module, "get_db") - with pytest.raises(LegacyWritePathClosed): - await fetch_all_active_feeds(max_concurrent=5, rate_limit=1.0) - - @pytest.mark.asyncio - async def test_it_does_not_return_a_zero_article_summary(self): - """The failure mode being ruled out is returning normally.""" - try: - result = await fetch_all_active_feeds() - except LegacyWritePathClosed: - return - raise AssertionError(f"returned a summary instead of refusing: {result}") diff --git a/tests/sources/test_base.py b/tests/sources/test_base.py index d86b04e..6ea1946 100644 --- a/tests/sources/test_base.py +++ b/tests/sources/test_base.py @@ -81,7 +81,7 @@ def test_same_content_hashes_the_same(self): assert content_hash("Title", "Body") == content_hash("Title", "Body") def test_hash_ignores_punctuation_case_and_whitespace(self): - """Matches ArticleDeduplicator._normalize_text, so the two agree.""" + """The normalization every stored hash was computed with; it must not drift.""" assert content_hash("The Rule.") == content_hash("the rule") def test_different_content_hashes_differently(self): diff --git a/tests/sources/test_observation.py b/tests/sources/test_observation.py index ac17f21..c20efda 100644 --- a/tests/sources/test_observation.py +++ b/tests/sources/test_observation.py @@ -228,11 +228,11 @@ def test_only_the_observation_module_constructs_an_observation(self): The guarantee that observations are content-addressed is only as strong as the number of places that can write one, so the count is asserted - rather than trusted. src/database/models.py is excluded because that is + rather than trusted. The model module is excluded because that is where the class is defined. """ offenders = modules_constructing( - "Observation", {"sources/observation.py", "database/models.py"} + "Observation", {"sources/observation.py", "database/models/observations.py"} ) assert offenders == [], ( f"these modules construct an Observation directly: {offenders}. " @@ -248,7 +248,9 @@ def test_only_the_store_module_constructs_an_article(self): kept alive by its own tests, and it was deleted in task 025 rather than documented, because a documented hole in an invariant is still a hole. """ - offenders = modules_constructing("Article", {"sources/store.py", "database/models.py"}) + offenders = modules_constructing( + "Article", {"sources/store.py", "database/models/sources.py"} + ) assert offenders == [], ( f"these modules construct an Article directly: {offenders}. " f"Every article write goes through src/sources/store.py::store_items, " diff --git a/tests/sources/test_rss_adapter.py b/tests/sources/test_rss_adapter.py index e7509a0..25d230c 100644 --- a/tests/sources/test_rss_adapter.py +++ b/tests/sources/test_rss_adapter.py @@ -103,6 +103,37 @@ async def test_http_failure_raises_rather_than_returning_empty(self): assert "boom" in caught.value.reason +class TestNotAFeed: + @pytest.mark.parametrize( + "content", + [ + b"

Feed moved

", + b"xChecking your browser
", + b'{"error": "not found"}', + ], + ids=["well-formed html", "html5 page", "json"], + ) + async def test_a_page_that_is_not_a_feed_is_an_error_not_an_empty_result(self, content): + """ + A 200 that parses to no feed at all is unreachable in every sense that + matters: recorded as success it would clear the source's error and be + listed in the brief as a feed that ran and returned nothing + (2026-09-23, backlog task 031 review). + """ + fetcher = RSSFetcher() + with mock_get(fetcher, content), pytest.raises(SourceUnavailable, match="not a feed"): + await adapter_with(fetcher).fetch(datetime(2020, 1, 1)) + await fetcher.close() + + async def test_a_feed_with_parse_warnings_but_entries_is_still_a_feed(self): + broken = b"xg" + fetcher = RSSFetcher() + with mock_get(fetcher, broken): + items = await adapter_with(fetcher).fetch(datetime(2020, 1, 1)) + await fetcher.close() + assert [i.guid for i in items] == ["g"] + + class TestLifecycle: async def test_an_injected_fetcher_is_not_closed_by_the_adapter(self, sample_rss_response): """The caller owns what the caller made.""" diff --git a/tests/sources/test_runner.py b/tests/sources/test_runner.py index b524bc3..7f5123c 100644 --- a/tests/sources/test_runner.py +++ b/tests/sources/test_runner.py @@ -6,19 +6,21 @@ brief, and no error. """ +import asyncio +import json from datetime import datetime import pytest from src.database.models import Article, RSSFeed from src.sources.base import RawItem, SourceUnavailable +from src.sources.rss_adapter import RSSAdapter from src.sources.runner import ( ADAPTER_FACTORIES, AdapterRunSummary, IngestResult, build_configured_adapters, non_rss_adapter_names, - non_rss_source_urls, run_adapter, run_adapters, run_configured_adapters, @@ -132,6 +134,31 @@ async def test_failure_is_recorded_on_the_source_row(self, db_factory): assert row.last_error == "HTTP 503" assert row.error_count == 1 + async def test_an_empty_fetch_is_recorded_as_a_fetch(self, db_factory): + """ + Zero items from a reachable source is a fact about the window, and the + brief prints it as such; it needs the fetch stamp to do so, and an + earlier error is over once the source answers (2026-09-22, task 031). + """ + + def row(): + with db_factory() as db: + r = db.query(RSSFeed).filter(RSSFeed.url == FakeAdapter.source_url).one() + return r.last_fetched, r.last_error, r.error_count + + await run_adapter(FakeAdapter([]), SINCE, db_factory=db_factory) + stamped, error, count = row() + assert stamped is not None, "an empty fetch must stamp the row itself" + assert (error, count) == (None, 0) + + await run_adapter( + FakeAdapter(SourceUnavailable("Fake Source", "HTTP 503")), SINCE, db_factory=db_factory + ) + assert row()[1:] == ("HTTP 503", 1) + + await run_adapter(FakeAdapter([]), SINCE, db_factory=db_factory) + assert row()[1:] == (None, 0), "an answer, even an empty one, ends the error" + async def test_an_unexpected_adapter_bug_is_still_an_outage(self, db_factory): result = await run_adapter( FakeAdapter(ValueError("adapter bug")), SINCE, db_factory=db_factory @@ -204,13 +231,6 @@ def test_the_shipped_config_builds_its_adapters(self): def test_the_shipped_config_declares_the_federal_register_adapter(self): assert non_rss_adapter_names() == {"federal_register"} - def test_non_rss_urls_are_kept_away_from_the_rss_fetcher(self): - urls = non_rss_source_urls() - - assert "https://www.federalregister.gov/api/v1/documents.json" in urls - # The Federal Register RSS feed is still RSS and must not be excluded. - assert "https://www.federalregister.gov/documents/feeds/public-inspection.xml" not in urls - def test_every_declared_adapter_has_a_factory(self): assert non_rss_adapter_names() <= set(ADAPTER_FACTORIES) @@ -234,3 +254,126 @@ async def test_no_configured_adapters_is_an_empty_summary(self, tmp_path, db_fac assert summary.total_sources == 0 assert summary.alerts == [] + + +class ConcurrencyTracker: + """How many adapters were mid-``fetch`` at once, the high-water mark of it.""" + + def __init__(self) -> None: + self.current = 0 + self.max_seen = 0 + + def enter(self) -> None: + self.current += 1 + self.max_seen = max(self.max_seen, self.current) + + def exit(self) -> None: + self.current -= 1 + + +class TrackedAdapter: + """An adapter whose ``fetch`` reports into a shared :class:`ConcurrencyTracker`.""" + + category = "federal_policy" + + def __init__(self, name: str, tracker: ConcurrencyTracker): + self.name = name + self.source_url = f"https://example.gov/api/{name}" + self._tracker = tracker + + async def fetch(self, since): + self._tracker.enter() + try: + await asyncio.sleep(0.02) + finally: + self._tracker.exit() + return [item(self.name)] + + +class TestConcurrency: + async def test_bounded_concurrency_never_exceeds_the_limit(self, db_factory): + tracker = ConcurrencyTracker() + adapters = [TrackedAdapter(f"Source {i}", tracker) for i in range(10)] + + summary = await run_adapters(adapters, SINCE, db_factory=db_factory, concurrency=3) + + assert tracker.max_seen == 3 + assert [r.source for r in summary.results] == [a.name for a in adapters] + assert all(r.fetched == 1 for r in summary.results) + + async def test_default_concurrency_of_one_runs_strictly_sequentially(self, db_factory): + tracker = ConcurrencyTracker() + adapters = [TrackedAdapter(f"Source {i}", tracker) for i in range(10)] + + summary = await run_adapters(adapters, SINCE, db_factory=db_factory) + + assert tracker.max_seen == 1 + assert [r.source for r in summary.results] == [a.name for a in adapters] + + +class TestIncludeRss: + """``build_configured_adapters`` excludes RSS unless asked, then names it right.""" + + FEEDS = { + "feeds": [ + { + "name": "Regional News", + "url": "https://example.com/regional.rss", + "applicability": { + "scope": ["always"], + "geo_tags": ["usa"], + "domain_tags": ["general_news", "local"], + "specialty_tags": [], + }, + "relevance_score": 1.0, + }, + { + "name": "Federal Register - Documents API", + "url": "https://www.federalregister.gov/api/v1/documents.json", + "adapter": "federal_register", + "applicability": { + "scope": ["always"], + "geo_tags": ["usa"], + "domain_tags": ["federal_policy", "regulatory"], + "specialty_tags": ["cybersecurity", "compliance"], + }, + "relevance_score": 0.95, + }, + { + "name": "Untagged Feed", + "url": "https://example.com/untagged.rss", + "applicability": { + "scope": ["always"], + "geo_tags": ["usa"], + "specialty_tags": [], + }, + "relevance_score": 0.5, + }, + ] + } + + @pytest.fixture + def feeds_dir(self, tmp_path): + (tmp_path / "feeds.json").write_text(json.dumps(self.FEEDS), encoding="utf-8") + return tmp_path + + def test_rss_is_excluded_by_default(self, feeds_dir): + adapters = build_configured_adapters(feeds_dir) + + assert [a.name for a in adapters] == ["Federal Register - Documents API"] + + def test_include_rss_adds_an_rss_adapter_per_configured_feed(self, feeds_dir): + adapters = build_configured_adapters(feeds_dir, include_rss=True) + + rss_adapters = [a for a in adapters if isinstance(a, RSSAdapter)] + assert {a.name for a in rss_adapters} == {"Regional News", "Untagged Feed"} + + regional = next(a for a in rss_adapters if a.name == "Regional News") + assert regional.source_url == "https://example.com/regional.rss" + assert regional.category == "general_news" + + def test_an_rss_feed_with_no_domain_tags_gets_uncategorized(self, feeds_dir): + adapters = build_configured_adapters(feeds_dir, include_rss=True) + + untagged = next(a for a in adapters if a.name == "Untagged Feed") + assert untagged.category == "uncategorized" diff --git a/tests/test_docs.py b/tests/test_docs.py new file mode 100644 index 0000000..c6bab7f --- /dev/null +++ b/tests/test_docs.py @@ -0,0 +1,148 @@ +""" +The documentation names only things that exist. + +A public repository's README is read more often than its code, and a command, +option, make target or path that the docs name and the tree lacks is a lie +the reader finds first. Every `insightweaver ...` invocation, every `make ...` +target and every backticked repository path in the documents below is checked +against the click group, the Makefile and the file system. + +Added 2026-09-23 for backlog tasks 032 and 033. +""" + +from __future__ import annotations + +import re +from pathlib import Path + +import click +import pytest + +from src.cli.app import cli + +ROOT = Path(__file__).resolve().parent.parent +DOCUMENTS = [ + "README.md", + "GETTING_STARTED.md", + "CONTRIBUTING.md", + "docs/CONCEPTS.md", + "docs/PLAN.md", + "SOURCES.md", + *sorted(str(p.relative_to(ROOT)) for p in (ROOT / ".claude" / "skills").glob("*/SKILL.md")), +] + +# `insightweaver` followed by words and options up to the end of the line or a +# closing backtick, pipe or quote. The text between is parsed as a command. +_INVOCATION = re.compile( + r"insightweaver\s+([a-z][a-z0-9 ._/-]*(?:\s+--?[a-z][a-z0-9-]*(?:[ =][^\s`|\"')]+)?)*)" +) +# `make x` in a code span or a code block; "make the" in prose is not a target. +_MAKE = re.compile(r"(?:`|^\s*)make\s+([a-z][a-z0-9-]*)", re.MULTILINE) +# Paths in the tree. `data/` is runtime output and is gitignored, so it is not checked. +_PATH = re.compile( + r"`((?:(?:src|tests|config|docs|backlog|\.claude|\.github)/[^`\s]+)" + r"|(?:Makefile|pyproject\.toml|[A-Z_]+\.md|requirements[a-z-]*\.txt|\.env\.example|\.pre-commit-config\.yaml))`" +) +# docs/PLAN.md lists what task 027 deleted, by path, on purpose. +_PATHS_CHECKED = [d for d in DOCUMENTS if d != "docs/PLAN.md"] +_OPTION = re.compile(r"^--?[a-z]") + + +def _read(name: str) -> str: + return (ROOT / name).read_text(encoding="utf-8") + + +def _resolve(tokens: list[str]) -> tuple[click.Command, list[str]]: + """Walk the group tree; return the command reached and the leftover tokens.""" + command: click.Command = cli + while tokens and isinstance(command, click.Group): + sub = command.commands.get(tokens[0]) + if sub is None: + break + command = sub + tokens = tokens[1:] + return command, tokens + + +def _options(command: click.Command) -> set[str]: + names = {opt for param in command.params for opt in param.opts} + names |= {opt for param in cli.params for opt in param.opts} # group options such as --debug + return names | {"--help"} + + +def _invocations(text: str) -> list[tuple[str, list[str]]]: + found = [] + for match in _INVOCATION.finditer(text): + tokens = match.group(1).split() + if tokens[0] in ("is", "now", "exposes", "run,", "on"): # prose, not a command + continue + found.append((match.group(0), tokens)) + return found + + +@pytest.mark.parametrize("document", DOCUMENTS) +def test_every_named_command_and_option_exists(document): + problems = [] + for literal, tokens in _invocations(_read(document)): + command, rest = _resolve(tokens) + if command is cli: + problems.append(f"{literal!r}: {tokens[0]!r} is not a command") + continue + if isinstance(command, click.Group) and rest and not _OPTION.match(rest[0]): + problems.append(f"{literal!r}: {rest[0]!r} is not a subcommand of {command.name}") + continue + for token in rest: + if _OPTION.match(token) and token.split("=")[0] not in _options(command): + problems.append(f"{literal!r}: {command.name} has no option {token}") + assert problems == [], "\n".join(problems) + + +@pytest.mark.parametrize("document", DOCUMENTS) +def test_every_named_make_target_exists(document): + targets = set(re.findall(r"^([a-z][a-z0-9-]*):", _read("Makefile"), re.MULTILINE)) + named = set(_MAKE.findall(_read(document))) + assert named <= targets, f"{document} names make targets that do not exist: {named - targets}" + + +@pytest.mark.parametrize("document", _PATHS_CHECKED) +def test_every_named_repository_path_exists(document): + missing = [] + for path in _PATH.findall(_read(document)): + if any(ch in path for ch in "*<>{}") or path.endswith("/..."): + continue + candidate = ROOT / path.split("::")[0].rstrip("/") + if not candidate.exists(): + missing.append(path) + assert missing == [], f"{document} names paths that do not exist: {missing}" + + +def test_the_onboarding_skill_transcribes_and_syncs(): + """Invariant 6 at the seam where it is easiest to break (backlog task 032).""" + text = _read(".claude/skills/onboard/SKILL.md") + assert text.startswith("---\nname: onboard\n") + assert "insightweaver watch sync" in text + assert "watch add" not in text.replace("`watch add`", "") # named only as what does not exist + assert "never fill a field yourself" in text + + +def _table_rows() -> list[str]: + readme = _read("README.md") + table = readme[readme.index("## Commands") : readme.index("## Sources")] + return [line.split("`")[1] for line in table.splitlines() if line.startswith("| `")] + + +def test_the_commands_table_in_the_readme_matches_the_cli(): + """Every command the group registers is in the README's commands table, and no other.""" + assert {row.split()[0] for row in _table_rows()} == set(cli.commands) + + +def test_every_option_in_the_commands_table_exists(): + """`brief [--since] [--as-of]` style rows: each bracketed option belongs to that command.""" + problems = [] + for row in _table_rows(): + tokens = row.replace("[", " ").replace("]", " ").replace("/", " ").split() + command, rest = _resolve(tokens) + for token in rest: + if _OPTION.match(token) and token not in _options(command): + problems.append(f"{row!r}: {command.name} has no option {token}") + assert problems == [], "\n".join(problems) diff --git a/tests/test_invariants.py b/tests/test_invariants.py new file mode 100644 index 0000000..ae49d91 --- /dev/null +++ b/tests/test_invariants.py @@ -0,0 +1,59 @@ +""" +Two of the six invariants that are properties of the tree rather than of a +run, pinned by scanning the tree (2026-09-23, backlog task 033). + +1. Nothing sends. The only modules that open an outbound connection are the + two fetchers and the model client, and nothing listens, mails or posts. +3. Evidence is deleted by ``replay --commit`` and nothing else. + +Like ``tests/test_reachability.py`` these match tokens, not behaviour; they +are guards against habit, and a new fetcher or a new delete is added to the +allowlist here in the same change that adds it, with its reason. +""" + +from __future__ import annotations + +import re +from pathlib import Path + +SRC = Path(__file__).resolve().parent.parent / "src" + +# Modules allowed to import an HTTP client. The model API is reached through +# the anthropic SDK, which owns its own transport, so src/llm/ is not here. +OUTBOUND = {"sources/federal_register.py", "rss/fetcher.py"} + +# Anything that would send, serve or listen. A hit is a design change. +FORBIDDEN_IMPORTS = re.compile( + r"^\s*(?:import|from)\s+(smtplib|socketserver|http\.server|socket|asyncio\.streams|" + r"flask|fastapi|uvicorn|aiohttp|websockets|requests)\b", + re.MULTILINE, +) +HTTP_CLIENT_IMPORT = re.compile(r"^\s*(?:import|from)\s+httpx\b", re.MULTILINE) +# A query over Evidence that ends in .delete(, across the lines a formatter +# spreads it over, or a core delete(Evidence) statement. +EVIDENCE_DELETE = re.compile(r"query\(Evidence\)[\s\S]{0,500}?\.delete\(|delete\(Evidence\b") + + +def _sources() -> dict[str, str]: + return { + str(p.relative_to(SRC)): p.read_text(encoding="utf-8") for p in sorted(SRC.rglob("*.py")) + } + + +def test_nothing_sends_serves_or_listens(): + offenders = [ + f"{name}: {match.group(1)}" + for name, text in _sources().items() + for match in FORBIDDEN_IMPORTS.finditer(text) + ] + assert offenders == [], f"a module imports something that sends or listens: {offenders}" + + +def test_only_the_two_fetchers_open_an_http_client(): + with_client = {name for name, text in _sources().items() if HTTP_CLIENT_IMPORT.search(text)} + assert with_client == OUTBOUND + + +def test_only_replay_deletes_evidence(): + deleters = {name for name, text in _sources().items() if EVIDENCE_DELETE.search(text)} + assert deleters == {"evidence/replay.py"} diff --git a/tests/test_reachability.py b/tests/test_reachability.py new file mode 100644 index 0000000..82f8f68 --- /dev/null +++ b/tests/test_reachability.py @@ -0,0 +1,95 @@ +""" +Every module under ``src/`` is reachable from a command or a migration. + +This is what keeps the 2026-09-22 sweep (backlog task 027) from recurring: a +module nothing imports fails the suite at the pull request, not a month +later. The walk is static -- ``ast`` over every file, absolute ``src.x.y`` +and relative imports resolved against the importing package -- so nothing is +executed and no allowlist exists. When the sweep first built this test it +found fourteen modules unreachable, the whole source, routing and model +stack, because no command wired them in; task 029 wired the last of them. + +If a module is legitimately unreachable, the fix is to give it a caller or +delete it, not to exempt it here. +""" + +import ast +from pathlib import Path + +SRC = Path(__file__).resolve().parents[1] / "src" +ROOTS = ("src.cli.app",) + + +def _module_name(path: Path) -> str: + rel = path.relative_to(SRC.parent).with_suffix("") + parts = list(rel.parts) + if parts[-1] == "__init__": + parts = parts[:-1] + return ".".join(parts) + + +def _all_modules() -> dict[str, Path]: + return {_module_name(p): p for p in SRC.rglob("*.py")} + + +def _resolve_relative(importer: str, is_package: bool, level: int, module: str | None) -> str: + base = importer.split(".") + if not is_package: + base = base[:-1] + if level > 1: + base = base[: len(base) - (level - 1)] + return ".".join(base + ([module] if module else [])) + + +def _imports(name: str, path: Path, known: set[str]) -> set[str]: + tree = ast.parse(path.read_text(encoding="utf-8")) + is_package = path.name == "__init__.py" + found: set[str] = set() + for node in ast.walk(tree): + if isinstance(node, ast.Import): + for alias in node.names: + if alias.name.startswith("src."): + found.add(alias.name) + elif isinstance(node, ast.ImportFrom): + if node.level: + target = _resolve_relative(name, is_package, node.level, node.module) + else: + target = node.module or "" + if not target.startswith("src"): + continue + found.add(target) + # `from pkg import name` may name a submodule rather than an attribute. + for alias in node.names: + candidate = f"{target}.{alias.name}" + if candidate in known: + found.add(candidate) + return {m for m in found if m in known} + + +def _reachable(modules: dict[str, Path], roots: tuple[str, ...]) -> set[str]: + seen: set[str] = set() + frontier = list(roots) + while frontier: + name = frontier.pop() + if name in seen or name not in modules: + continue + seen.add(name) + # Importing a submodule imports every package above it. + parts = name.split(".") + for i in range(1, len(parts)): + frontier.append(".".join(parts[:i])) + frontier.extend(_imports(name, modules[name], set(modules))) + return seen + + +def test_every_module_under_src_is_reachable_from_a_command_or_a_migration(): + modules = _all_modules() + migrations = tuple(m for m in modules if m.startswith("src.database.migrations.")) + reachable = _reachable(modules, ROOTS + migrations) + + unreachable = sorted(m for m in modules if m not in reachable and not m.endswith("__init__")) + unreachable = [m for m in unreachable if modules[m].name != "__init__.py"] + assert unreachable == [], ( + "these modules are reachable from no command and no migration; give each a caller " + f"or delete it: {unreachable}" + ) diff --git a/tests/utils/conftest.py b/tests/utils/conftest.py deleted file mode 100644 index 15df907..0000000 --- a/tests/utils/conftest.py +++ /dev/null @@ -1,82 +0,0 @@ -""" -Utils-specific test fixtures -""" - -import json - -import pytest - - -@pytest.fixture -def valid_user_profile(): - """Valid user profile data for testing""" - return { - "geographic_context": { - "primary_location": { - "city": "Fairfax", - "county": "Fairfax County", - "state": "Virginia", - "region": "Northern Virginia", - "country": "USA", - }, - "secondary_locations": [], - }, - "professional_context": { - "professional_domains": ["cybersecurity", "software development"], - "industry": "technology", - "role": "engineer", - }, - "civic_interests": { - "policy_areas": ["education", "housing"], - "engagement_level": "medium", - }, - "personal_priorities": { - "topics": ["AI", "security"], - "time_horizon": "medium", - }, - "content_preferences": { - "excluded_topics": ["sports", "entertainment"], - "preferred_sources": [], - }, - } - - -@pytest.fixture -def profile_missing_section(): - """Profile missing required section""" - return { - "geographic_context": { - "primary_location": {"city": "Test", "state": "VA"}, - }, - "professional_context": { - "professional_domains": ["test"], - }, - # Missing: civic_interests, personal_priorities, content_preferences - } - - -@pytest.fixture -def profile_missing_field(): - """Profile missing required field within a section""" - return { - "geographic_context": { - # Missing: primary_location - }, - "professional_context": { - "professional_domains": ["test"], - }, - "civic_interests": {}, - "personal_priorities": {}, - "content_preferences": { - "excluded_topics": [], - }, - } - - -@pytest.fixture -def temp_profile_file(tmp_path, valid_user_profile): - """Create a temporary profile file for testing""" - profile_path = tmp_path / "user_profile.json" - with open(profile_path, "w") as f: - json.dump(valid_user_profile, f) - return profile_path diff --git a/tests/utils/test_profile_loader.py b/tests/utils/test_profile_loader.py deleted file mode 100644 index e0875b2..0000000 --- a/tests/utils/test_profile_loader.py +++ /dev/null @@ -1,162 +0,0 @@ -""" -Tests for user profile loader -""" - -import json - -import pytest - -from src.utils.profile_loader import ProfileValidationError, UserProfile - - -class TestUserProfileInit: - """Tests for UserProfile initialization""" - - def test_init_with_custom_path(self, tmp_path): - """Should accept custom profile path""" - custom_path = tmp_path / "custom_profile.json" - profile = UserProfile(profile_path=str(custom_path)) - - assert profile.profile_path == custom_path - - def test_init_with_default_path(self): - """Should use default path when none provided""" - profile = UserProfile() - - assert "user_profile.json" in str(profile.profile_path) - assert "config" in str(profile.profile_path) - - -class TestLoadProfile: - """Tests for profile loading""" - - def test_load_valid_profile(self, temp_profile_file, valid_user_profile): - """Should load valid profile successfully""" - profile = UserProfile(profile_path=str(temp_profile_file)) - result = profile.load_profile() - - assert result is not None - assert "geographic_context" in result - assert "professional_context" in result - - def test_load_nonexistent_file_raises(self, tmp_path): - """Should raise FileNotFoundError for missing file""" - nonexistent = tmp_path / "nonexistent.json" - profile = UserProfile(profile_path=str(nonexistent)) - - with pytest.raises(FileNotFoundError): - profile.load_profile() - - def test_load_invalid_json_raises(self, tmp_path): - """Should raise JSONDecodeError for invalid JSON""" - bad_json = tmp_path / "bad.json" - with open(bad_json, "w") as f: - f.write("{invalid json") - - profile = UserProfile(profile_path=str(bad_json)) - - with pytest.raises(json.JSONDecodeError): - profile.load_profile() - - -class TestProfileValidation: - """Tests for profile validation""" - - def test_validate_missing_section_raises(self, tmp_path, profile_missing_section): - """Should raise ProfileValidationError for missing sections""" - profile_path = tmp_path / "profile.json" - with open(profile_path, "w") as f: - json.dump(profile_missing_section, f) - - profile = UserProfile(profile_path=str(profile_path)) - - with pytest.raises(ProfileValidationError) as exc_info: - profile.load_profile() - - assert "missing required sections" in str(exc_info.value) - - def test_validate_missing_field_raises(self, tmp_path, profile_missing_field): - """Should raise ProfileValidationError for missing fields""" - profile_path = tmp_path / "profile.json" - with open(profile_path, "w") as f: - json.dump(profile_missing_field, f) - - profile = UserProfile(profile_path=str(profile_path)) - - with pytest.raises(ProfileValidationError) as exc_info: - profile.load_profile() - - assert "missing required fields" in str(exc_info.value) - - -class TestRequiredSections: - """Tests for required sections constant""" - - def test_required_sections_defined(self): - """Should have required sections defined""" - assert hasattr(UserProfile, "REQUIRED_SECTIONS") - assert isinstance(UserProfile.REQUIRED_SECTIONS, set) - - def test_required_sections_contents(self): - """Should include expected sections""" - expected = { - "geographic_context", - "professional_context", - "civic_interests", - "personal_priorities", - "content_preferences", - } - assert expected == UserProfile.REQUIRED_SECTIONS - - -class TestRequiredFields: - """Tests for required fields constant""" - - def test_required_fields_defined(self): - """Should have required fields defined""" - assert hasattr(UserProfile, "REQUIRED_FIELDS") - assert isinstance(UserProfile.REQUIRED_FIELDS, dict) - - def test_geographic_context_required_fields(self): - """Geographic context should require primary_location""" - assert "geographic_context" in UserProfile.REQUIRED_FIELDS - assert "primary_location" in UserProfile.REQUIRED_FIELDS["geographic_context"] - - def test_professional_context_required_fields(self): - """Professional context should require professional_domains""" - assert "professional_context" in UserProfile.REQUIRED_FIELDS - assert "professional_domains" in UserProfile.REQUIRED_FIELDS["professional_context"] - - def test_content_preferences_required_fields(self): - """Content preferences should require excluded_topics""" - assert "content_preferences" in UserProfile.REQUIRED_FIELDS - assert "excluded_topics" in UserProfile.REQUIRED_FIELDS["content_preferences"] - - -class TestProfileProperty: - """Tests for profile property access""" - - def test_profile_property(self, temp_profile_file, valid_user_profile): - """Should access profile data after loading""" - profile = UserProfile(profile_path=str(temp_profile_file)) - profile.load_profile() - - # After loading, profile data should be accessible - assert profile._profile_data is not None - assert profile._profile_data["geographic_context"]["primary_location"]["city"] == "Fairfax" - - -class TestProfileValidationError: - """Tests for ProfileValidationError""" - - def test_is_exception(self): - """Should be an Exception subclass""" - error = ProfileValidationError("Test error") - - assert isinstance(error, Exception) - - def test_message(self): - """Should store message""" - error = ProfileValidationError("Missing fields") - - assert str(error) == "Missing fields"