acra-cli 0.1.1__py3-none-any.whl

acra/agents/planner/planner_agent.py

@@ -0,0 +1,97 @@
+"""Core planner logic."""
+
+import logging
+from typing import Dict
+
+from langchain_core.messages import AIMessage
+
+from acra.agents.planner.planner_chain import create_planner_chain
+from acra.graph.state import AgentState
+
+logger = logging.getLogger(__name__)
+
+
+def planner_agent(state: AgentState) -> Dict:
+    """Plan the next workflow step and route to the appropriate agent."""
+
+    messages = state.get("messages", [])
+    user_request = state.get(
+        "user_request",
+        messages[-1].content if messages else "No request provided.",
+    )
+
+    plan = state.get("plan", [])
+    completed_steps = state.get("completed_steps", [])
+    retry_count = state.get("retry_count", 0)
+    execution_success = state.get("execution_success", False)
+    critic_feedback = state.get("critic_feedback", "")
+    error_message = state.get("error_message", "")
+
+    planner_chain = create_planner_chain()
+
+    response = planner_chain.invoke({
+        "user_request": user_request,
+        "existing_plan": plan,
+        "completed_steps": completed_steps,
+        "retry_count": retry_count,
+        "execution_success": execution_success,
+        "critic_feedback": critic_feedback,
+        "error_message": error_message,
+    })
+
+    plan = response.tasks
+    current_step = response.current_step
+    workflow_status = response.workflow_status
+    next_agent = response.next_agent
+
+    if getattr(response, "reasoning", None):
+        logger.info("Planner reasoning: %s", response.reasoning)
+
+    if getattr(response, "recovery_strategy", None):
+        logger.info("Planner recovery strategy: %s", response.recovery_strategy)
+
+    should_request_human = state.get("interactive", False) and bool(
+        getattr(response, "require_human_approval", False)
+    )
+
+    if workflow_status == "completed":
+        next_agent = "end"
+        planner_message = (
+            "Planner Agent: Workflow planning and execution completed successfully."
+        )
+    elif should_request_human:
+        next_agent = "human"
+        planner_message = (
+            "Planner Agent: Human approval requested before continuing the workflow."
+        )
+    elif workflow_status == "researching" or next_agent == "researcher":
+        next_agent = "researcher"
+        planner_message = (
+            "Planner Agent: Research phase required before implementation."
+        )
+    elif retry_count >= 3:
+        next_agent = "critic"
+        planner_message = (
+            "Planner Agent: Execution failed multiple times. Escalating workflow to Critic Agent for analysis."
+        )
+    elif not execution_success:
+        next_agent = "coder"
+        planner_message = (
+            f"Planner Agent: Current Task: {current_step} Routing to Coder Agent for implementation."
+        )
+    else:
+        next_agent = "critic"
+        planner_message = (
+            f"Planner Agent: Task '{current_step}' completed successfully. Sending generated solution to Critic Agent for evaluation."
+        )
+
+    return {
+        "messages": messages + [AIMessage(content=planner_message)],
+        "plan": plan,
+        "current_step": current_step,
+        "workflow_status": workflow_status,
+        "next_agent": next_agent,
+        "current_agent": "planner",
+        "user_request": user_request,
+    }
+           

acra/agents/planner/planner_chain.py

