rhachet-roles-bhrain 0.1.1 → 0.3.0

package/dist/roles/architect/briefs/brains.replic/arc106.concept.tool-definition.[article].md

@@ -0,0 +1,59 @@
+# tool-definition
+
+## .what
+
+a schema that describes a tool's interface — its name, purpose, parameters, and expected behavior — enabling an llm to understand when and how to invoke it.
+
+## .why
+
+tool definitions are the contract between the llm and external capabilities. by providing structured schemas, the llm can reason about which tools apply to a task, what parameters to provide, and what results to expect. well-designed tool definitions are essential for reliable agent behavior.
+
+## dependsOn
+
+- `system-prompt` — tool definitions are typically included in system prompt
+- `llm` — interprets tool definitions and decides when to invoke
+
+## key characteristics
+
+- **name**: unique identifier for the tool
+- **description**: natural language explanation of purpose
+- **parameters**: typed schema (often JSON Schema) for inputs
+- **returns**: description of expected output format
+
+## example schema
+
+```json
+{
+  "name": "Read",
+  "description": "Reads a file from the filesystem",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "file_path": {
+        "type": "string",
+        "description": "Absolute path to the file"
+      },
+      "offset": {
+        "type": "number",
+        "description": "Line number to start reading from"
+      }
+    },
+    "required": ["file_path"]
+  }
+}
+```
+
+## tool categories (replic brains)
+
+| category | examples |
+|----------|----------|
+| filesystem | Read, Write, Edit, Glob, Grep |
+| execution | Bash, Task |
+| communication | WebSearch, WebFetch |
+| coordination | TodoWrite, AskUserQuestion |
+
+## sources
+
+- [Advanced Tool Use on Claude](https://www.anthropic.com/engineering/advanced-tool-use) — tool definition patterns
+- [Toolformer](https://arxiv.org/abs/2302.04761) — self-supervised tool learning
+- [MCP Specification](https://modelcontextprotocol.io/) — standardized tool protocol

package/dist/roles/architect/briefs/brains.replic/arc107.concept.tool-call.[article].md

@@ -0,0 +1,54 @@
+# tool-call
+
+## .what
+
+a structured request generated by an llm to invoke a specific tool with given parameters, representing the agent's decision to take an external action.
+
+## .why
+
+tool calls are the mechanism by which replic brains interact with the world beyond text generation. when the llm determines that a task requires external action — reading a file, executing code, searching the web — it emits a tool call. this is the bridge between reasoning and action.
+
+## dependsOn
+
+- `tool-definition` — provides the schema for valid calls
+- `llm` — generates the tool call
+- `agentic-loop` — processes and executes the call
+
+## key characteristics
+
+- **structured**: follows the schema defined in tool-definition
+- **atomic**: one tool call = one action
+- **declarative**: specifies what to do, not how
+- **interruptible**: execution may require user approval
+
+## example
+
+```json
+{
+  "tool": "Read",
+  "parameters": {
+    "file_path": "/home/user/project/src/main.ts",
+    "offset": 100,
+    "limit": 50
+  }
+}
+```
+
+## lifecycle
+
+1. llm generates tool call in response
+2. system extracts and validates parameters
+3. permission check (if required)
+4. tool executes
+5. result returned to context as `tool-result`
+
+## parallelism
+
+some systems allow multiple tool calls in a single response:
+- **independent calls**: can execute in parallel
+- **dependent calls**: must execute sequentially
+
+## sources
+
+- [ReAct](https://arxiv.org/abs/2210.03629) — action in reasoning+acting loop
+- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) — tool call patterns

package/dist/roles/architect/briefs/brains.replic/arc108.concept.tool-result.[article].md

@@ -0,0 +1,58 @@
+# tool-result
+
+## .what
+
+the output returned from executing a tool call, injected back into the llm's context as feedback for continued reasoning.
+
+## .why
+
+tool results close the feedback loop in agentic systems. they allow the llm to observe the consequences of its actions, verify success or failure, and adjust its approach. without tool results, the agent would be operating blind.
+
+## dependsOn
+
+- `tool-call` — produces the result
+- `context-window` — result consumes context tokens
+
+## key characteristics
+
+- **structured or text**: depends on tool (json, stdout, file contents)
+- **may be truncated**: large outputs compressed to fit context
+- **includes metadata**: success/failure, error messages
+- **grounds reasoning**: provides factual information
+
+## example
+
+```
+Tool Result (Read):
+     1→import { Component } from 'react';
+     2→
+     3→export class App extends Component {
+     4→  render() {
+     5→    return <div>Hello World</div>;
+     6→  }
+     7→}
+```
+
+## handling large results
+
+| strategy | description |
+|----------|-------------|
+| truncation | cut output at N characters/lines |
+| summarization | llm summarizes before adding to context |
+| pagination | return chunks with offset/limit |
+| streaming | process incrementally |
+
+## error results
+
+tool results may indicate failures:
+- file not found
+- permission denied
+- timeout exceeded
+- invalid parameters
+
+the llm must interpret these and adapt its approach.
+
+## sources
+
+- [ReAct](https://arxiv.org/abs/2210.03629) — observation in ReAct loop
+- [Inner Monologue](https://arxiv.org/abs/2207.05608) — environment feedback

package/dist/roles/architect/briefs/brains.replic/arc109.concept.agentic-loop.[article].md

@@ -0,0 +1,62 @@
+# agentic-loop
+
+## .what
+
+the core execution pattern of replic brains: repeatedly generate llm response, check for tool calls, execute tools, append results, and continue until task completion.
+
+## .why
+
+the agentic loop is what transforms a stateless llm into a persistent, goal-directed agent. by iterating through generate → execute → observe cycles, the agent can accomplish complex multi-step tasks that exceed what a single generation could produce.
+
+## dependsOn
+
+- `llm` — generates responses and tool calls
+- `repl` — the agentic loop is the repl pattern applied to llms
+- `tool-call` — actions to execute
+- `tool-result` — feedback from actions
+- `context-window` — accumulates conversation history
+
+## pseudocode
+
+```python
+while True:
+    response = llm.generate(context_window)
+
+    if response.has_tool_calls:
+        for tool_call in response.tool_calls:
+            result = execute_tool(tool_call)
+            context_window.append(result)
+    else:
+        return response  # task complete, exit loop
+```
+
+## key characteristics
+
+- **unbounded iteration**: continues until llm stops calling tools
+- **context accumulation**: history grows with each turn
+- **goal-directed**: llm decides when task is complete
+- **interruptible**: user can inject messages mid-loop
+
+## termination conditions
+
+| condition          | trigger                         |
+| ------------------ | ------------------------------- |
+| natural completion | llm responds without tool calls |
+| context exhaustion | context window fills up         |
+| user interruption  | user sends new message          |
+| timeout            | max iterations or time exceeded |
+| error              | unrecoverable tool failure      |
+
+## variants
+
+| variant     | modification                         |
+| ----------- | ------------------------------------ |
+| react       | interleave explicit reasoning traces |
+| reflexion   | add self-reflection after failures   |
+| tree search | explore multiple action branches     |
+
+## sources
+
+- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) — canonical loop description
+- [ReAct](https://arxiv.org/abs/2210.03629) — reasoning-augmented loop
+- [CoALA](https://arxiv.org/abs/2309.02427) — framework for loop variants

package/dist/roles/architect/briefs/brains.replic/arc110.concept.reasoning-trace.[article].md

@@ -0,0 +1,58 @@
+# reasoning-trace
+
+## .what
+
+explicit intermediate reasoning steps that an llm produces before generating a final answer, making its thought process visible and improving accuracy on complex tasks.
+
+## .why
+
+reasoning traces transform black-box generation into interpretable problem-solving. by externalizing intermediate steps, the llm can break down complex problems, catch errors in its reasoning, and provide explanations that humans can verify. this is the foundation for chain-of-thought and related techniques.
+
+## dependsOn
+
+- `llm` — generates the reasoning trace
+- `context-window` — traces consume tokens
+
+## key characteristics
+
+- **intermediate**: produced before final answer
+- **natural language**: typically readable text
+- **step-by-step**: decomposed reasoning
+- **self-documenting**: explains the llm's approach
+
+## example
+
+```
+Question: What is 23 × 17?
+
+Reasoning trace:
+- I need to multiply 23 by 17
+- 23 × 17 = 23 × (10 + 7)
+- = 23 × 10 + 23 × 7
+- = 230 + 161
+- = 391
+
+Answer: 391
+```
+
+## elicitation methods
+
+| method | technique |
+|--------|-----------|
+| zero-shot | "Let's think step by step" |
+| few-shot | provide example traces |
+| trained | fine-tune on trace datasets |
+| scratchpad | dedicated trace output space |
+
+## benefits
+
+- improved accuracy on reasoning tasks
+- reduced hallucination
+- debuggable/auditable outputs
+- enables self-correction
+
+## sources
+
+- [Chain-of-Thought Prompting](https://arxiv.org/abs/2201.11903) — seminal paper
+- [Scratchpads](https://arxiv.org/abs/2112.00114) — intermediate computation
+- [Extended Thinking](https://www.anthropic.com/news/visible-extended-thinking) — claude's thinking mode

package/dist/roles/architect/briefs/brains.replic/arc111.concept.react-pattern.[article].md

@@ -0,0 +1,65 @@
+# react-pattern
+
+## .what
+
+a prompting paradigm that interleaves reasoning traces with actions, producing explicit Thought → Action → Observation cycles that ground reasoning in real-world feedback.
+
+## .why
+
+react addresses a fundamental limitation of pure reasoning: hallucination. by forcing the model to take actions and observe actual results between reasoning steps, react grounds abstract thought in concrete feedback. this synergy of reasoning and acting enables more reliable task completion.
+
+## dependsOn
+
+- `reasoning-trace` — the "thought" component
+- `tool-call` — the "action" component
+- `tool-result` — the "observation" component
+- `agentic-loop` — orchestrates the cycle
+
+## pattern structure
+
+```
+Thought: I need to find information about X
+Action: Search("X")
+Observation: [search results]
+Thought: Based on these results, I should check Y
+Action: Read("file_y.txt")
+Observation: [file contents]
+Thought: Now I can answer the question
+Answer: ...
+```
+
+## benchmark performance
+
+| benchmark | react vs baseline |
+|-----------|-------------------|
+| HotPotQA | competitive with CoT, lower hallucination (6% vs 14%) |
+| ALFWorld | +34% over imitation learning |
+| WebShop | significantly outperforms Act-only |
+
+## tradeoffs
+
+### strengths
+- grounded in real observations
+- lower hallucination rate
+- interpretable decision process
+- recovers from errors via feedback
+
+### weaknesses
+- structurally constrained (forced action after each thought)
+- dependent on quality of retrieved information
+- may force unnecessary actions
+
+## comparison with pure CoT
+
+| aspect | CoT | ReAct |
+|--------|-----|-------|
+| grounding | internal only | external observations |
+| hallucination | higher | lower |
+| flexibility | high | constrained by structure |
+| task types | reasoning | reasoning + interaction |
+
+## sources
+
+- [ReAct: Synergizing Reasoning and Acting](https://arxiv.org/abs/2210.03629) — original paper (ICLR 2023)
+- [Google Research Blog](https://research.google/blog/react-synergizing-reasoning-and-acting-in-language-models/) — overview
+- [Comprehensive Guide to ReAct](https://www.mercity.ai/blog-post/react-prompting-and-react-based-agentic-systems) — practical guide

package/dist/roles/architect/briefs/brains.replic/arc112.concept.reflexion-pattern.[article].md

@@ -0,0 +1,68 @@
+# reflexion-pattern
+
+## .what
+
+an agent architecture that adds explicit self-reflection after task attempts, storing verbal feedback in memory to improve performance on subsequent trials through "verbal reinforcement learning."
+
+## .why
+
+reflexion addresses a key limitation of single-attempt agents: they cannot learn from their mistakes within a session. by reflecting on failures and storing insights, the agent can iteratively improve without weight updates. this enables rapid adaptation and higher eventual success rates.
+
+## dependsOn
+
+- `agentic-loop` — base execution pattern
+- `reasoning-trace` — reflection is a form of reasoning
+- `context-window` — stores reflection memory
+
+## pattern structure
+
+```
+Attempt 1:
+  [Execute task]
+  Result: Failed (test case 3)
+
+Reflection:
+  "I failed because I didn't handle the edge case where
+   the input is empty. Next time I should check for
+   empty inputs before processing."
+
+Attempt 2:
+  [Execute task with reflection in context]
+  Result: Passed
+```
+
+## key components
+
+| component | purpose |
+|-----------|---------|
+| actor | executes actions in environment |
+| evaluator | scores trajectory (success/failure) |
+| self-reflection | generates verbal feedback |
+| memory | stores reflections for future attempts |
+
+## benchmark performance
+
+| benchmark | improvement |
+|-----------|-------------|
+| ALFWorld | +22% success rate with reflection |
+| HotPotQA | improved accuracy over baseline ReAct |
+| programming | higher pass rates on iterative debugging |
+
+## vs other patterns
+
+| pattern | learns from failure? | mechanism |
+|---------|---------------------|-----------|
+| ReAct | no | single attempt |
+| Reflexion | yes | verbal memory |
+| LATS | yes | tree search with backtracking |
+
+## implementation notes
+
+- reflection is stored as text in context or external memory
+- number of attempts typically capped (e.g., 3-5)
+- works best when failure modes are diverse
+
+## sources
+
+- [Reflexion: Language Agents with Verbal Reinforcement Learning](https://arxiv.org/abs/2303.11366) — original paper
+- [AgentBench](https://arxiv.org/abs/2308.03688) — benchmark including reflexion variants

package/dist/roles/architect/briefs/brains.replic/arc113.concept.tree-of-thoughts.[article].md

@@ -0,0 +1,76 @@
+# tree-of-thoughts
+
+## .what
+
+a deliberate problem-solving framework that explores multiple reasoning paths as a tree structure, using search algorithms (BFS/DFS) and evaluation to find optimal solutions.
+
+## .why
+
+tree of thoughts addresses the limitation of linear chain-of-thought: once a reasoning path is taken, there's no backtracking. by explicitly exploring multiple branches and evaluating intermediate states, ToT enables deliberate planning and can solve problems requiring lookahead that linear approaches cannot.
+
+## dependsOn
+
+- `reasoning-trace` — each node contains reasoning
+- `llm` — generates and evaluates thoughts
+
+## pattern structure
+
+```
+                    [Problem]
+                       │
+          ┌────────────┼────────────┐
+          │            │            │
+     [Thought A]  [Thought B]  [Thought C]
+          │            │            │
+       [eval: 0.8]  [eval: 0.3]  [eval: 0.9] ← best
+          │                         │
+     [Thought A1]              [Thought C1]
+          │                         │
+       [eval: 0.6]              [eval: 0.95] ← selected
+```
+
+## key components
+
+| component | purpose |
+|-----------|---------|
+| thought decomposition | break problem into steps |
+| thought generator | propose multiple candidates |
+| state evaluator | score intermediate states |
+| search algorithm | BFS, DFS, or beam search |
+
+## benchmark performance
+
+| benchmark | ToT vs CoT |
+|-----------|------------|
+| Game of 24 | 74% vs 4% |
+| Creative Writing | improved coherence |
+| Crosswords | significantly higher solve rate |
+
+## search strategies
+
+| strategy | characteristic |
+|----------|----------------|
+| BFS | explore all options at each depth |
+| DFS | explore deeply first, backtrack |
+| beam search | keep top-k candidates at each level |
+
+## cost tradeoff
+
+ToT requires significantly more LLM calls than linear approaches:
+- multiple thought proposals per step
+- evaluation calls for each candidate
+- may explore many branches
+
+## vs other patterns
+
+| pattern | exploration | backtracking |
+|---------|-------------|--------------|
+| CoT | linear | none |
+| Self-Consistency | parallel paths, no interaction | none |
+| ToT | tree structure | yes |
+| LATS | tree + MCTS | yes, with learning |
+
+## sources
+
+- [Tree of Thoughts: Deliberate Problem Solving](https://arxiv.org/abs/2305.10601) — original paper (NeurIPS 2023)
+- [CoALA](https://arxiv.org/abs/2309.02427) — positions ToT in agent framework

package/dist/roles/architect/briefs/brains.replic/arc114.concept.self-consistency.[article].md

@@ -0,0 +1,73 @@
+# self-consistency
+
+## .what
+
+a decoding strategy that samples multiple reasoning paths from the llm and selects the final answer by majority vote, leveraging the intuition that correct reasoning is more likely to converge on the same answer.
+
+## .why
+
+self-consistency exploits the stochastic nature of llm generation as a feature rather than a bug. different reasoning paths may make different mistakes, but correct paths tend to agree on the final answer. by sampling multiple times and voting, we reduce the impact of individual reasoning errors.
+
+## dependsOn
+
+- `reasoning-trace` — each sample produces a trace
+- `llm` — generates multiple samples
+
+## pattern structure
+
+```
+Question: What is the capital of Australia?
+
+Sample 1: "Australia is in Oceania. Sydney is the largest city.
+           But the capital is Canberra." → Canberra
+
+Sample 2: "Australia's government is in Canberra, which was
+           purpose-built as the capital." → Canberra
+
+Sample 3: "The largest city is Sydney, which might be the
+           capital." → Sydney
+
+Majority vote: Canberra (2/3)
+Final answer: Canberra
+```
+
+## key characteristics
+
+- **embarrassingly parallel**: all samples independent
+- **temperature > 0**: requires stochastic sampling
+- **answer extraction**: must identify final answer in each trace
+- **voting mechanism**: typically majority, can be weighted
+
+## benchmark performance
+
+| benchmark | improvement over greedy CoT |
+|-----------|---------------------------|
+| arithmetic | +17.9% (GSM8K) |
+| commonsense | +11.0% (CommonsenseQA) |
+| symbolic | significant gains |
+
+## parameters
+
+| parameter | effect |
+|-----------|--------|
+| num_samples | more samples = higher accuracy, higher cost |
+| temperature | higher = more diverse samples |
+| voting method | majority, weighted, etc. |
+
+## cost analysis
+
+self-consistency is more expensive than single-path CoT:
+- linear cost increase with sample count
+- typically 5-40 samples used
+- parallelizable (latency ≈ single sample if concurrent)
+
+## limitations
+
+- requires extractable final answers
+- expensive for long generations
+- doesn't help if all paths fail similarly
+
+## sources
+
+- [Self-Consistency Improves Chain of Thought Reasoning](https://arxiv.org/abs/2203.11171) — original paper
+- [Reasoning with LM Prompting Survey](https://github.com/zjunlp/Prompt4ReasoningPapers) — comparison with other methods

package/dist/roles/architect/briefs/brains.replic/arc115.concept.lats-pattern.[article].md

@@ -0,0 +1,78 @@
+# lats-pattern (language agent tree search)
+
+## .what
+
+an advanced agent framework that combines tree-of-thoughts with monte carlo tree search (MCTS), using external feedback and learned value functions to guide exploration of action sequences.
+
+## .why
+
+LATS addresses limitations of both linear agents (no backtracking) and static tree search (no learning). by incorporating MCTS principles — selection, expansion, simulation, backpropagation — LATS can learn from failed trajectories and allocate search effort efficiently toward promising paths.
+
+## dependsOn
+
+- `tree-of-thoughts` — tree structure for exploration
+- `agentic-loop` — action execution
+- `reflexion-pattern` — learning from feedback
+
+## mcts components in LATS
+
+| component | implementation |
+|-----------|----------------|
+| selection | UCB1-guided node choice |
+| expansion | llm generates candidate actions |
+| simulation | execute action, observe result |
+| backpropagation | update values based on outcome |
+
+## pattern structure
+
+```
+        [Root State]
+             │
+    ┌────────┼────────┐
+    │        │        │
+ [A:0.6]  [B:0.8]  [C:0.4]  ← UCB1 selects B
+             │
+    ┌────────┼────────┐
+    │        │        │
+ [B1:0.7] [B2:0.9] [B3:0.5]  ← expand B, simulate
+             │
+          [success]
+             │
+         backpropagate +reward
+```
+
+## benchmark performance
+
+| benchmark | LATS performance |
+|-----------|-----------------|
+| HotPotQA | state-of-the-art among agent methods |
+| WebShop | improved over ReAct/Reflexion |
+| Programming | higher solve rates with search |
+
+## key innovations over ToT
+
+| aspect | ToT | LATS |
+|--------|-----|------|
+| exploration | static heuristic | learned UCB1 |
+| feedback | evaluation only | environment + reflection |
+| memory | none | experience buffer |
+| replanning | from scratch | informed by history |
+
+## computational cost
+
+LATS is more expensive than simpler methods:
+- multiple simulation trajectories
+- value function updates
+- but more sample-efficient than random exploration
+
+## when to use
+
+- complex multi-step tasks
+- sparse reward signals
+- when backtracking is valuable
+- sufficient compute budget
+
+## sources
+
+- [Language Agent Tree Search (LATS)](https://arxiv.org/abs/2310.04406) — original paper (ICML 2024)
+- [Understanding LLM Agent Planning Survey](https://arxiv.org/abs/2402.02716) — positions LATS in taxonomy