zettelforge 2.5.1__tar.gz → 2.5.2__tar.gz

{zettelforge-2.5.1 → zettelforge-2.5.2}/CHANGELOG.md

@@ -6,6 +6,83 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [2.5.2] - 2026-04-25
+
+Hotfix release. Restores end-to-end functionality of synthesis, causal
+triple extraction, fact extraction, LLM NER, and neighbor evolution
+under any reasoning-style LLM (qwen3.5+, qwen3.6, nemotron-3, etc.).
+
+### Fixed
+
+- **Reasoning-model token starvation across every LLM call site**.
+  Reasoning models emit hidden `<think>...</think>` tokens that count
+  against `num_predict` but never appear in the final `response` field
+  Ollama returns. Pre-2.5.2 token caps (`max_tokens=300`/`400`/`800`/
+  `1024`) were exhausted entirely by the thinking phase on these
+  models, leaving the JSON answer empty. Symptoms: synthesis fell back
+  to `"No specific answer found for: …"` on every query; causal triple
+  extraction persisted **0 edges** despite rich CTI text; LLM NER
+  silently no-opped; neighbor evolution `parse_failed{schema=...,
+  raw=""}` warnings flooded the log.
+
+  Bumped every `generate(..., max_tokens=...)` call site to give
+  reasoning models room to think *and* emit a final answer. Affected
+  files:
+
+  | File | Old cap | New cap |
+  |---|---|---|
+  | `note_constructor.py` (causal triples) | 300 | **8000** |
+  | `synthesis_generator.py` | 800 | 2500 |
+  | `fact_extractor.py` | 400 | 2500 |
+  | `entity_indexer.py` (NER) | 300 | 2500 |
+  | `memory_evolver.py` (2 sites) | 1024 | 2500 |
+
+  Causal extraction needs the largest budget because the prompt asks
+  the model to enumerate *every* causal relation in a passage; this
+  triggers the longest reasoning chains anywhere in the system.
+  Empirical against `qwen3.5:9b`: at 4000 tokens the call was
+  *stochastically* sufficient (eval_count varied 2.8k–4k+, ~70%
+  success), so 8000 is the conservative cap that keeps the success
+  rate above 95% on the same model. Other call sites converge with
+  less reasoning overhead so 2500 suffices.
+
+- **LLM client timeout bumped 60s → 180s**. `LLMConfig.timeout` and
+  `OllamaProvider` constructor default were both 60 seconds — well
+  below the 60–120s wall-clock time of a 4000–8000 token reasoning
+  generation on a 9B-Q4_K_M model. `ReadTimeout` was firing during
+  causal extraction even when the model would have returned valid
+  JSON given another 30 seconds. Bumped both defaults plus
+  `config.default.yaml` to 180s.
+
+  Verified end-to-end on `qwen3.5:9b`:
+  - Synthesis: query "What CVE does DROPBEAR exploit?" returns
+    `"CVE-2024-3094"` with 1 source citation (was returning
+    `"No specific answer found for: …"` on every call pre-2.5.2).
+  - Causal extraction: corpus seeded with APT28/DROPBEAR/CVE-2024-3094
+    text yields a 4-triple JSON array in 137s wall time:
+    `APT28 → targets → manufacturing sector`,
+    `APT28 → uses → DROPBEAR`,
+    `DROPBEAR → exploits → CVE-2024-3094`,
+    `APT28 → attributed_to → Russian GRU Unit 26165`.
+
+### Operational note
+
+Slow models. With 8000 tokens of reasoning budget, single causal
+extraction calls now take 60–140s on a 9B model. `remember(sync=True)`
+in this configuration will block 1–3 minutes per note. The default
+async path (background enrichment queue) is the preferred mode.
+Operators on faster hardware or smaller models can lower the caps via
+config/env if needed, but the v2.5.2 defaults trade latency for
+end-to-end correctness on the reference model.
+
+### Notes
+
+This explains the `evolution_parse_failed` and `causal_triples
+parse_failed` cascades documented in the v2.4.x Vigil incident. The
+v2.4.2 PR #95 Tier 1/2 LLM observability surfaced the empty responses
+but the root-cause attribution to token-cap-vs-thinking-budget waited
+until the v2.5.1 perf-bench run made the failure reproducible end-to-end.
+
 ## [2.5.1] - 2026-04-25
 
 Hotfix release. Surfaced during the v2.5.0 perf benchmark run.

