atlas-chat 0.1.0__py3-none-any.whl

atlas/__init__.py

@@ -0,0 +1,40 @@
+"""
+Atlas - Full-stack LLM chat interface with MCP integration.
+
+This package provides both a Python API for programmatic access and
+CLI tools for interacting with LLMs.
+
+Example usage:
+    from atlas import AtlasClient, ChatResult
+
+    client = AtlasClient()
+    result = await client.chat("Hello, world!")
+    print(result.message)
+
+CLI tools (after pip install):
+    atlas-chat "Your prompt here" --model gpt-4o
+    atlas-server --port 8000
+"""
+
+from atlas.version import VERSION
+
+__version__ = VERSION
+__all__ = [
+    "AtlasClient",
+    "ChatResult",
+    "VERSION",
+    "__version__",
+]
+
+
+def __getattr__(name: str):
+    """Lazy import to avoid loading heavy dependencies at module import time."""
+    if name == "AtlasClient":
+        from atlas.atlas_client import AtlasClient
+        globals()["AtlasClient"] = AtlasClient  # Cache for subsequent accesses
+        return AtlasClient
+    if name == "ChatResult":
+        from atlas.atlas_client import ChatResult
+        globals()["ChatResult"] = ChatResult  # Cache for subsequent accesses
+        return ChatResult
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

atlas/application/__init__.py

@@ -0,0 +1,7 @@
+"""Application layer - business logic and use cases."""
+
+from .chat.service import ChatService
+
+__all__ = [
+    "ChatService",
+]

atlas/application/chat/__init__.py

@@ -0,0 +1,7 @@
+"""Chat application service."""
+
+from .service import ChatService
+
+__all__ = [
+    "ChatService",
+]

atlas/application/chat/agent/__init__.py

@@ -0,0 +1,10 @@
+# Agent loop package exports
+
+from .factory import AgentLoopFactory as AgentLoopFactory
+from .protocols import AgentContext as AgentContext
+from .protocols import AgentEvent as AgentEvent
+from .protocols import AgentEventHandler as AgentEventHandler
+from .protocols import AgentLoopProtocol as AgentLoopProtocol
+from .protocols import AgentResult as AgentResult
+from .react_loop import ReActAgentLoop as ReActAgentLoop
+from .think_act_loop import ThinkActAgentLoop as ThinkActAgentLoop

