thoughtflow 0.2.4__tar.gz → 0.2.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/CHANGELOG.md +23 -5
  2. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/PKG-INFO +87 -24
  3. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/README.md +86 -23
  4. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/pyproject.toml +1 -1
  5. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/__init__.py +1 -1
  6. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/_util.py +65 -0
  7. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/memory.py +173 -35
  8. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/thought.py +232 -62
  9. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/thoughts/plan.py +39 -7
  10. thoughtflow-0.2.5/tests/unit/test_foundation_agent_response.py +615 -0
  11. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_memory.py +189 -0
  12. thoughtflow-0.2.5/tests/unit/test_reference_plan_loop.py +406 -0
  13. thoughtflow-0.2.4/tests/unit/test_foundation_agent_response.py +0 -240
  14. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/.gitignore +0 -0
  15. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/LICENSE +0 -0
  16. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/_cron_expr.py +0 -0
  17. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/action.py +0 -0
  18. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/__init__.py +0 -0
  19. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/_http.py +0 -0
  20. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/_substitution.py +0 -0
  21. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/ask.py +0 -0
  22. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/call.py +0 -0
  23. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/fetch.py +0 -0
  24. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/noop.py +0 -0
  25. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/notify.py +0 -0
  26. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/post.py +0 -0
  27. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/read_file.py +0 -0
  28. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/run.py +0 -0
  29. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/say.py +0 -0
  30. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/scrape.py +0 -0
  31. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/search.py +0 -0
  32. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/sleep.py +0 -0
  33. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/wait.py +0 -0
  34. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/actions/write_file.py +0 -0
  35. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/agent.py +0 -0
  36. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/agents/__init__.py +0 -0
  37. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/agents/planact.py +0 -0
  38. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/agents/react.py +0 -0
  39. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/agents/reflect.py +0 -0
  40. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/chat.py +0 -0
  41. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/chron.py +0 -0
  42. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/delegate.py +0 -0
  43. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/embed.py +0 -0
  44. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/eval/__init__.py +0 -0
  45. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/eval/harness.py +0 -0
  46. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/llm.py +0 -0
  47. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/llm_cache.py +0 -0
  48. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/llm_params.py +0 -0
  49. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/mcp.py +0 -0
  50. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/message.py +0 -0
  51. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/providers/README.md +0 -0
  52. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/providers/__init__.py +0 -0
  53. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/providers/cerebras.py +0 -0
  54. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/providers/groq.py +0 -0
  55. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/providers/openrouter.py +0 -0
  56. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/py.typed +0 -0
  57. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/this.py +0 -0
  58. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/thoughts/__init__.py +0 -0
  59. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/thoughts/decide.py +0 -0
  60. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/tool.py +0 -0
  61. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/src/thoughtflow/workflow.py +0 -0
  62. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/__init__.py +0 -0
  63. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/conftest.py +0 -0
  64. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/integration/__init__.py +0 -0
  65. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/integration/smoke_helpers.py +0 -0
  66. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/integration/test_chron.py +0 -0
  67. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/integration/test_embed_providers.py +0 -0
  68. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/integration/test_llm_providers.py +0 -0
  69. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/integration/test_scrape.py +0 -0
  70. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/integration/test_search_providers.py +0 -0
  71. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/__init__.py +0 -0
  72. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_action.py +0 -0
  73. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_actions.py +0 -0
  74. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_agent.py +0 -0
  75. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_chat.py +0 -0
  76. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_chron.py +0 -0
  77. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_delegate.py +0 -0
  78. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_embed.py +0 -0
  79. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_eval.py +0 -0
  80. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_llm.py +0 -0
  81. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_llm_provider_integration.py +0 -0
  82. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_mcp.py +0 -0
  83. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_message.py +0 -0
  84. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_replay.py +0 -0
  85. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_this.py +0 -0
  86. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_thought.py +0 -0
  87. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_tool.py +0 -0
  88. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_util.py +0 -0
  89. {thoughtflow-0.2.4 → thoughtflow-0.2.5}/tests/unit/test_workflow.py +0 -0
