acra-cli 0.1.1__py3-none-any.whl

acra/graph/checkpoint.py

@@ -0,0 +1,85 @@
+import logging
+import os
+
+from acra import config
+from acra.config import SQLITE_DB_PATH
+
+logger = logging.getLogger(__name__)
+
+
+class GraphCheckpointManager:
+    """
+    LangGraph checkpoint abstraction.
+
+    Responsibilities:
+    - provide checkpoint saver for graph persistence
+    - support graph resumability
+    """
+
+    def __init__(self):
+        self.backend = os.getenv("CHECKPOINT_BACKEND", config.CHECKPOINT_BACKEND).lower()
+        self._backend_context = None
+        self.checkpointer = self._initialize_backend()
+        logger.info("Checkpoint backend initialized: %s", self.backend)
+
+    def _initialize_backend(self):
+        """Initialize LangGraph checkpoint saver based on configured backend."""
+        if self.backend == "sqlite":
+            try:
+                from langgraph.checkpoint.sqlite import SqliteSaver
+
+                db_path = str(SQLITE_DB_PATH)
+                os.makedirs(os.path.dirname(db_path), exist_ok=True)
+
+                logger.info("Using SQLite checkpoint: %s", db_path)
+                self._backend_context = SqliteSaver.from_conn_string(db_path)
+                return self._backend_context.__enter__()
+            except ImportError:
+                logger.warning(
+                    "SQLite backend not available. Install: pip install langgraph-checkpoint-sqlite. Falling back to memory saver."
+                )
+                return self._get_memory_saver()
+            except Exception as exc:
+                logger.error("Failed to initialize SQLite: %s. Using memory saver.", exc)
+                return self._get_memory_saver()
+
+        if self.backend == "postgres":
+            try:
+                from langgraph.checkpoint.postgres import PostgresSaver
+
+                connection_string = os.getenv(
+                    "POSTGRES_CONNECTION_STRING",
+                    "postgresql://user:password@localhost/omniagent",
+                )
+
+                logger.info("Using PostgreSQL checkpoint")
+                self._backend_context = PostgresSaver.from_conn_string(connection_string)
+                return self._backend_context.__enter__()
+            except ImportError:
+                logger.warning(
+                    "PostgreSQL backend not available. Install: pip install langgraph-checkpoint-postgres. Falling back to memory saver."
+                )
+                return self._get_memory_saver()
+            except Exception as exc:
+                logger.error("Failed to initialize PostgreSQL: %s. Using memory saver.", exc)
+                return self._get_memory_saver()
+
+        return self._get_memory_saver()
+
+    def _get_memory_saver(self):
+        """Get in-memory checkpoint saver (default/fallback)."""
+        from langgraph.checkpoint.memory import MemorySaver
+
+        logger.info("Using MemorySaver (in-memory checkpoints)")
+        return MemorySaver()
+
+    def __del__(self):
+        if self._backend_context is not None:
+            try:
+                self._backend_context.__exit__(None, None, None)
+            except Exception:
+                pass
+
+
+graph_checkpoint = GraphCheckpointManager()
+

acra/graph/conditional_edges.py

@@ -0,0 +1,103 @@
+from langgraph.graph import END
+
+from acra.graph.router import (
+    route_workflow
+)
+
+
+# conditional edge map
+
+CONDITIONAL_EDGE_MAP = {
+
+    "planner": "planner",
+
+    "researcher": "researcher",
+
+    "coder": "coder",
+
+    "executor": "executor",
+
+    "critic": "critic",
+
+    "memory": "memory",
+
+    "human": "human",
+
+    END: END
+}
+
+
+# register conditional edges
+
+def register_conditional_edges(
+    workflow
+):
+    """
+    Register routing logic
+    for all workflow nodes.
+    """
+
+    workflow.add_conditional_edges(
+
+        "planner",
+
+        route_workflow,
+
+        CONDITIONAL_EDGE_MAP
+    )
+
+    workflow.add_conditional_edges(
+
+        "researcher",
+
+        route_workflow,
+
+        CONDITIONAL_EDGE_MAP
+    )
+
+    workflow.add_conditional_edges(
+
+        "coder",
+
+        route_workflow,
+
+        CONDITIONAL_EDGE_MAP
+    )
+
+    workflow.add_conditional_edges(
+
+        "executor",
+
+        route_workflow,
+
+        CONDITIONAL_EDGE_MAP
+    )
+
+    workflow.add_conditional_edges(
+
+        "critic",
+
+        route_workflow,
+
+        CONDITIONAL_EDGE_MAP
+    )
+
+    workflow.add_conditional_edges(
+
+        "memory",
+
+        route_workflow,
+
+        CONDITIONAL_EDGE_MAP
+    )
+
+    workflow.add_conditional_edges(
+
+        "human",
+
+        route_workflow,
+
+        CONDITIONAL_EDGE_MAP
+    )
+
+    return workflow