atlas/application/chat/agent/act_loop.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from atlas.interfaces.llm import LLMProtocol
+from atlas.interfaces.tools import ToolManagerProtocol
+from atlas.modules.prompts.prompt_provider import PromptProvider
+
+from ..utilities import error_handler, tool_executor
+from .protocols import AgentContext, AgentEvent, AgentEventHandler, AgentLoopProtocol, AgentResult
+
+
+class ActAgentLoop(AgentLoopProtocol):
+    """Pure action agent loop - just execute tools in a loop until done.
+
+    No explicit reasoning or observation steps. The LLM directly decides which
+    tools to call and when to finish. Fastest strategy with minimal overhead.
+
+    Exit conditions:
+    - LLM calls the "finished" tool with a final_answer
+    - No tool calls returned (LLM provides text response)
+    - Max steps reached
+    """
+
+    def __init__(
+        self,
+        *,
+        llm: LLMProtocol,
+        tool_manager: Optional[ToolManagerProtocol],
+        prompt_provider: Optional[PromptProvider],
+        connection: Any = None,
+        config_manager=None,
+    ) -> None:
+        self.llm = llm
+        self.tool_manager = tool_manager
+        self.prompt_provider = prompt_provider
+        self.connection = connection
+        self.config_manager = config_manager
+        self.skip_approval = False
+
+    def _extract_finished_args(self, tool_calls: List[Dict[str, Any]]) -> Optional[str]:
+        """Extract final_answer from finished tool call if present."""
+        try:
+            for tc in tool_calls:
+                f = tc.get("function") if isinstance(tc, dict) else None
+                if f and f.get("name") == "finished":
+                    raw_args = f.get("arguments")
+                    if isinstance(raw_args, str):
+                        try:
+                            args = json.loads(raw_args)
+                            return args.get("final_answer")
+                        except Exception:
+                            return None
+                    if isinstance(raw_args, dict):
+                        return raw_args.get("final_answer")
+            return None
+        except Exception:
+            return None
+
+    async def run(
+        self,
+        *,
+        model: str,
+        messages: List[Dict[str, Any]],
+        context: AgentContext,
+        selected_tools: Optional[List[str]],
+        data_sources: Optional[List[str]],
+        max_steps: int,
+        temperature: float,
+        event_handler: AgentEventHandler,
+    ) -> AgentResult:
+        await event_handler(AgentEvent(type="agent_start", payload={"max_steps": max_steps, "strategy": "act"}))
+
+        steps = 0
+        final_answer: Optional[str] = None
+
+        # Define the "finished" control tool
+        finished_tool_schema = {
+            "type": "function",
+            "function": {
+                "name": "finished",
+                "description": "Call this when you have completed the task and are ready to provide a final answer to the user.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "final_answer": {
+                            "type": "string",
+                            "description": "The final response to provide to the user",
+                        },
+                    },
+                    "required": ["final_answer"],
+                    "additionalProperties": False,
+                },
+            },
+        }
+
+        while steps < max_steps and final_answer is None:
+            steps += 1
+            await event_handler(AgentEvent(type="agent_turn_start", payload={"step": steps}))
+
+            # Build tools schema: user tools + finished tool
+            tools_schema: List[Dict[str, Any]] = [finished_tool_schema]
+            if selected_tools and self.tool_manager:
+                user_tools = await error_handler.safe_get_tools_schema(self.tool_manager, selected_tools)
+                tools_schema.extend(user_tools)
+
+            # Call LLM with tools - using "required" to force tool calling during Act phase
+            # The LiteLLM caller has fallback logic to "auto" if "required" is not supported
+            if data_sources and context.user_email:
+                llm_response = await self.llm.call_with_rag_and_tools(
+                    model, messages, data_sources, tools_schema, context.user_email, "required", temperature=temperature
+                )
+            else:
+                llm_response = await self.llm.call_with_tools(
+                    model, messages, tools_schema, "required", temperature=temperature
+                )
+
+            # Process response
+            if llm_response.has_tool_calls():
+                tool_calls = llm_response.tool_calls or []
+
+                # Check if finished tool was called
+                final_answer = self._extract_finished_args(tool_calls)
+                if final_answer:
+                    break
+
+                # Execute first non-finished tool call
+                first_call = None
+                for tc in tool_calls:
+                    f = tc.get("function") if isinstance(tc, dict) else None
+                    if f and f.get("name") != "finished":
+                        first_call = tc
+                        break
+
+                if first_call is None:
+                    # Only finished tool or no valid tools
+                    final_answer = llm_response.content or "Task completed."
+                    break
+
+                # Execute the tool
+                messages.append({
+                    "role": "assistant",
+                    "content": llm_response.content,
+                    "tool_calls": [first_call],
+                })
+
+                result = await tool_executor.execute_single_tool(
+                    tool_call=first_call,
+                    session_context={
+                        "session_id": context.session_id,
+                        "user_email": context.user_email,
+                        "files": context.files,
+                    },
+                    tool_manager=self.tool_manager,
+                    update_callback=(self.connection.send_json if self.connection else None),
+                    config_manager=self.config_manager,
+                    skip_approval=self.skip_approval,
+                )
+
+                messages.append({
+                    "role": "tool",
+                    "content": result.content,
+                    "tool_call_id": result.tool_call_id,
+                })
+
+                # Emit tool results for artifact ingestion
+                await event_handler(AgentEvent(type="agent_tool_results", payload={"results": [result]}))
+            else:
+                # No tool calls - treat content as final answer
+                final_answer = llm_response.content or "Task completed."
+                break
+
+        # Fallback if no final answer after max steps
+        if not final_answer:
+            final_answer = await self.llm.call_plain(model, messages, temperature=temperature)
+
+        await event_handler(AgentEvent(type="agent_completion", payload={"steps": steps}))
+        return AgentResult(final_answer=final_answer, steps=steps, metadata={"agent_mode": True, "strategy": "act"})

atlas/application/chat/agent/factory.py