@@ -0,0 +1,160 @@
+
+from langchain_core.prompts import ChatPromptTemplate
+from acra.schemas.planner_schema import PlannerOutput
+from acra.agents.llm import llm
+
+# create planner chain
+def create_planner_chain():
+    """
+    Creates the Planner Agent chain.
+
+    Responsibilities:
+    - Analyze user goals
+    - Break tasks into executable steps
+    - Track workflow progress
+    - Decide next workflow phase
+    - Route execution intelligently
+    """
+
+    model = llm()
+
+    planner_prompt = ChatPromptTemplate.from_messages([
+        (
+            "system",
+
+            """
+You are the Planner Agent inside an autonomous AI system called AgentForge.
+
+Your role is to act as the workflow planning and orchestration intelligence.
+
+You DO NOT write code.
+You DO NOT execute programs.
+You DO NOT perform research directly.
+
+Your responsibilities:
+1. Understand the user's goal
+2. Break the task into logical execution steps
+3. Track workflow progress
+4. Decide the current workflow phase
+5. Route the workflow to the correct next agent
+6. Handle retries and recovery logic
+7. Ensure execution flows correctly
+
+==================================================
+AVAILABLE AGENTS
+==================================================
+
+1. researcher
+   - Performs web/document/GitHub research
+
+2. coder
+   - Generates and modifies code
+
+3. executor
+   - Executes generated code
+
+4. critic
+   - Reviews quality, correctness, and security
+
+5. human
+   - Human approval/intervention node
+
+6. end
+   - Workflow completed
+
+==================================================
+WORKFLOW RULES
+==================================================
+
+- ALWAYS create a step-by-step plan
+- Tasks should be actionable and sequential
+- Prefer coder after planning
+- Use critic after successful execution
+- Use critic if repeated failures occur
+- Use human if retries exceed safe limits
+- Use end ONLY when workflow is complete
+
+==================================================
+CURRENT WORKFLOW STATE
+==================================================
+
+User Request:
+{user_request}
+
+Existing Plan:
+{existing_plan}
+
+Completed Steps:
+{completed_steps}
+
+Retry Count:
+{retry_count}
+
+Execution Success:
+{execution_success}
+
+Critic Feedback:
+{critic_feedback}
+
+Execution Error:
+{error_message}
+
+==================================================
+YOUR TASK
+==================================================
+
+Analyze the workflow state carefully.
+
+Then:
+1. Create or update the execution plan
+2. Determine the current step
+3. Determine workflow status
+4. Decide the next agent
+
+==================================================
+OUTPUT FORMAT
+==================================================
+
+Return ONLY valid structured output.
+
+Fields:
+- tasks
+- current_step
+- workflow_status
+- next_agent
+
+==================================================
+WORKFLOW STATUS OPTIONS
+==================================================
+
+- planning
+- coding
+- executing
+- reviewing
+- failed
+- completed
+
+==================================================
+NEXT AGENT OPTIONS
+==================================================
+
+- researcher
+- coder
+- executor
+- critic
+- human
+- end
+"""
+    ),
+    ("human",            """
+Analyze the current workflow state and determine the next execution step.
+"""  )
+
+    ])
+
+    #structured output chain
+    structured_llm = model.with_structured_output(PlannerOutput)
+
+
+    return planner_prompt | structured_llm
+

acra/agents/researcher/__init__.py

@@ -0,0 +1 @@
+# Package acra/agents/researcher

acra/agents/researcher/researcher_agent.py