{zettelforge-2.5.1 → zettelforge-2.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zettelforge
-Version: 2.5.1
+Version: 2.5.2
 Summary: ZettelForge: Agentic Memory System with vector search, knowledge graph, and synthesis
 Project-URL: Homepage, https://github.com/rolandpg/zettelforge
 Project-URL: Documentation, https://docs.threatrecall.ai

{zettelforge-2.5.1 → zettelforge-2.5.2}/config.default.yaml

@@ -214,7 +214,7 @@ llm:
   url: http://localhost:11434
   api_key: ""
   temperature: 0.1
-  timeout: 60.0
+  timeout: 180.0  # v2.5.2: bumped from 60s for reasoning-model headroom
   max_retries: 2
   fallback: ""
   local_backend: llama-cpp-python  # used when provider=local (RFC-011)

{zettelforge-2.5.1 → zettelforge-2.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "zettelforge"
-version = "2.5.1"
+version = "2.5.2"
 description = "ZettelForge: Agentic Memory System with vector search, knowledge graph, and synthesis"
 readme = "README.md"
 license = "MIT"

{zettelforge-2.5.1 → zettelforge-2.5.2}/src/zettelforge/__init__.py

@@ -57,7 +57,7 @@ from zettelforge.vector_retriever import VectorRetriever
 # importable for advanced use but are not part of the advertised public API
 # and are therefore excluded from __all__ below.
 
-__version__ = "2.5.1"
+__version__ = "2.5.2"
 __all__ = [
     # Ontology reference tables (TypedEntityStore / OntologyValidator are
     # importable from zettelforge.ontology but are not part of the public API

{zettelforge-2.5.1 → zettelforge-2.5.2}/src/zettelforge/config.py

@@ -103,7 +103,7 @@ class LLMConfig:
     url: str = "http://localhost:11434"
     api_key: str = ""  # supports ${ENV_VAR} references — never commit raw keys
     temperature: float = 0.1
-    timeout: float = 60.0
+    timeout: float = 180.0  # v2.5.2: bumped from 60s — reasoning models at higher num_predict (4000 for causal triples) routinely exceed 60s on a 9B at Q4_K_M
     max_retries: int = 2
     fallback: str = ""  # empty preserves implicit local→ollama fallback
     local_backend: str = "llama-cpp-python"  # RFC-011: "llama-cpp-python" or "onnxruntime-genai"

{zettelforge-2.5.1 → zettelforge-2.5.2}/src/zettelforge/entity_indexer.py

@@ -271,9 +271,12 @@ class EntityExtractor:
             from zettelforge.llm_client import generate
 
             prompt = f"Extract named entities from this text:\n\n{text[:2000]}\n\nJSON:"
+            # 2500-token budget for reasoning-model headroom (v2.5.2; pre-fix
+            # 300 was exhausted by qwen3.5+ <think> tokens, leaving the NER
+            # JSON empty and entity extraction silently no-opping).
             output = generate(
                 prompt,
-                max_tokens=300,
+                max_tokens=2500,
                 temperature=0.0,
                 system=self.NER_SYSTEM_PROMPT,
             )
@@ -282,7 +285,7 @@ class EntityExtractor:
             if parsed is None and output and output.strip():
                 _logger.info("retry_parse", site="entity_indexer_ner", attempt=2)
                 retry_prompt = prompt + "\n\nRespond with valid JSON only."
-                output = generate(retry_prompt, max_tokens=300, temperature=0.3, json_mode=True)
+                output = generate(retry_prompt, max_tokens=2500, temperature=0.3, json_mode=True)
                 parsed = extract_json(output, expect="object")
             return self._parse_ner_output_from_parsed(parsed, output, conversational_types)
 

{zettelforge-2.5.1 → zettelforge-2.5.2}/src/zettelforge/fact_extractor.py

@@ -42,7 +42,9 @@ class FactExtractor:
         try:
             from zettelforge.llm_client import generate
 
-            raw_output = generate(prompt, max_tokens=400, temperature=0.1)
+            # 2500-token budget for reasoning-model headroom (see v2.5.2
+            # CHANGELOG; pre-fix 400 was exhausted by qwen3.5+ <think> tokens).
+            raw_output = generate(prompt, max_tokens=2500, temperature=0.1)
             return self._parse_extraction_response(raw_output)
         except Exception:
             _logger.warning("llm_fact_extraction_failed", exc_info=True)

{zettelforge-2.5.1 → zettelforge-2.5.2}/src/zettelforge/llm_providers/ollama_provider.py

@@ -39,7 +39,7 @@ class OllamaProvider:
         self,
         model: str = "",
         url: str = "",
-        timeout: float = 60.0,
+        timeout: float = 180.0,  # see config.LLMConfig.timeout for rationale
         **_: Any,
     ) -> None:
         self._model = model or _DEFAULT_MODEL

{zettelforge-2.5.1 → zettelforge-2.5.2}/src/zettelforge/memory_evolver.py

@@ -93,7 +93,7 @@ class MemoryEvolver:
         )
 
         # First attempt
-        output = generate(prompt, max_tokens=1024, temperature=0.2, json_mode=True)
+        output = generate(prompt, max_tokens=2500, temperature=0.2, json_mode=True)
         result = extract_json(output, expect="object")
 
         # Single retry on parse failure (AD-2). Capture what the model
@@ -108,7 +108,7 @@ class MemoryEvolver:
                 raw_chars=len(output or ""),
                 prompt_preview=prompt[:240],
             )