@@ -5,6 +5,27 @@ All notable changes to ThoughtFlow will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [Unreleased]
9
+
10
+ ## [0.2.5] - 2026-07-17
11
+
12
+ Foundation Agent loop response: lifecycle emits on MEMORY, THOUGHT prompt/history improvements, PLAN normalization fix, and a copy-and-edit plan-commit-reflect reference recipe.
13
+
14
+ ### Added
15
+ - `MEMORY.emit()` and `get_emits()` for JSON-safe, typed lifecycle and evaluation events
16
+ - THOUGHT `template_mode='substitute'` for exact `{key}` replacement in JSON-heavy prompts
17
+ - THOUGHT `include_history=False` for requests containing only the configured system and user prompts
18
+ - Executable plan-commit-reflect reference recipe with receipts, bounded loops, step-result resolution, lifecycle events, sub-run isolation, and CHRON adapter guidance
19
+
20
+ ### Changed
21
+ - THOUGHT now builds included history through `MEMORY.get_llm_msgs()` and no longer applies bare substring replacement to historical message content
22
+ - THOUGHT prompt context now exposes each MEMORY variable's latest value instead of its internal event history
23
+ - Dict-shaped prompt sections retain their previous format-mode behavior and support exact placeholder rendering in substitute mode
24
+ - README aligned with current capabilities (lifecycle emits, RAG augments, THOUGHT rendering options)
25
+
26
+ ### Fixed
27
+ - PLAN now validates, returns, and stores the same value produced by `normalize_plan()`, including across validation retries
28
+
8
29
  ## [0.2.4] - 2026-07-11
9
30
 
10
31
  ### Fixed
