{"id":29222800,"url":"https://github.com/hankbesser/recursive-agents","last_synced_at":"2025-07-03T04:02:20.932Z","repository":{"id":301808104,"uuid":"1006642819","full_name":"hankbesser/recursive-agents","owner":"hankbesser","description":"A meta-framework for self-improving LLMs with transparent reasoning","archived":false,"fork":false,"pushed_at":"2025-07-03T02:33:26.000Z","size":9962,"stargazers_count":19,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-03T02:40:12.041Z","etag":null,"topics":["ai","langchain","llm","recursion","recursive","self-improvement"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hankbesser.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-22T17:52:09.000Z","updated_at":"2025-07-03T02:33:29.000Z","dependencies_parsed_at":"2025-07-03T02:40:13.437Z","dependency_job_id":null,"html_url":"https://github.com/hankbesser/recursive-agents","commit_stats":null,"previous_names":["hankbesser/recursive-companion","hankbesser/recursive-agents"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hankbesser/recursive-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hankbesser%2Frecursive-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hankbesser%2Frecursive-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hankbesser%2Frecursive-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hankbesser%2Frecursive-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hankbesser","download_url":"https://codeload.github.com/hankbesser/recursive-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hankbesser%2Frecursive-agents/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263256548,"owners_count":23438262,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","langchain","llm","recursion","recursive","self-improvement"],"created_at":"2025-07-03T04:02:20.162Z","updated_at":"2025-07-03T04:02:20.814Z","avatar_url":"https://github.com/hankbesser.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Recursive Agents 🔄\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Contributing](https://img.shields.io/badge/Contributing-Guidelines-blue.svg)](CONTRIBUTING.md)\n\n## A Meta-Framework for Self-Improving Agents\n\nRecursive Agents implements a **three-phase iterative refinement architecture** where LLM agents (instances of Classes) critique and improve their own outputs. Unlike single-pass systems, each agent automatically tracks its full revision history, making every decision inspectable and debuggable.\n\n![Sequence Flow](images/Sequence_Summary.svg)\n\n→ See the [Architecture Documentation](docs/RA_architecture.md) for detailed system design.\n\n### Why Recursive Agents?\n\n**See inside the thinking.*** While other frameworks show you what happened, RA shows you why. Every instance maintains a complete audit trail of its critique-revision cycles, stopping conditions, and decision rationale. This transparency is built-in, not bolted on.\n\n*Unlike single-shot responses, agents systematically refine their outputs by critiquing and improving their own work—thinking about their thinking.\n\n**Flexible template loading.** The `build_templates()` utility lets you compose analytical patterns: override just what changes (usually only initial system template per domain), apply overarching protocols to specific phases (usually throughout system templates in all realted domains for consistent behavior), or skip protocols entirely. System templates define WHO the agent is, user templates define WHAT task to perform, and protocols shape HOW to analyze—each layer independently configurable.\n\n### Why \"Companions\"?\n\nIn the Recursive Agents framework, we call our agent implementations\n\"Companions\" rather than \"Agents\" for clarity:\n\n- **Framework**: Recursive Agents (what the system does)\n- ***C***lasses: ***C***ompanions (what you work with)\n\n---\n\n## What Makes RA Unique\n\n| Code Pattern | Why It Matters | Rare in OSS? |\n|--------------|----------------|--------------|\n| **`Draft\\|LLM → Critique\\|LLM → Revision\\|LLM` chains built once** | Three-phase self-improvement is automatic - no manual wiring | ✓✓ |\n| **One `protocol_context.txt` feeds all system prompts** | Change reasoning style everywhere with one edit | ✓ |\n| **Templates live as `.txt` files on disk** | Git tracks prompt changes; hot-reload without restarting | ✓ |\n| **New expert domain = inherit BaseCompanion + point to template** | Three lines of code gets you a complete agent | ✓✓ |\n| **Every Companion instance  is itself an `agent()` or `RunnableLambda(agent)`** | Same object works standalone or in any framework | ✓ |\n| **Built-in `run_log` tracks all iterations** | See why decisions were made without adding instrumentation | ✓✓ |\n\n✓ = Uncommon in open source projects | ✓✓ = Very rare in open source projects\n\n---\n### Quick Clone\n\n```bash\n# Create conda environment\nconda create -n recursive-agents python=3.12 -y # (or python=3.13 -y)\nconda activate recursive-agents\n# Or using venv\n# python -m venv venv\n# source venv/bin/activate  \n\n# clone and install\ngit clone https://github.com/hankbesser/recursive-agents.git\ncd recursive-agents\npip install -e .  # or pip install . for non-editable\n# pip install -e .[all] for running the streamlit app and working with LangGraph in demo\n# pip install .[all] for non edittable version as above   \n```  \n---\n### Challenge: Ask Your Agentic Coding tool to Think Deeply about this Project\n\nHere's something fun - ask your favorite coding tool ( i.e. Claude Code in a terminal) the following input prompt in a new conversation.. It is very informal and you can tailor the structure (possibly more formal language if you are into that) but the TODO is pretty solid with this particular order:\n\n**\"Ok please think as deeply as possible about this project. Start with the README and docs folder to get a sense of it... now thinking as deeply as you possibly can, analyze the package. The main core engine is in core/chains.py - think deeply about this, giving every detail you can see from it and what it does. Then go to the package level in recursive_agents including template_load_utils.py and base.py and do the same deep thinking process. Then read the templates folder starting with the protocol, then system prompts (noting that protocol language won't leak as an aside), then the user prompts. Lastly, hit all files in the the demos folder- again, as deep of analysis as you can go.  It's good to get a deep grasp of this project. Thank you!\"**\n\n*The responses will not dissapoint.*\n\n---\n\n\n## Architecture: Clean Layers, Clear Purpose\n→ See the [Architecture Documentation](docs/RA_architecture.md)\n\n```text\nYour Code\n    ↓ imports\nrecursive_agents/        # Pick your companion\n    ├── base.py             # Standard: Marketing, Bug, Strategy, Generic\n    └── streamlit.py        # Same companions + live UI updates\n        ↓ inherits\ncore/chains.py              # The engine: 3-phase loop, convergence, history\n        ↓ uses\ntemplates/*.txt             # Hot-swappable prompts + protocol injection\n```\n**Where to Look (Separation of Concerns):**\n\n- **Engineers** → ```core/chains.py``` (how to build the chains, storage/caching/memory management, observability, iteration process, etc.)\n- **Users** → ```recursive_agents/base.py``` (picking companions)\n- **Context Engineers** → ```templates/``` folder + ```template_load_utils.py```\n- **UI Developers** → ```streamlit_app.py``` (progress containers)\n- *or any combination of these*\n\n**Tip:** Each module includes extensive docstrings and comments explaining design decisions, usage patterns, and implementation details. Start with the docstrings for a comprehensive understanding. \n\n\n---\n## Three Levels of Understanding\n\n### Level 1: Just Use It (5 minutes)\n```python\nfrom recursive_agents import MarketingCompanion\n\n# Create an agent - it's just a callable!\nagent = MarketingCompanion(\"gpt-4o-mini\")\n\n# Get a refined answer through automatic critique cycles\nanswer = agent(\"Why did engagement drop 30%...?\")\nprint(answer)  # Final, refined analysis after self-critique\n\n# Note: agent(\"...\") is the same as agent.loop(\"...\")\n# The __call__ method is an alias for loop()\n# This makes companions work as simple callables in any framework!\n\n# Want to see the thinking process? It's all there:\nprint(f\"Iterations: {len(agent.run_log)}\")\nprint(f\"Final critique: {agent.run_log[-1]['critique']}\")\n\n# Get beautifully formatted thinking history\nprint(agent.transcript_as_markdown())\n# Outputs:\n# ### Iteration 1\n# **Draft**: [Initial analysis...]\n# **Critique**: [What could be improved...]\n# **Revision**: [Enhanced analysis...]\n# (continues for each iteration)\n```\n\n### Level 2: Compose \u0026 Customize (30 minutes)\n```python\n# 1. Configure companions for different use cases\nfast_draft = MarketingCompanion(\n    temperature=0.9,          # More creative\n    max_loops=1,             # Single pass for speed\n    clear_history=True       # Don't retain context\n)\n\nthoughtful = MarketingCompanion(\n    llm=\"gpt-4.1-mini\"\n    temperature=0.3,          # More focused\n    max_loops=5,             # Deep refinement\n    similarity_threshold=0.99 # Only stop on near-identical\n)\n\n# 2. Different ways to get results\nsimple_answer = fast_draft(\"Quick take on our Q3 performance...\")\n\n# Get both answer and thinking history\nanswer, thinking = thoughtful.loop(\"Deep analysis of Q3 performance...\")\nprint(f\"Went through {len(thinking)} iterations\")\nprint(thoughtful.transcript_as_markdown())  # See the evolution\n\n# 3. Use verbose mode to watch thinking live\ndebug_companion = BugTriageCompanion(verbose=True)\nresult = debug_companion(\"Users can't upload files \u003e10MB...\")\n# Prints: USER INPUT, INITIAL DRAFT, CRITIQUE #1, REVISION #1, etc.\n```\n### Level 3: Extend the Framework (2 hours)\n\n```python\n# Step 1: Create your domain template (templates/legal_initial_sys.txt)\n\"\"\"\n{context}  # Protocol automatically injected\n\nYou are a Legal Analysis Companion specializing in contract review,\ncompliance assessment, and risk evaluation. Focus on:\n- Identifying potential legal liabilities\n- Highlighting ambiguous language\n- Suggesting protective clauses\n\"\"\"\n\n# Step 2: Create your companion class (just 4 lines!)\n\nfrom recursive_agents.core.chains import BaseCompanion\nfrom recursive_agents.template_load_utils import build_templates\n\n# probably best to do in recusrive_companion/base.py with other Companions\nLEGAL_TEMPLATES = build_templates(initial_sys=\"legal_initial_sys\")\nclass LegalCompanion(BaseCompanion):\n    TEMPLATES = LEGAL_TEMPLATES\n    SIM_THRESHOLD = 0.99  # Legal requires higher precision\n    MAX_LOOPS = 4         # Thorough analysis for legal matters\n\n# Step 3: Use it immediately\nlegal = LegalCompanion()\nanalysis = legal(\"Review this SaaS agreement for potential risks...\")\n\n# Access everything just like built-in companions\nprint(f\"Iterations until convergence: {len(legal.run_log)}\")\nprint(legal.transcript_as_markdown())  # Full audit trail for compliance!\n```\n## Quick Start - Full Streamlit App\n\n\n```bash\nexport OPENAI_API_KEY=\"sk-...\" # in terminal\n# For Jupyter/Python (more secure):\n# Create .env file with:\n# OPENAI_API_KEY=\"sk-...\"\n# Then in your code:\n# from dotenv import load_dotenv\n# load_dotenv()\n```\n\n### Run the Complete Streamlit Application\n```bash\nstreamlit run streamlit_app.py\n```\n\u003ca href=\"images/Streamlit_App_Screenshot.png\"\u003e\n    \u003cimg src=\"images/Streamlit_App_Screenshot.png\" width=\"890\" height=\"450\"\u003e\n\u003c/a\u003e\n\n**You get a full interactive application:**\n- Select any companion type from the dropdown\n- Adjust features in side bar\n- Enter your prompt and watch the AI refine its response\n- System templates and protocol viewer (updated when changes made in `templates/` and app reloads)\n- See critique-revision cycles happen in real-time\n- View cosine similarity scores update live\n\n\n\nThis is a full testing and observability app included with the framework.\n\n---\n\n## Why This Architecture Matters\n\n1. **Mathematical Convergence \u003e Arbitrary Limits**\n    - Not \"stop after 3 tries\"\n    - Stop when `cosine_from_embeddings(revision[n-1], revision[n]) \u003e 0.98`\n2. **Companions as Callables = Composability**\n- Works in Jupyter: `agent(\"question\")`\n- Works with LangGraph: `RunnableLambda(agent)`\n- Works in Streamlit: Live visualization of critique-revision cycles!\n3. **Templates as Data = Evolution Without Refactoring**\n- Change prompts in production\n- A/B test different protocols\n- Domain experts can contribute without coding\n\n---\n## Multi-Agent Orchestration\n\n#### **Raw Python** (Sequential with Full Observability):\n- [multi agent RA notebook ](demos/multi_agent_raw_ra_demo.ipynb)\n- [multi agent RA pyton file ](demos/multi_agent_raw_ra_demo.py)\n```python\nfrom recursive_agents.base import MarketingCompanion, BugTriageCompanion, StrategyCompanion\n\nproblem = \"App crashes on upload, users leaving bad reviews...\"\n\n# Each agent analyzes independently\nmkt = MarketingCompanion()\nbug = BugTriageCompanion()\nstrategy = StrategyCompanion()\n\nmkt_view = mkt(problem)\nbug_view = bug(problem)\n\n# Combine insights\ncombined = f\"Marketing: {mkt_view}\\n\\nEngineering: {bug_view}\"\naction_plan = strategy(combined)\n\n# Full introspection available for each agent\nprint(f\"Marketing iterations: {len(mkt.run_log)}\")\nprint(f\"Engineering iterations: {len(bug.run_log)}\")\nprint(f\"Strategy iterations: {len(strategy.run_log)}\")\n\n# See why strategy reached its conclusion\nprint(strategy.transcript_as_markdown())\n```\n\n#### **LangGraph** (Parallel Execution + RA Transparency):\n- [multi agent RA callable / LangGraph notebook ](demos/multi_agent_langgraph_demo.ipynb)\n- [multi agent RA callable / LangGraph python file ](demos/multi_agent_langgraph_demo.py)\n\n```python\nfrom langchain_core.runnables import RunnableLambda\nfrom langgraph.graph import StateGraph\nfrom typing import TypedDict\n\n# Same companions work as LangGraph nodes!\n# mkt, bug instances from raw RA example above\nmkt_node = RunnableLambda(mkt)\neng_node = RunnableLambda(bug)\nstrategy_node = RunnableLambda(strategy)\n\n# Simple merge function\nmerge_node = RunnableLambda(\n    lambda d: f\"Marketing: {d['marketing']}\\n\\nEngineering: {d['engineering']}\"\n)\n\n# Define the state schema for LangGraph\nclass GraphState(TypedDict):\n    input: str\n    marketing: str\n    engineering: str\n    merged: str\n    final_plan: str\n\n# Build parallel workflow\n# No extra prompts, no schema gymnastics: simply passing text between the callables the classes already expose.\ngraph = StateGraph(GraphState)\ngraph.add_node(\"marketing_agent\",   lambda state: {\"marketing\": mkt_node.invoke(state[\"input\"])})\ngraph.add_node(\"engineering_agent\", lambda state: {\"engineering\": eng_node.invoke(state[\"input\"])})\ngraph.add_node(\"merge_agent\",       lambda state: {\"merged\": merge_node.invoke(state)})\ngraph.add_node(\"strategy_agent\",    lambda state: {\"final_plan\": plan_node.invoke(state[\"merged\"])})\n\ngraph.add_edge(\"marketing_agent\", \"merge_agent\")\ngraph.add_edge(\"engineering_agent\", \"merge_agent\")\ngraph.add_edge(\"merge_agent\", \"strategy_agent\")\n\ngraph.add_edge(\"__start__\", \"marketing_agent\")\ngraph.add_edge(\"__start__\", \"engineering_agent\")\ngraph.set_finish_point(\"strategy_agent\")\nworkflow = graph.compile()\n\n# Run workflow\nresult = workflow.invoke({\"input\": problem})\n\n# RA's thinking history still available!\nprint(mkt.transcript_as_markdown())     # Full marketing analysis\nprint(bug.transcript_as_markdown())     # Full engineering analysis\nprint(strategy.transcript_as_markdown()) # How strategy synthesized both\n```\nFor detailed comparison with LangGraph capabilities, see [LangGraph_comparison_compliment](docs/LangGraph_RA_comp.md).\n\n---\n## Production Features\n\n#### Observability and Flexibility\n\n- **Verbose mode**: prints every phase of thinking live\n- **Transcript capture**: return full run_log for debugging along with the final analysis (the instatiated object will have have it own run_log though)\n- **Standard logging**: Integration-ready\n- **Streamlit App**: visualze all live previews, testing \n\n- **Smart caching**: Single embeddings client\n- **Early exit**: Stop when converged, not exhausted\n\n- **Any OpenAI model**: \"gpt-4o-mini\", \"gpt-4.1\", custom endpoints\n- **Configurable everything**: Per-instance overrides\n- **Template hot-reload:** Change prompts without code\n\n---\n\n## The Strategic Decomposition Protocol\n\nRead ```templates/protocol_context.txt``` to see the structured reasoning framework that guides agents through:\n\n- Multi-layered problem analysis\n- Iterative pattern recognition\n- Systematic refinement cycles\n\nThis structured approach to recursive problem decomposition consistently outperforms single-pass analysis.\n\n---\n\n\n### Creating Your Own Companion\n\n### 1. Write your\n```text\n# templates/financial_initial_sys.txt\n{context}  # Protocol automatically injected\n\nYou are a Financial Analysis Companion. Focus on:\n- Cash flow patterns and anomalies\n- Risk indicators and market conditions\n- Regulatory compliance implications\n```\n\n### 2. Create the companion class\n```python\nyour_app/base.py\nfrom recursive_agents.core.chains import BaseCompanion\nfrom recursive_agents.template_load_utils import build_templates\n\nFINANCE_TEMPLATES = build_templates(initial_sys=\"financial_initial_sys\")\nclass FinancialCompanion(BaseCompanion):\n    TEMPLATES = FINANCE_TEMPLATES\n    MODEL_NAME = \"gpt-4.1-mini\"\n    MAX_LOOPS = 4  # Financial analysis needs thoroughness\n    TEMPERATURE = 0.3  # Lower temperature for numerical precision\n```\n\n### 3. Use it anywhere\n```python\nfin = FinancialCompanion()\n\n# note: callable - __call__ is an alias for loop()\nanalysis = fin(\"Q3 revenue variance exceeds 2 standard deviations\") \n```\n---\n\n\n*Agents that refine their responses through iteration, integrated seamlessly into your existing code.*\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get started.\n\n## Future Explorations\n\nThe Recursive Agents framework opens fascinating research directions:\n\n- Advanced convergence analysis beyond embeddings / cosine similarity\n- Richer integration patterns with agentic frameworks\n- Extended observability for multi-loop systems\n\nWe're particularly interested in collaborations exploring how recursive\npatterns emerge across different domains and scales.\n\n\n\n## Bonus Section: This README's design philosophy\n\n1. **Three-level structure** mirrors the codebase organization\n2. **Technical depth** with actual code snippets and architecture diagrams\n3. **Clear separation** of who should look where (users → base.py, engineers → chains.py)\n4. **Focus on observability** with real implementation details for testing and visualzing in the prvoided full scale Streamlit app\n5. **Protocol + Templates** flexible composition for different applications\n6. **Clean examples** demonstrating the \"companions as callables\" pattern\n7. **Practical guidance** for extending the framework\n8. **Visual learning** - Sequence diagram up front, architecture docs linked\n\n#### The goal: Show what makes Recursive Agents different and how to use it effectively.\n\n---\n\n## Built Through Collaboration\n\nThis framework emerged from intensive human-AI collaboration over 3 weeks:\n- Solo developer working with multiple LLMs\n- Built using the very patterns it now enables  \n- The architecture mirrors the discovery process itself\n\nThe rapid development was possible because the framework design emerged naturally from the recursive dialogue process—we were building what we were already doing. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhankbesser%2Frecursive-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhankbesser%2Frecursive-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhankbesser%2Frecursive-agents/lists"}