-            output = generate(prompt, max_tokens=1024, temperature=0.1, json_mode=True)
+            output = generate(prompt, max_tokens=2500, temperature=0.1, json_mode=True)
             result = extract_json(output, expect="object")
 
         if result is None:

{zettelforge-2.5.1 → zettelforge-2.5.2}/src/zettelforge/note_constructor.py

@@ -122,7 +122,15 @@ JSON:"""
         try:
             from zettelforge.llm_client import generate
 
-            output = generate(prompt, max_tokens=300, temperature=0.1)
+            # 8000 tokens for causal extraction — the highest cap in the
+            # codebase. This prompt asks the model to enumerate every causal
+            # relation in a passage, which triggers the longest reasoning
+            # chains anywhere in the system. Empirical: qwen3.5:9b at
+            # num_predict=4000 was *stochastically* sufficient (~70% success
+            # rate), eval_count varied between 2.8k (success) and 4k+ (still
+            # in <think> tags when budget exhausted). 8000 keeps the
+            # success rate >95% on the same model. v2.5.2 CHANGELOG.
+            output = generate(prompt, max_tokens=8000, temperature=0.1)
 
             parsed = extract_json(output, expect="array")
             if parsed is None:

{zettelforge-2.5.1 → zettelforge-2.5.2}/src/zettelforge/synthesis_generator.py

@@ -143,7 +143,11 @@ class SynthesisGenerator:
         try:
             from zettelforge.llm_client import generate
 
-            raw = generate(full_prompt, max_tokens=800, temperature=0.1, system=system_prompt)
+            # 2500-token budget for reasoning-model headroom. Pre-2.5.2 the
+            # 800-token cap was exhausted by qwen3.5+/qwen3.6/nemotron-3
+            # <think> tokens before any JSON answer was emitted, dropping
+            # synthesis to its empty-result fallback on every call.
+            raw = generate(full_prompt, max_tokens=2500, temperature=0.1, system=system_prompt)
             result = extract_json(raw, expect="object")
             if result is None:
                 _logger.warning("parse_failed", schema="synthesis", raw=(raw or "")[:200])