acra/graph/edges.py

@@ -0,0 +1,85 @@
+from langgraph.graph import END
+
+
+# static edge 
+
+GRAPH_EDGES = {
+
+    "planner": [
+        "researcher",
+        "coder",
+        "human"
+    ],
+
+    "researcher": [
+        "coder"
+    ],
+
+    "coder": [
+        "executor"
+    ],
+
+    "executor": [
+        "critic",
+        "coder",
+        "human"
+    ],
+
+    "critic": [
+        "memory",
+        "coder",
+        "human"
+    ],
+
+    "memory": [
+        END
+    ],
+
+    "human": [
+        "coder",
+        END
+    ]
+}
+
+
+# validate transition
+
+def validate_transition(source: str, destination: str) -> bool:
+    """Returns True if the transition is explicitly defined OR destination is END."""
+    if destination == END:
+        return True
+    return destination in GRAPH_EDGES.get(source, [])
+
+
+# get next edges
+
+def get_next_nodes(
+    node_name: str
+):
+    """
+    Returns possible next nodes.
+    """
+
+    return GRAPH_EDGES.get(
+        node_name,
+        []
+    )
+
+
+# validate edges 
+
+def is_valid_transition(
+    source: str,
+    destination: str
+):
+    """
+    Validates graph transition.
+    """
+
+    return (
+        destination
+        in GRAPH_EDGES.get(
+            source,
+            []
+        )
+    )

acra/graph/graph_visualizer.py

@@ -0,0 +1,175 @@
+from pathlib import Path
+from typing import Optional
+
+from acra.graph.workflow import (
+    omniagent_graph
+)
+
+
+# graph visualizer
+
+class GraphVisualizer:
+    """
+    Responsibilities:
+    - visualize LangGraph workflow
+    - export Mermaid diagrams
+    - save workflow images
+    - support debugging/documentation
+    """
+
+    def __init__(self):
+
+        self.graph = omniagent_graph
+
+
+    # get mermaid
+
+    def get_mermaid(self) -> str:
+        """
+        Returns Mermaid graph definition.
+        """
+
+        try:
+
+            return (
+                self.graph
+                .get_graph()
+                .draw_mermaid()
+            )
+
+        except Exception as e:
+
+            return (
+                f"Failed to generate Mermaid: {e}"
+            )
+
+
+    # save mermaid
+
+    def save_mermaid(
+        self,
+        filepath: str
+    ) -> str:
+        """
+        Save Mermaid graph to file.
+        """
+
+        mermaid = self.get_mermaid()
+
+        Path(filepath).parent.mkdir(
+            parents=True,
+            exist_ok=True
+        )
+
+        with open(
+            filepath,
+            "w",
+            encoding="utf-8"
+        ) as file:
+
+            file.write(mermaid)
+
+        return filepath
+
+
+    # save png
+
+    def save_png(
+        self,
+        filepath: str
+    ) -> str:
+        """
+        Save workflow graph as PNG.
+
+        Requires:
+        grandalf
+        pygraphviz
+        OR LangGraph image support
+        """
+
+        try:
+
+            png_data = (
+
+                self.graph
+                .get_graph()
+                .draw_mermaid_png()
+
+            )
+
+            Path(filepath).parent.mkdir(
+                parents=True,
+                exist_ok=True
+            )
+
+            with open(
+                filepath,
+                "wb"
+            ) as file:
+
+                file.write(
+                    png_data
+                )
+
+            return filepath
+
+        except Exception as e:
+
+            raise RuntimeError(
+                f"PNG export failed: {e}"
+            )
+
+
+    # display mermaid
+
+    def print_graph(self):
+        """
+        Print Mermaid workflow.
+        """
+
+        print(
+            self.get_mermaid()
+        )
+
+
+    # export documentation
+
+    def export_documentation(
+        self,
+        filepath: str
+    ) -> str:
+        """
+        Export graph documentation.
+        """
+
+        mermaid = self.get_mermaid()
+
+        content = f"""
+# OMNIAGENT Workflow
+
+```mermaid
+{mermaid}
+```
+"""
+
+        Path(filepath).parent.mkdir(
+            parents=True,
+            exist_ok=True
+        )
+
+        with open(
+            filepath,
+            "w",
+            encoding="utf-8"
+        ) as file:
+
+            file.write(content)
+
+        return filepath
+
+
+# global visualizer 
+
+graph_visualizer = (
+    GraphVisualizer()
+)

acra/graph/nodes.py