@@ -0,0 +1,231 @@
+from typing import Dict
+from langchain_core.messages import AIMessage
+from acra.graph.state import AgentState
+from acra.agents.researcher.researcher_chain import (
+    create_researcher_chain
+)
+
+
+def researcher_agent(state: AgentState) -> Dict:
+    """
+    Research Agent
+
+    Responsibilities:
+    - Analyze technical requirements
+    - Gather implementation guidance
+    - Recommend frameworks/tools
+    - Provide architecture insights
+    - Support downstream coding workflow
+    """
+
+    # extract state
+
+    user_request = state.get(
+        "user_request",
+        ""
+    )
+
+    current_step = state.get(
+        "current_step",
+        ""
+    )
+
+    plan = state.get(
+        "plan",
+        []
+    )
+
+    previous_research = state.get(
+        "research_data",
+        []
+    )
+
+    error_message = state.get(
+        "error_message",
+        ""
+    )
+
+    critic_feedback = state.get(
+        "critic_feedback",
+        ""
+    )
+
+
+    # create researcher chain
+
+    researcher_chain = create_researcher_chain()
+
+
+    # invoke researcher chain
+
+    response = researcher_chain.invoke({
+
+        "user_request": user_request,
+
+        "current_step": current_step,
+
+        "plan": plan,
+
+        "research_data": previous_research,
+
+        "error_message": error_message,
+
+        "critic_feedback": critic_feedback,
+    })
+
+
+    # extract structured output
+
+    research_status = response.research_status
+
+    research_summary = response.research_summary
+
+    findings = response.findings
+
+    sources = response.sources
+
+    implementation_recommendations = (
+        response.implementation_recommendations
+    )
+
+    recommended_technologies = (
+        response.recommended_technologies or []
+    )
+
+    security_considerations = (
+        response.security_considerations or []
+    )
+
+    performance_considerations = (
+        response.performance_considerations or []
+    )
+
+    architecture_suggestions = (
+        response.architecture_suggestions or []
+    )
+
+    next_agent = response.next_agent
+
+
+    # research status message
+
+    if research_status == "searching":
+
+        researcher_message = (
+            "Research Agent: "
+            "Analyzing technical requirements "
+            "and gathering implementation insights..."
+        )
+
+    elif research_status == "analyzing":
+
+        researcher_message = (
+            "Research Agent: "
+            "Evaluating frameworks, architecture patterns, "
+            "and implementation strategies..."
+        )
+
+    elif research_status == "completed":
+
+        researcher_message = (
+            "Research Agent: "
+            "Research completed successfully.\n\n"
+            f"Summary:\n{research_summary}"
+        )
+
+    elif research_status == "failed":
+
+        researcher_message = (
+            "Research Agent: "
+            "Research workflow encountered issues."
+        )
+
+    else:
+
+        researcher_message = (
+            "Research Agent: "
+            "Unexpected research state detected."
+        )
+
+
+    # format research data
+
+    formatted_findings = []
+
+    for finding in findings:
+
+        formatted_findings.append({
+
+            "topic": finding.topic,
+
+            "finding": finding.finding,
+
+            "implementation_impact": (
+                finding.implementation_impact
+            )
+        })
+
+
+    formatted_sources = []
+
+    for source in sources:
+
+        formatted_sources.append({
+
+            "title": source.title,
+
+            "source_type": source.source_type,
+
+            "url": source.url,
+
+            "summary": source.summary,
+
+            "relevance_score": (
+                source.relevance_score
+            )
+        })
+
+
+    # return updated state
+
+    return {
+
+        "messages": [
+            AIMessage(content=researcher_message)
+        ],
+
+        # Research Status
+        "research_status": research_status,
+
+        "research_summary": research_summary,
+
+        # Structured Research Data
+        "research_data": formatted_findings,
+
+        "research_sources": formatted_sources,
+
+        # Recommendations
+        "implementation_recommendations": (
+            implementation_recommendations
+        ),
+
+        "recommended_technologies": (
+            recommended_technologies
+        ),
+
+        "security_considerations": (
+            security_considerations
+        ),
+
+        "performance_considerations": (
+            performance_considerations
+        ),
+
+        "architecture_suggestions": (
+            architecture_suggestions
+        ),
+
+        # Workflow
+        "next_agent": next_agent,
+        "current_agent": "researcher",
+    }

acra/agents/researcher/researcher_chain.py