@@ -49,10 +70,6 @@ Production-hardening release: THOUGHT/PLAN parsing improvements (Foundation Agen
49
70
  - EMBED Groq calls include User-Agent (Cloudflare HTTP 1010 without it)
50
71
  - EMBED `text-embedding-004` aliases to `gemini-embedding-001`; `last_error` surfaced on failures
51
72
 
52
- ## [Unreleased]
53
-
54
- _Nothing yet._
55
-
56
73
  ---
57
74
 
58
75
  ## [0.2.0] - 2026-06-10
@@ -208,7 +225,8 @@ grown from MEMORY itself, with zero new concepts.
208
225
  ---
209
226
 
210
227
  <!-- Release links -->
211
- [Unreleased]: https://github.com/jrolf/thoughtflow/compare/v0.2.4...HEAD
228
+ [Unreleased]: https://github.com/jrolf/thoughtflow/compare/v0.2.5...HEAD
229
+ [0.2.5]: https://github.com/jrolf/thoughtflow/compare/v0.2.4...v0.2.5
212
230
  [0.2.4]: https://github.com/jrolf/thoughtflow/compare/v0.2.3...v0.2.4
213
231
  [0.2.3]: https://github.com/jrolf/thoughtflow/compare/v0.2.2...v0.2.3
214
232
  [0.2.2]: https://github.com/jrolf/thoughtflow/compare/v0.2.0...v0.2.2
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: thoughtflow
3
- Version: 0.2.4
3
+ Version: 0.2.5
4
4
  Summary: Powerful AI systems from simple parts. Composable cognitive primitives, event-sourced memory, and autonomous agents in pure Python with zero dependencies.
5
5
  Project-URL: Homepage, https://github.com/jrolf/thoughtflow
6
6
  Project-URL: Documentation, https://thoughtflow.dev
@@ -164,7 +164,7 @@ supply-chain anxiety. The core library uses only Python's standard library —
164
164
  pip install --upgrade thoughtflow
165
165
 
166
166
  # Pin to a specific version for stability
167
- pip install thoughtflow==0.2.4
167
+ pip install thoughtflow==0.2.5
168
168
 
169
169
  # Check your installed version
170
170
  python -c "import thoughtflow; print(thoughtflow.__version__)"
@@ -304,18 +304,6 @@ ThoughtFlow is the right choice when:
304
304
  - **You prefer composition over configuration** — Plain Python, not YAML or JSON configs.
305
305
  - **You work across multiple LLM providers** — One interface for OpenAI, Anthropic, Groq, Gemini, Ollama, and more.
306
306
 
307
- ## ❌ When NOT to Use ThoughtFlow
308
-
309
- Be honest with yourself — ThoughtFlow isn't for everyone:
310
-
311
- - **You need pre-built RAG pipelines out of the box** → Consider [LlamaIndex](https://github.com/run-llama/llama_index)
312
- - **You want visual workflow builders** → Consider [Flowise](https://github.com/FlowiseAI/Flowise), [Langflow](https://github.com/langflow-ai/langflow)
313
- - **You need very large-scale multi-agent swarms** → Consider [AutoGen](https://github.com/microsoft/autogen), [CrewAI](https://github.com/joaomdmoura/crewai) (ThoughtFlow supports multi-agent via AGENT + DELEGATE, but optimizes for clarity over massive swarms)
314
- - **You prefer batteries-included over minimal** → Consider [LangChain](https://github.com/langchain-ai/langchain)
315
- - **You need built-in vector stores and retrievers** → ThoughtFlow doesn't include these (but see [ThoughtBase](#-sister-library-thoughtbase))
316
-
317
- **ThoughtFlow is opinionated:** we trade breadth for clarity. We do fewer things, but we do them well.
318
-
319
307
  ---
320
308
 
321
309
  ## 🚀 Escape Velocity: What You Can Delete
@@ -681,6 +669,34 @@ visible = memory.get_msgs(exclude_metadata={"internal": True})
681
669
  # Or select only the tagged ones
682
670
  rag_events = memory.get_msgs(metadata_filter={"source": "rag"})
683
671
 
672
+ # ═══════════════════════════════════════════════════════════════════════════
673
+ # RAG AUGMENTS — optional LLM-view merging (event log unchanged)
674
+ # ═══════════════════════════════════════════════════════════════════════════
675
+
676
+ # Store retrieved context as a tagged augment event
677
+ memory.add_augment(
678
+ "Retrieved context:\n" + context,
679
+ metadata={"internal": True, "source": "rag"},
680
+ )
681
+
682
+ # Default LLM view: augment is a separate message
683
+ memory.get_llm_msgs()
684
+
685
+ # Opt-in: fold augment into the preceding user turn for the model only
686
+ memory.get_llm_msgs(merge_augments=True)
687
+
688
+ # AGENT(merge_augments=True) uses the merged view automatically
689
+
690
+ # ═══════════════════════════════════════════════════════════════════════════
691
+ # LIFECYCLE EMITS — typed, JSON-safe machine-readable events
692
+ # ═══════════════════════════════════════════════════════════════════════════
693
+
694
+ memory.emit("run_started", {"run_id": "abc123", "trigger": {"source": "cron"}})
695
+ memory.emit("plan_committed", {"step_count": 3, "plan_id": "p1"})
696
+
697
+ started = memory.get_emits(kind="run_started")
698
+ all_emits = memory.get_emits() # chronological, deep-copied payloads
699
+
684
700
  # ═══════════════════════════════════════════════════════════════════════════
685
701
  # LOGS & REFLECTIONS — internal agent reasoning
686
702
  # ═══════════════════════════════════════════════════════════════════════════
@@ -836,6 +852,8 @@ memory.get_var("attachment") # Returns decompressed data
836
852
  - **Full variable history** — See every change with timestamps
837
853
  - **Channel tracking** — Build omni-channel agents (web, mobile, Telegram, etc.)
838
854
  - **Message metadata** — Tag events and filter views (UI-visible vs internal)
855
+ - **RAG augments** — `add_augment()` + `get_llm_msgs(merge_augments=True)` for optional LLM-view merging
856
+ - **Lifecycle emits** — `emit()` / `get_emits()` for typed JSON-safe run facts alongside prose logs
839
857
  - **Tombstone deletion** — History is never lost
840
858
  - **Auto-compression** — Large values handled automatically
841
859
  - **Multiple export formats** — JSON, Pickle, snapshots for cloud sync
@@ -1014,6 +1032,20 @@ memory = thought(memory)
1014
1032
  # Tokens stream through your hook in real time; the complete text still
1015
1033
  # flows through parsing/validation and lands in memory as usual.
1016
1034
 
1035
+ # ═══════════════════════════════════════════════════════════════════════════
1036
+ # PROMPT RENDERING — substitute mode and history control
1037
+ # ═══════════════════════════════════════════════════════════════════════════
1038
+
1039
+ thought = THOUGHT(
1040
+ name="extract_plan",
1041
+ llm=llm,
1042
+ prompt='Return JSON with key "steps": {task}',
1043
+ template_mode="substitute", # exact {key} replacement (no .format() escaping issues)
1044
+ include_history=False, # only system + rendered user prompt (no prior turns)
1045
+ )
1046
+ # When include_history=True (default), prior turns come from MEMORY.get_llm_msgs()
1047
+ # and are forwarded without template substitution on historical content.
1048
+
1017
1049
  # ═══════════════════════════════════════════════════════════════════════════
1018
1050
  # PRODUCTION LANE — opt-in hardening (v0.2.2+, defaults unchanged)
1019
1051
  # ═══════════════════════════════════════════════════════════════════════════
@@ -1067,6 +1099,8 @@ thought.last_response # Raw LLM response
1067
1099
  - **Schema-based parsing** — Via `valid_extract` for bulletproof extraction
1068
1100
  - **Multiple validators** — Built-in or custom, via the `validation=` parameter
1069
1101
  - **Token streaming** — `on_token=` hook streams chunks without breaking the contract
1102
+ - **Prompt rendering** — `template_mode='substitute'` for JSON-heavy prompts; `include_history=False` for single-turn calls
1103
+ - **History via MEMORY** — Prior turns come from `get_llm_msgs()` without mutating stored events
1070
1104
  - **Production lane (opt-in)** — `validation_mode`, `strict_schema`, `hold_msg`, `on_failure`
1071
1105
  - **Structured failure visibility** — `{name}_last_error` and `{name}_attempts` on MEMORY
1072
1106
  - **Four operations** — `llm_call`, `memory_query`, `variable_set`, `conditional`
@@ -1365,6 +1399,8 @@ planner = PLAN(
1365
1399
  - **Configurable limits** — `max_steps` and `max_parallel` constraints
1366
1400
  - **Inherits from THOUGHT** — Full retry, serialization, and hook support
1367
1401
 
1402
+ For an executable, offline plan-commit-reflect loop built from PLAN, MEMORY, and plain Python, see the copy-and-edit [Foundation agent loop reference](examples/reference/README.md). The recipe demonstrates bounded execution, receipts, step-result resolution, approval gates, lifecycle emits, and isolated sub-runs without adding a framework layer.
1403
+
1368
1404
  ---
1369
1405
 
1370
1406
  ### ACTION Subclasses — Elemental Operations
@@ -1548,6 +1584,7 @@ agent = AGENT(
1548
1584
  tools=tools,
1549
1585
  system_prompt="You are a helpful weather assistant.",
1550
1586
  max_iterations=10,
1587
+ merge_augments=False, # set True to fold RAG augments into user messages for the LLM
1551
1588
  )
1552
1589
 
1553
1590
  memory = MEMORY()
@@ -1761,6 +1798,21 @@ rules = {
1761
1798
  }
1762
1799
  ```
1763
1800
 
1801
+ **Branch-shaped responses (oneOf dialect):**
1802
+
1803
+ ```python
1804
+ # First matching branch wins — useful for classification thoughts
1805
+ rules = {
1806
+ "kind": "python",
1807
+ "format": {
1808
+ "oneOf": [
1809
+ {"verdict": "found", "matched_span": ""},
1810
+ {"verdict": "absent", "note": ""},
1811
+ ]
1812
+ },
1813
+ }
1814
+ ```
1815
+
1764
1816
  **List element validation:**
1765
1817
 
1766
1818
  ```python
@@ -1816,6 +1868,7 @@ except ValidExtractError as e:
1816
1868
  - `{}` → dict (any contents)
1817
1869
  - `{"k": schema}` → dict with required key "k"
1818
1870
  - `{"k?": schema}` → dict with optional key "k"
1871
+ - `{"oneOf": [schema, ...]}` → first matching branch wins (classification)
1819
1872
 
1820
1873
  ---
1821
1874
 
@@ -2146,26 +2199,34 @@ lives in [`examples/serverless/`](examples/serverless/).
2146
2199
 
2147
2200
  ### RAG, the ThoughtFlow Way
2148
2201
 
2149
- Retrieved context enters MEMORY as **tagged events** — the user's original
2150
- message is never mutated, so the event log stays a truthful audit of what the
2151
- user said versus what the system added:
2202
+ Retrieved context enters MEMORY as **tagged augment events** — the user's
2203
+ original message is never mutated, so the event log stays a truthful audit of
2204
+ what the user said versus what the system added:
2152
2205
 
2153
2206
  ```python
2154
2207
  # Retrieve (EMBED + cosine similarity, a vector DB, or any retriever you like)
2155
2208
  context = retrieve_relevant_chunks(memory.last_user_msg(content_only=True))
2156
2209
 
2157
- # Inject as a tagged system message — auditable, filterable
2158
- memory.add_msg("system", f"Relevant context:\n{context}",
2159
- metadata={"internal": True, "source": "rag"})
2210
+ # Store as an augment — auditable, filterable, separate in the event log
2211
+ memory.add_augment(
2212
+ f"Relevant context:\n{context}",
2213
+ metadata={"internal": True, "source": "rag"},
2214
+ )
2160
2215
 
2161
- memory = answer_thought(memory) # the THOUGHT sees the context
2216
+ # Default: THOUGHT/AGENT see context as a separate system message
2217
+ memory = answer_thought(memory)
2218
+
2219
+ # Opt-in: fold context into the user turn for the LLM payload only
2220
+ agent = AGENT(llm=llm, merge_augments=True)
2221
+ memory = agent(memory)
2162
2222
 
2163
2223
  # The UI shows only what the user should see
2164
2224
  visible_history = memory.get_msgs(exclude_metadata={"internal": True})
2165
2225
  ```
2166
2226
 
2167
2227
  ThoughtFlow deliberately ships no vector store — compose with whatever
2168
- retrieval you already trust. The full doctrine is in
2228
+ retrieval you already trust. The full walkthrough is in
2229
+ [`examples/scripts/14_rag_llm_view.py`](examples/scripts/14_rag_llm_view.py) and
2169
2230
  [`docs/concepts/rag.md`](docs/concepts/rag.md).
2170
2231
 
2171
2232
  ---
@@ -2340,7 +2401,8 @@ thoughtflow/
2340
2401
  │ └── eval/ # Evaluation harness (record/replay lives in llm.py/memory.py)
2341
2402
  ├── primitives/ # Per-primitive documentation (Markdown) — canonical API reference
2342
2403
  ├── examples/ # Working, runnable examples
2343
- │ ├── scripts/ # Numbered walkthroughs (01_hello_world ... 13_record_replay)
2404
+ │ ├── scripts/ # Numbered walkthroughs (01_hello_world ... 15_thought_integration_test)
2405
+ │ ├── reference/ # Copy-and-edit agent loop recipes with focused tests
2344
2406
  │ └── serverless/ # Deployable AWS Lambda chat handler
2345
2407
  ├── tests/ # Comprehensive test suite
2346
2408
  │ ├── unit/
@@ -2389,10 +2451,11 @@ See [developer/](developer/) for comprehensive development documentation.
2389
2451
  | **Orchestration** | ✅ Stable | WORKFLOW, CHRON |
2390
2452
  | **Action Subclasses** | ✅ Stable | 16 elemental operations (SEARCH, SCRAPE, FETCH, etc.) |
2391
2453
  | **Record/Replay** | ✅ Shipped | LLM/EMBED recording, deterministic replay, eval harness |
2454
+ | **Lifecycle emits & RAG augments** | ✅ Shipped | `emit()`/`get_emits()`, `add_augment()`/`get_llm_msgs(merge_augments=)` |
2392
2455
  | **Provider convenience classes** | ✅ Shipped (0.2.2) | GroqLLM, CerebrasLLM, OpenRouterLLM, prompt caching |
2393
2456
  | **API Stability** | 🟡 Alpha | May evolve based on feedback |
2394
2457
  | **Documentation** | ✅ Per-primitive docs | `primitives/` folder with Markdown per class |
2395
- | **Test Coverage** | ✅ ~744 unit tests | Plus optional integration smoke tests (API keys) |
2458
+ | **Test Coverage** | ✅ ~870 unit tests | Plus optional integration smoke tests (API keys) |
2396
2459
  | **Serverless Ready** | ✅ Yes | Zero deps, deployable example in `examples/serverless/` |
2397
2460
 
2398
2461
  See [CHANGELOG.md](CHANGELOG.md) for version history.
@@ -93,7 +93,7 @@ supply-chain anxiety. The core library uses only Python's standard library —
93
93
  pip install --upgrade thoughtflow
94
94
 
95
95
  # Pin to a specific version for stability
96
- pip install thoughtflow==0.2.4
96
+ pip install thoughtflow==0.2.5
97
97
 
98
98
  # Check your installed version
99
99
  python -c "import thoughtflow; print(thoughtflow.__version__)"
@@ -233,18 +233,6 @@ ThoughtFlow is the right choice when:
233
233
  - **You prefer composition over configuration** — Plain Python, not YAML or JSON configs.
234
234
  - **You work across multiple LLM providers** — One interface for OpenAI, Anthropic, Groq, Gemini, Ollama, and more.
235
235
 
236
- ## ❌ When NOT to Use ThoughtFlow
237
-
238
- Be honest with yourself — ThoughtFlow isn't for everyone:
239
-
240
- - **You need pre-built RAG pipelines out of the box** → Consider [LlamaIndex](https://github.com/run-llama/llama_index)
241
- - **You want visual workflow builders** → Consider [Flowise](https://github.com/FlowiseAI/Flowise), [Langflow](https://github.com/langflow-ai/langflow)
242
- - **You need very large-scale multi-agent swarms** → Consider [AutoGen](https://github.com/microsoft/autogen), [CrewAI](https://github.com/joaomdmoura/crewai) (ThoughtFlow supports multi-agent via AGENT + DELEGATE, but optimizes for clarity over massive swarms)
243
- - **You prefer batteries-included over minimal** → Consider [LangChain](https://github.com/langchain-ai/langchain)
244
- - **You need built-in vector stores and retrievers** → ThoughtFlow doesn't include these (but see [ThoughtBase](#-sister-library-thoughtbase))
245
-
246
- **ThoughtFlow is opinionated:** we trade breadth for clarity. We do fewer things, but we do them well.
247
-
248
236
  ---
249
237
 
250
238
  ## 🚀 Escape Velocity: What You Can Delete
@@ -610,6 +598,34 @@ visible = memory.get_msgs(exclude_metadata={"internal": True})
610
598
  # Or select only the tagged ones
611
599
  rag_events = memory.get_msgs(metadata_filter={"source": "rag"})
612
600
 
601
+ # ═══════════════════════════════════════════════════════════════════════════
602
+ # RAG AUGMENTS — optional LLM-view merging (event log unchanged)
603
+ # ═══════════════════════════════════════════════════════════════════════════
604
+
605
+ # Store retrieved context as a tagged augment event
606
+ memory.add_augment(
607
+ "Retrieved context:\n" + context,
608
+ metadata={"internal": True, "source": "rag"},
609
+ )
610
+
611
+ # Default LLM view: augment is a separate message
612
+ memory.get_llm_msgs()
613
+
614
+ # Opt-in: fold augment into the preceding user turn for the model only
615
+ memory.get_llm_msgs(merge_augments=True)
616
+
617
+ # AGENT(merge_augments=True) uses the merged view automatically
618
+
619
+ # ═══════════════════════════════════════════════════════════════════════════
620
+ # LIFECYCLE EMITS — typed, JSON-safe machine-readable events
621
+ # ═══════════════════════════════════════════════════════════════════════════
622
+
623
+ memory.emit("run_started", {"run_id": "abc123", "trigger": {"source": "cron"}})
624
+ memory.emit("plan_committed", {"step_count": 3, "plan_id": "p1"})
625
+
626
+ started = memory.get_emits(kind="run_started")
627
+ all_emits = memory.get_emits() # chronological, deep-copied payloads
628
+
613
629
  # ═══════════════════════════════════════════════════════════════════════════
614
630
  # LOGS & REFLECTIONS — internal agent reasoning
615
631
  # ═══════════════════════════════════════════════════════════════════════════
@@ -765,6 +781,8 @@ memory.get_var("attachment") # Returns decompressed data
765
781
  - **Full variable history** — See every change with timestamps
766
782
  - **Channel tracking** — Build omni-channel agents (web, mobile, Telegram, etc.)
767
783
  - **Message metadata** — Tag events and filter views (UI-visible vs internal)
784
+ - **RAG augments** — `add_augment()` + `get_llm_msgs(merge_augments=True)` for optional LLM-view merging
785
+ - **Lifecycle emits** — `emit()` / `get_emits()` for typed JSON-safe run facts alongside prose logs
768
786
  - **Tombstone deletion** — History is never lost
769
787
  - **Auto-compression** — Large values handled automatically
770
788
  - **Multiple export formats** — JSON, Pickle, snapshots for cloud sync
@@ -943,6 +961,20 @@ memory = thought(memory)
943
961
  # Tokens stream through your hook in real time; the complete text still
944
962
  # flows through parsing/validation and lands in memory as usual.
945
963
 
964
+ # ═══════════════════════════════════════════════════════════════════════════
965
+ # PROMPT RENDERING — substitute mode and history control
966
+ # ═══════════════════════════════════════════════════════════════════════════
967
+
968
+ thought = THOUGHT(
969
+ name="extract_plan",
970
+ llm=llm,
971
+ prompt='Return JSON with key "steps": {task}',
972
+ template_mode="substitute", # exact {key} replacement (no .format() escaping issues)
973
+ include_history=False, # only system + rendered user prompt (no prior turns)
974
+ )
975
+ # When include_history=True (default), prior turns come from MEMORY.get_llm_msgs()
976
+ # and are forwarded without template substitution on historical content.
977
+
946
978
  # ═══════════════════════════════════════════════════════════════════════════
947
979
  # PRODUCTION LANE — opt-in hardening (v0.2.2+, defaults unchanged)
948
980
  # ═══════════════════════════════════════════════════════════════════════════
@@ -996,6 +1028,8 @@ thought.last_response # Raw LLM response
996
1028
  - **Schema-based parsing** — Via `valid_extract` for bulletproof extraction
997
1029
  - **Multiple validators** — Built-in or custom, via the `validation=` parameter
998
1030
  - **Token streaming** — `on_token=` hook streams chunks without breaking the contract
1031
+ - **Prompt rendering** — `template_mode='substitute'` for JSON-heavy prompts; `include_history=False` for single-turn calls
1032
+ - **History via MEMORY** — Prior turns come from `get_llm_msgs()` without mutating stored events
999
1033
  - **Production lane (opt-in)** — `validation_mode`, `strict_schema`, `hold_msg`, `on_failure`
1000
1034
  - **Structured failure visibility** — `{name}_last_error` and `{name}_attempts` on MEMORY
1001
1035
  - **Four operations** — `llm_call`, `memory_query`, `variable_set`, `conditional`
@@ -1294,6 +1328,8 @@ planner = PLAN(
1294
1328
  - **Configurable limits** — `max_steps` and `max_parallel` constraints
1295
1329
  - **Inherits from THOUGHT** — Full retry, serialization, and hook support
1296
1330
 
1331
+ For an executable, offline plan-commit-reflect loop built from PLAN, MEMORY, and plain Python, see the copy-and-edit [Foundation agent loop reference](examples/reference/README.md). The recipe demonstrates bounded execution, receipts, step-result resolution, approval gates, lifecycle emits, and isolated sub-runs without adding a framework layer.
1332
+
1297
1333
  ---
1298
1334
 
1299
1335
  ### ACTION Subclasses — Elemental Operations
@@ -1477,6 +1513,7 @@ agent = AGENT(
1477
1513
  tools=tools,
1478
1514
  system_prompt="You are a helpful weather assistant.",
1479
1515
  max_iterations=10,
1516
+ merge_augments=False, # set True to fold RAG augments into user messages for the LLM
1480
1517
  )
1481
1518
 
1482
1519
  memory = MEMORY()
@@ -1690,6 +1727,21 @@ rules = {
1690
1727
  }
1691
1728
  ```
1692
1729
 
1730
+ **Branch-shaped responses (oneOf dialect):**
1731
+
1732
+ ```python
1733
+ # First matching branch wins — useful for classification thoughts
1734
+ rules = {
1735
+ "kind": "python",
1736
+ "format": {
1737
+ "oneOf": [
1738
+ {"verdict": "found", "matched_span": ""},
1739
+ {"verdict": "absent", "note": ""},
1740
+ ]
1741
+ },
1742
+ }
1743
+ ```
1744
+
1693
1745
  **List element validation:**
1694
1746
 
1695
1747
  ```python
@@ -1745,6 +1797,7 @@ except ValidExtractError as e:
1745
1797
  - `{}` → dict (any contents)
1746
1798
  - `{"k": schema}` → dict with required key "k"
1747
1799
  - `{"k?": schema}` → dict with optional key "k"
1800
+ - `{"oneOf": [schema, ...]}` → first matching branch wins (classification)
1748
1801
 
1749
1802
  ---
1750
1803
 
@@ -2075,26 +2128,34 @@ lives in [`examples/serverless/`](examples/serverless/).
2075
2128
 
2076
2129
  ### RAG, the ThoughtFlow Way
2077
2130
 
2078
- Retrieved context enters MEMORY as **tagged events** — the user's original
2079
- message is never mutated, so the event log stays a truthful audit of what the
2080
- user said versus what the system added:
2131
+ Retrieved context enters MEMORY as **tagged augment events** — the user's
2132
+ original message is never mutated, so the event log stays a truthful audit of
2133
+ what the user said versus what the system added:
2081
2134
 
2082
2135
  ```python
2083
2136
  # Retrieve (EMBED + cosine similarity, a vector DB, or any retriever you like)
2084
2137
  context = retrieve_relevant_chunks(memory.last_user_msg(content_only=True))
2085
2138
 
2086
- # Inject as a tagged system message — auditable, filterable
2087
- memory.add_msg("system", f"Relevant context:\n{context}",
2088
- metadata={"internal": True, "source": "rag"})
2139
+ # Store as an augment — auditable, filterable, separate in the event log
2140
+ memory.add_augment(
2141
+ f"Relevant context:\n{context}",
2142
+ metadata={"internal": True, "source": "rag"},
2143
+ )
2089
2144
 
2090
- memory = answer_thought(memory) # the THOUGHT sees the context
2145
+ # Default: THOUGHT/AGENT see context as a separate system message
2146
+ memory = answer_thought(memory)
2147
+
2148
+ # Opt-in: fold context into the user turn for the LLM payload only
2149
+ agent = AGENT(llm=llm, merge_augments=True)
2150
+ memory = agent(memory)
2091
2151
 
2092
2152
  # The UI shows only what the user should see
2093
2153
  visible_history = memory.get_msgs(exclude_metadata={"internal": True})
2094
2154
  ```
2095
2155
 
2096
2156
  ThoughtFlow deliberately ships no vector store — compose with whatever
2097
- retrieval you already trust. The full doctrine is in
2157
+ retrieval you already trust. The full walkthrough is in
2158
+ [`examples/scripts/14_rag_llm_view.py`](examples/scripts/14_rag_llm_view.py) and
2098
2159
  [`docs/concepts/rag.md`](docs/concepts/rag.md).
2099
2160
 
2100
2161
  ---
@@ -2269,7 +2330,8 @@ thoughtflow/
2269
2330
  │ └── eval/ # Evaluation harness (record/replay lives in llm.py/memory.py)
2270
2331
  ├── primitives/ # Per-primitive documentation (Markdown) — canonical API reference
2271
2332
  ├── examples/ # Working, runnable examples
2272
- │ ├── scripts/ # Numbered walkthroughs (01_hello_world ... 13_record_replay)
2333
+ │ ├── scripts/ # Numbered walkthroughs (01_hello_world ... 15_thought_integration_test)
2334
+ │ ├── reference/ # Copy-and-edit agent loop recipes with focused tests
2273
2335
  │ └── serverless/ # Deployable AWS Lambda chat handler
2274
2336
  ├── tests/ # Comprehensive test suite
2275
2337
  │ ├── unit/
@@ -2318,10 +2380,11 @@ See [developer/](developer/) for comprehensive development documentation.
2318
2380
  | **Orchestration** | ✅ Stable | WORKFLOW, CHRON |
2319
2381
  | **Action Subclasses** | ✅ Stable | 16 elemental operations (SEARCH, SCRAPE, FETCH, etc.) |
2320
2382
  | **Record/Replay** | ✅ Shipped | LLM/EMBED recording, deterministic replay, eval harness |
2383
+ | **Lifecycle emits & RAG augments** | ✅ Shipped | `emit()`/`get_emits()`, `add_augment()`/`get_llm_msgs(merge_augments=)` |
2321
2384
  | **Provider convenience classes** | ✅ Shipped (0.2.2) | GroqLLM, CerebrasLLM, OpenRouterLLM, prompt caching |
2322
2385
  | **API Stability** | 🟡 Alpha | May evolve based on feedback |
2323
2386
  | **Documentation** | ✅ Per-primitive docs | `primitives/` folder with Markdown per class |
2324
- | **Test Coverage** | ✅ ~744 unit tests | Plus optional integration smoke tests (API keys) |
2387
+ | **Test Coverage** | ✅ ~870 unit tests | Plus optional integration smoke tests (API keys) |
2325
2388
  | **Serverless Ready** | ✅ Yes | Zero deps, deployable example in `examples/serverless/` |
2326
2389
 
2327
2390
  See [CHANGELOG.md](CHANGELOG.md) for version history.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "thoughtflow"
7
- version = "0.2.4"
7
+ version = "0.2.5"
8
8
  description = "Powerful AI systems from simple parts. Composable cognitive primitives, event-sourced memory, and autonomous agents in pure Python with zero dependencies."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.9"
@@ -105,7 +105,7 @@ try:
105
105
 
106
106
  __version__ = _get_version("thoughtflow")
107
107
  except Exception:
108
- __version__ = "0.2.4"
108
+ __version__ = "0.2.5"
109
109
 
110
110
  # Public API
111
111
  __all__ = [
@@ -178,6 +178,71 @@ Never mix boundaries. Each block is separate.
178
178
  This is to improve your ease-of-reading.
179
179
  '''
180
180
 
181
+ def substitute_placeholders(text, ctx):
182
+ """
183
+ Replace ``{key}`` placeholders only when ``key`` is present in ``ctx``.
184
+
185
+ Unknown placeholders and literal JSON braces are left untouched. Bare words
186
+ such as ``messages`` are never replaced unless the template contains
187
+ ``{messages}``.
188
+
189
+ Args:
190
+ text (str): Template string.
191
+ ctx (dict): Context variables available for substitution.
192
+
193
+ Returns:
194
+ str: Rendered string.
195
+ """
196
+ if not isinstance(text, str):
197
+ return str(text)
198
+
199
+ pattern = re.compile(r"\{([^}]+)\}")
200
+
201
+ def replacer(match):
202
+ key = match.group(1)
203
+ if key in ctx:
204
+ return str(ctx[key])
205
+ return match.group(0)
206
+
207
+ return pattern.sub(replacer, text)
208
+
209
+
210
+ def render_template(template, ctx, mode="format"):
211
+ """
212
+ Render a prompt template using the selected template mode.
213
+
214
+ ``format`` uses ``str.format(**ctx)`` with the legacy silent fallback that
215
+ returns the raw template when formatting fails. ``substitute`` replaces
216
+ only explicit ``{key}`` placeholders for keys present in ``ctx``.
217
+
218
+ Args:
219
+ template (str): Prompt template string.
220
+ ctx (dict): Context variables for rendering.
221
+ mode (str): ``format`` or ``substitute``.
222
+
223
+ Returns:
224
+ str: Rendered prompt text.
225
+
226
+ Raises:
227
+ ValueError: When ``mode`` is not ``format`` or ``substitute``.
228
+ """
229
+ if mode not in ("format", "substitute"):
230
+ raise ValueError(
231
+ "template_mode must be 'format' or 'substitute', got: {!r}".format(mode)
232
+ )
233
+
234
+ if not isinstance(template, str):
235
+ return str(template)
236
+
237
+ if mode == "substitute":
238
+ return substitute_placeholders(template, ctx)
239
+
240
+ try:
241
+ return template.format(**ctx)
242
+ except Exception:
243
+ return template
244
+
245
+
181
246
  def construct_prompt(
182
247
  prompt_obj = {},
183
248
  order = [],