@@ -0,0 +1,68 @@
+from acra.agents.planner.planner_agent import (
+    planner_agent
+)
+
+from acra.agents.researcher.researcher_agent import (
+    researcher_agent
+)
+
+from acra.agents.coder.coder_agent import (
+    coder_agent
+)
+
+from acra.agents.executor.executor_agent import (
+    executor_agent
+)
+
+from acra.agents.critic.critic_agent import (
+    critic_agent
+)
+
+from acra.agents.memory.memory_agent import (
+    memory_agent
+)
+
+from acra.agents.human.human_node import (
+    human_node
+)
+
+
+# node registry
+
+NODE_REGISTRY = {
+
+    "planner": planner_agent,
+
+    "researcher": researcher_agent,
+
+    "coder": coder_agent,
+
+    "executor": executor_agent,
+
+    "critic": critic_agent,
+
+    "memory": memory_agent,
+
+    "human": human_node,
+}
+
+
+# get nodes 
+
+def get_node(node_name: str):
+    """
+    Returns node function.
+    """
+
+    return NODE_REGISTRY.get(node_name)
+
+# list nodes
+
+def list_nodes():
+    """
+    Returns all available nodes.
+    """
+
+    return list(
+        NODE_REGISTRY.keys()
+    )

acra/graph/router.py

@@ -0,0 +1,69 @@
+import logging
+from langgraph.graph import END
+from acra.graph.edges import validate_transition
+
+
+# router 
+
+def route_workflow(state):
+    """
+    Central workflow router.
+
+    Reads state["next_agent"]
+    and returns the next graph node.
+    Enforces retry limits and validates transitions.
+    """
+
+    # Check retry limit
+    retry_count = state.get("retry_count", 0)
+    max_retries = state.get("max_retries", 5)
+    if retry_count >= max_retries:
+        logging.getLogger(__name__).warning(
+            "Max retries (%d) reached. Ending workflow.", max_retries
+        )
+        return END
+
+    next_agent = state.get(
+        "next_agent",
+        "end"
+    )
+
+    if not next_agent:
+
+        return END
+
+    if next_agent.lower() == "end":
+
+        return END
+
+    # Validate transition
+    current_agent = state.get("current_agent", "")
+    if not validate_transition(current_agent, next_agent):
+        logging.getLogger(__name__).warning(
+            "Unexpected transition from '%s' to '%s'", current_agent, next_agent
+        )
+        return END
+
+    return next_agent
+
+
+# route mapping
+
+ROUTE_MAPPING = {
+
+    "planner": "planner",
+
+    "researcher": "researcher",
+
+    "coder": "coder",
+
+    "executor": "executor",
+
+    "critic": "critic",
+
+    "memory": "memory",
+
+    "human": "human",
+
+    "end": END
+}

acra/graph/state.py

@@ -0,0 +1,93 @@
+from typing import List, Dict, Any
+
+from langgraph.graph import MessagesState
+
+
+class AgentState(MessagesState):
+    """Workflow state for OmniAgent.
+
+    TypedDict does not provide runtime defaults, so callers must read with
+    state.get(key, default) or populate fields explicitly when a node first
+    introduces them.
+    """
+
+    # USER INPUT
+
+    user_request: str
+    session_id: str
+
+    # PLANNING
+
+    plan: List[str]
+    current_step: str
+    completed_steps: List[str]
+
+    # RESEARCH
+
+    research_data: List[Any]
+    research_status: str
+    research_summary: str
+    research_sources: List[Any]
+    references: List[str]
+    implementation_recommendations: str
+    recommended_technologies: List[str]
+    security_considerations: List[str]
+    performance_considerations: List[str]
+    architecture_suggestions: List[str]
+
+    # CODE GENERATION
+
+    project_name: str
+    generated_files: Dict[str, str]
+    entry_point: str
+    coding_status: str
+    coding_explanation: str
+
+    # EXECUTION
+
+    execution_logs: str
+    execution_success: bool
+    execution_output: str
+    execution_status: str
+    execution_time: float
+
+    # ERROR HANDLING
+
+    error_message: str
+    retry_count: int
+    max_retries: int
+
+    # CRITIC / REVIEW
+
+    review_status: str
+    critic_feedback: str
+    critic_summary: str
+    quality_score: float
+    review_issues: List[Any]
+    security_issues: List[str]
+    improvement_suggestions: List[str]
+
+    # HUMAN-IN-THE-LOOP
+
+    approval_required: bool
+    approved: bool
+    human_feedback: str
+    interactive: bool
+
+    # MEMORY
+
+    memory_context: List[str]
+    memory_type: str
+    memory_stats: Dict[str, Any]
+    previous_attempts: List[Dict[str, Any]]
+    similar_failures: List[Any]
+
+    # WORKFLOW CONTROL
+
+    next_agent: str
+    workflow_status: str
+    current_agent: str
+
+    # OBSERVABILITY
+
+    token_usage: int