@@ -0,0 +1,142 @@
+"""Factory for creating agent loop instances based on strategy."""
+
+import logging
+from typing import Optional
+
+from atlas.interfaces.llm import LLMProtocol
+from atlas.interfaces.tools import ToolManagerProtocol
+from atlas.interfaces.transport import ChatConnectionProtocol
+from atlas.modules.prompts.prompt_provider import PromptProvider
+
+from .act_loop import ActAgentLoop
+from .protocols import AgentLoopProtocol
+from .react_loop import ReActAgentLoop
+from .think_act_loop import ThinkActAgentLoop
+
+logger = logging.getLogger(__name__)
+
+
+class AgentLoopFactory:
+    """
+    Factory for creating agent loop instances.
+
+    This factory pattern allows for easy addition of new agent loop strategies
+    without modifying existing code. Simply add a new strategy to the registry.
+    """
+
+    def __init__(
+        self,
+        llm: LLMProtocol,
+        tool_manager: Optional[ToolManagerProtocol] = None,
+        prompt_provider: Optional[PromptProvider] = None,
+        connection: Optional[ChatConnectionProtocol] = None,
+        config_manager=None,
+    ):
+        """
+        Initialize factory with shared dependencies.
+
+        Args:
+            llm: LLM protocol implementation
+            tool_manager: Optional tool manager
+            prompt_provider: Optional prompt provider
+            connection: Optional connection for sending updates
+            config_manager: Optional config manager for approval settings
+        """
+        self.llm = llm
+        self.tool_manager = tool_manager
+        self.prompt_provider = prompt_provider
+        self.connection = connection
+        self.config_manager = config_manager
+        self.skip_approval = False
+
+        # Registry of available strategies
+        self._strategy_registry = {
+            "react": ReActAgentLoop,
+            "think-act": ThinkActAgentLoop,
+            "think_act": ThinkActAgentLoop,
+            "thinkact": ThinkActAgentLoop,
+            "act": ActAgentLoop,
+        }
+
+        # Cache of instantiated loops for performance
+        self._loop_cache: dict[str, AgentLoopProtocol] = {}
+
+    def create(self, strategy: str = "think-act") -> AgentLoopProtocol:
+        """
+        Create an agent loop instance for the given strategy.
+
+        Args:
+            strategy: Strategy name (react, think-act, act, etc.)
+
+        Returns:
+            AgentLoopProtocol instance
+
+        Note:
+            If the strategy is not recognized, falls back to 'react' with a warning.
+        """
+        strategy_normalized = strategy.lower().strip()
+
+        # Check cache first
+        if strategy_normalized in self._loop_cache:
+            logger.info(f"Using agent loop strategy: {strategy_normalized}")
+            return self._loop_cache[strategy_normalized]
+
+        # Look up strategy in registry
+        loop_class = self._strategy_registry.get(strategy_normalized)
+
+        if loop_class is None:
+            logger.warning(
+                f"Unknown agent loop strategy '{strategy}', falling back to 'react'"
+            )
+            loop_class = self._strategy_registry["react"]
+            strategy_normalized = "react"
+
+        # Instantiate the loop
+        loop_instance = loop_class(
+            llm=self.llm,
+            tool_manager=self.tool_manager,
+            prompt_provider=self.prompt_provider,
+            connection=self.connection,
+            config_manager=self.config_manager,
+        )
+
+        loop_instance.skip_approval = self.skip_approval
+
+        # Cache for future use
+        self._loop_cache[strategy_normalized] = loop_instance
+
+        logger.info(f"Created and using agent loop strategy: {strategy_normalized}")
+        return loop_instance
+
+    def get_available_strategies(self) -> list[str]:
+        """
+        Get list of available strategy names.
+
+        Returns:
+            List of strategy identifiers
+        """
+        # Return unique strategy names (deduplicated)
+        unique_strategies = set()
+        for strategy in self._strategy_registry.keys():
+            # Normalize to primary name
+            if strategy in ("react",):
+                unique_strategies.add("react")
+            elif strategy in ("think-act", "think_act", "thinkact"):
+                unique_strategies.add("think-act")
+            elif strategy in ("act",):
+                unique_strategies.add("act")
+        return sorted(unique_strategies)
+
+    def register_strategy(self, name: str, loop_class: type[AgentLoopProtocol]) -> None:
+        """
+        Register a new agent loop strategy.
+
+        This allows for dynamic extension of available strategies.
+
+        Args:
+            name: Strategy identifier
+            loop_class: Agent loop class to instantiate
+        """
+        name_normalized = name.lower().strip()
+        self._strategy_registry[name_normalized] = loop_class
+        logger.info(f"Registered new agent loop strategy: {name_normalized}")

atlas/application/chat/agent/protocols.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Protocol
+from uuid import UUID
+
+from atlas.domain.messages.models import ConversationHistory
+
+
+@dataclass
+class AgentContext:
+    session_id: UUID
+    user_email: Optional[str]
+    files: Dict[str, Any]
+    history: ConversationHistory
+
+
+@dataclass
+class AgentResult:
+    final_answer: str
+    steps: int
+    metadata: Dict[str, Any]
+
+
+@dataclass
+class AgentEvent:
+    type: str
+    payload: Dict[str, Any]
+
+
+AgentEventHandler = Callable[[AgentEvent], Awaitable[None]]
+
+
+class AgentLoopProtocol(Protocol):
+    async def run(
+        self,
+        *,
+        model: str,
+        messages: List[Dict[str, Any]],
+        context: AgentContext,
+        selected_tools: Optional[List[str]],
+        data_sources: Optional[List[str]],
+        max_steps: int,
+        temperature: float,
+        event_handler: AgentEventHandler,
+    ) -> AgentResult: ...