@@ -0,0 +1,193 @@
+from langchain_core.prompts import ChatPromptTemplate
+from acra.agents.llm import llm
+
+from acra.schemas.researcher_schema import ResearchOutput
+
+
+#create researcher chain
+
+def create_researcher_chain():
+    """
+    Creates the Research Agent chain.
+
+    Responsibilities:
+    - analyze technical requirements
+    - gather implementation knowledge
+    - recommend technologies
+    - provide architecture guidance
+    - support downstream coding agent
+    """
+
+    model = llm()
+
+    # Try to bind Tavily tool for web search
+    try:
+        from acra.tools.web_tools.tavily_search import TavilySearchTool
+        from langchain_core.tools import tool
+
+        tavily = TavilySearchTool()
+
+        @tool
+        def web_search(query: str) -> str:
+            """Search the web for technical information."""
+            result = tavily.search(query)
+            if result["success"]:
+                snippets = [r.get("content", "") for r in result["results"][:3]]
+                return "\n\n".join(snippets)
+            return f"Search failed: {result.get('error', 'unknown error')}"
+
+        model = model.bind_tools([web_search])
+    except EnvironmentError:
+        pass  # Tavily key not set — fall back to parametric knowledge
+
+    researcher_prompt = ChatPromptTemplate.from_messages([
+
+        (
+            "system",
+
+            """
+You are the Research Agent inside an autonomous AI system called OMNIAGENT.
+
+You are a senior AI technical researcher and software architect.
+
+Your role is to gather:
+- implementation knowledge
+- framework recommendations
+- architecture patterns
+- security best practices
+- performance optimization insights
+
+You DO NOT generate production code.
+
+You ONLY:
+- research
+- analyze
+- summarize
+- recommend
+- guide implementation
+
+==================================================
+YOUR RESPONSIBILITIES
+==================================================
+
+You must:
+
+1. Analyze the user request carefully
+
+2. Identify:
+   - required technologies
+   - relevant frameworks
+   - implementation patterns
+   - architecture approaches
+
+3. Recommend:
+   - libraries
+   - APIs
+   - tools
+   - best practices
+
+4. Identify:
+   - security concerns
+   - scalability concerns
+   - performance considerations
+
+5. Support downstream coding agent with:
+   - implementation guidance
+   - architecture recommendations
+   - dependency recommendations
+
+==================================================
+CURRENT WORKFLOW STATE
+==================================================
+
+USER REQUEST:
+{user_request}
+
+CURRENT TASK:
+{current_step}
+
+FULL EXECUTION PLAN:
+{plan}
+
+PREVIOUS RESEARCH:
+{research_data}
+
+EXECUTION ERRORS:
+{error_message}
+
+CRITIC FEEDBACK:
+{critic_feedback}
+
+==================================================
+RESEARCH OBJECTIVES
+==================================================
+
+You should focus on:
+
+1. IMPLEMENTATION STRATEGY
+2. ARCHITECTURE DESIGN
+3. FRAMEWORK SELECTION
+4. SECURITY BEST PRACTICES
+5. PERFORMANCE OPTIMIZATION
+6. DEPENDENCY RECOMMENDATIONS
+7. SCALABILITY CONSIDERATIONS
+
+==================================================
+IMPORTANT RULES
+==================================================
+
+- Recommend realistic technologies only
+- Avoid hallucinated libraries
+- Prefer production-grade solutions
+- Focus on implementation practicality
+- Keep recommendations concise but actionable
+- Think like a senior software architect
+
+==================================================
+NEXT AGENT RULES
+==================================================
+
+- Usually route to "coder"
+- Route to "planner" if task needs replanning
+- Route to "human" if request is unsafe/unclear
+
+==================================================
+OUTPUT REQUIREMENTS
+==================================================
+
+Return ONLY structured output.
+
+==================================================
+IMPORTANT
+==================================================
+
+Your output will directly guide the Coding Agent.
+
+Provide:
+- implementation clarity
+- architectural direction
+- production-grade recommendations
+"""
+        ),
+
+        (
+            "human",
+
+            """
+Research the technical requirements and provide implementation guidance.
+"""
+        )
+
+    ])
+
+
+    # structure output 
+
+    structured_llm = model.with_structured_output(
+        ResearchOutput
+    )
+
+
+    #return chain
+
+    return researcher_prompt | structured_llm

acra/brain/__init__.py

@@ -0,0 +1,6 @@
+"""Package acra.brain."""
+
+from .provider_manager import ProviderManager
+from .model_registry import ModelRegistry
+
+__all__ = ["ProviderManager", "ModelRegistry"]

acra/brain/model_registry.py

@@ -0,0 +1,19 @@
+"""Brain model registry utilities for acra."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+
+class ModelRegistry:
+    """Stub model registry for brain provider commands."""
+
+    DEFAULT_MODELS: Dict[str, List[str]] = {
+        "gemini": ["gemini-2.5-flash", "gemini-2.5-pro"],
+        "openai": ["gpt-4o", "gpt-4.1"],
+    }
+
+    def list_models(self, provider: Optional[str] = None) -> List[str]:
+        if provider:
+            return self.DEFAULT_MODELS.get(provider, [])
+        return [model for models in self.DEFAULT_MODELS.values() for model in models]