thoughtflow 0.2.3__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.
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/CHANGELOG.md +30 -5
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/PKG-INFO +87 -24
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/README.md +86 -23
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/pyproject.toml +1 -1
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/__init__.py +1 -1
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/_util.py +65 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/memory.py +198 -51
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/thought.py +232 -62
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/thoughts/plan.py +39 -7
- thoughtflow-0.2.5/tests/unit/test_foundation_agent_response.py +615 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_memory.py +197 -9
- thoughtflow-0.2.5/tests/unit/test_reference_plan_loop.py +406 -0
- thoughtflow-0.2.3/tests/unit/test_foundation_agent_response.py +0 -240
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/.gitignore +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/LICENSE +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/_cron_expr.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/action.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/__init__.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/_http.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/_substitution.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/ask.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/call.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/fetch.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/noop.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/notify.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/post.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/read_file.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/run.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/say.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/scrape.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/search.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/sleep.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/wait.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/actions/write_file.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/agent.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/agents/__init__.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/agents/planact.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/agents/react.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/agents/reflect.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/chat.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/chron.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/delegate.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/embed.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/eval/__init__.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/eval/harness.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/llm.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/llm_cache.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/llm_params.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/mcp.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/message.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/providers/README.md +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/providers/__init__.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/providers/cerebras.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/providers/groq.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/providers/openrouter.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/py.typed +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/this.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/thoughts/__init__.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/thoughts/decide.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/tool.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/src/thoughtflow/workflow.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/__init__.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/conftest.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/integration/__init__.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/integration/smoke_helpers.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/integration/test_chron.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/integration/test_embed_providers.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/integration/test_llm_providers.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/integration/test_scrape.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/integration/test_search_providers.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/__init__.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_action.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_actions.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_agent.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_chat.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_chron.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_delegate.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_embed.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_eval.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_llm.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_llm_provider_integration.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_mcp.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_message.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_replay.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_this.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_thought.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_tool.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_util.py +0 -0
- {thoughtflow-0.2.3 → thoughtflow-0.2.5}/tests/unit/test_workflow.py +0 -0
|
@@ -5,6 +5,33 @@ 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
|
+
|
|
29
|
+
## [0.2.4] - 2026-07-11
|
|
30
|
+
|
|
31
|
+
### Fixed
|
|
32
|
+
- MEMORY index tie-breaking: events with identical `dt_utc` now preserve insertion order (fixes flaky replay and get_events tests on CI)
|
|
33
|
+
- `add_exchange()` stamp now includes response payload so duplicate-key recordings are not overwritten
|
|
34
|
+
|
|
8
35
|
## [0.2.3] - 2026-07-11
|
|
9
36
|
|
|
10
37
|
### Fixed
|
|
@@ -43,10 +70,6 @@ Production-hardening release: THOUGHT/PLAN parsing improvements (Foundation Agen
|
|
|
43
70
|
- EMBED Groq calls include User-Agent (Cloudflare HTTP 1010 without it)
|
|
44
71
|
- EMBED `text-embedding-004` aliases to `gemini-embedding-001`; `last_error` surfaced on failures
|
|
45
72
|
|
|
46
|
-
## [Unreleased]
|
|
47
|
-
|
|
48
|
-
_Nothing yet._
|
|
49
|
-
|
|
50
73
|
---
|
|
51
74
|
|
|
52
75
|
## [0.2.0] - 2026-06-10
|
|
@@ -202,7 +225,9 @@ grown from MEMORY itself, with zero new concepts.
|
|
|
202
225
|
---
|
|
203
226
|
|
|
204
227
|
<!-- Release links -->
|
|
205
|
-
[Unreleased]: https://github.com/jrolf/thoughtflow/compare/v0.2.
|
|
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
|
|
230
|
+
[0.2.4]: https://github.com/jrolf/thoughtflow/compare/v0.2.3...v0.2.4
|
|
206
231
|
[0.2.3]: https://github.com/jrolf/thoughtflow/compare/v0.2.2...v0.2.3
|
|
207
232
|
[0.2.2]: https://github.com/jrolf/thoughtflow/compare/v0.2.0...v0.2.2
|
|
208
233
|
[0.2.0]: https://github.com/jrolf/thoughtflow/compare/v0.1.3...v0.2.0
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: thoughtflow
|
|
3
|
-
Version: 0.2.
|
|
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.
|
|
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
|
|
2150
|
-
message is never mutated, so the event log stays a truthful audit of
|
|
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
|
-
#
|
|
2158
|
-
memory.
|
|
2159
|
-
|
|
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
|
-
|
|
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
|
|
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 ...
|
|
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** | ✅ ~
|
|
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.
|
|
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
|
|
2079
|
-
message is never mutated, so the event log stays a truthful audit of
|
|
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
|
-
#
|
|
2087
|
-
memory.
|
|
2088
|
-
|
|
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
|
-
|
|
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
|
|
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 ...
|
|
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** | ✅ ~
|
|
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.
|
|
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"
|
|
@@ -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 = [],
|