minimal impl. of the agent

agent/README.md

@@ -0,0 +1,127 @@
+# HF Agent
+
+AI Agent for working with Hugging Face models, datasets, and tools.
+
+## Structure
+
+```
+agent/
+├── core/                 # Core agent logic
+│   ├── agent.py         # Main agent implementation
+│   ├── base.py          # Base classes and interfaces
+│   ├── planner.py       # Task planning and decomposition
+│   └── executor.py      # Task execution engine
+│
+├── tools/               # Agent tools and actions
+│   ├── base.py         # Tool base class and registry
+│   ├── search/         # Search tools (models, datasets, papers)
+│   ├── generation/     # Generation tools (content, code, data)
+│   ├── analysis/       # Analysis and evaluation tools
+│   └── dataset_ops/    # Dataset operations
+│
+├── prompts/            # Prompt templates
+│   ├── system/         # System prompts
+│   ├── task/           # Task-specific prompts
+│   └── few_shot/       # Few-shot examples
+│
+├── memory/             # Memory systems
+│   ├── short_term/     # Conversational memory
+│   └── long_term/      # Persistent knowledge
+│
+├── config/             # Configuration
+│   ├── settings.py     # Settings management
+│   └── default_config.json
+│
+├── utils/              # Utilities
+│   ├── logging.py      # Logging setup
+│   └── retry.py        # Retry logic
+│
+└── tests/              # Test suite
+    ├── unit/           # Unit tests
+    └── integration/    # Integration tests
+```
+
+## Key Components
+
+### Core
+- **Agent**: Main orchestrator that coordinates planning, execution, and reflection
+- **Planner**: Breaks down complex tasks into actionable steps
+- **Executor**: Executes individual steps using available tools
+
+### Tools
+- Modular tool system with base class and registry
+- Tools organized by category (search, generation, analysis, dataset ops)
+- Each tool can be registered and used by the agent
+
+### Memory
+- **Short-term**: Manages conversation context and current task state
+- **Long-term**: Persistent storage for learned knowledge and past interactions
+
+### Prompts
+- Template-based prompt management
+- System prompts for agent behavior
+- Task-specific prompts for different operations
+- Few-shot examples for learning
+
+## Usage
+
+```python
+from agent import Agent
+from agent.config import load_config
+
+# Load configuration
+config = load_config()
+
+# Create agent
+agent = Agent(config=config.model_dump())
+
+# Run a task
+result = await agent.run("Find the top 5 text generation models")
+```
+
+## Development
+
+### Adding a New Tool
+
+1. Create a new file in the appropriate `tools/` subdirectory
+2. Inherit from `BaseTool`
+3. Implement `execute()` and `_get_parameters()`
+4. Register the tool with the agent
+
+```python
+from agent.tools.base import BaseTool
+
+class MyTool(BaseTool):
+    name = "my_tool"
+    description = "Does something useful"
+
+    async def execute(self, **kwargs):
+        # Implementation
+        pass
+
+    def _get_parameters(self):
+        return {
+            "type": "object",
+            "properties": {...}
+        }
+```
+
+### Running Tests
+
+```bash
+pytest agent/tests/
+```
+
+## Configuration
+
+Configure the agent via `config/default_config.json` or by passing a config dict:
+
+```python
+config = {
+    "model_name": "gpt-4",
+    "temperature": 0.7,
+    "max_iterations": 10,
+    "reflection_enabled": True
+}
+agent = Agent(config=config)
+```

agent/__init__.py

@@ -0,0 +1,7 @@
+"""
+HF Agent - Main agent module
+"""
+
+from agent.core.agent_loop import Agent
+
+__all__ = ["Agent"]

agent/codex_agent_demo.py

@@ -0,0 +1,470 @@
+"""
+Minimum Viable Implementation of Codex Agent Loop in Python
+
+This demonstrates the core architecture patterns from codex-rs:
+- Async submission loop (like submission_loop in codex.rs)
+- Context manager for conversation history
+- Channel-based communication (submissions in, events out)
+- Handler pattern for operations
+"""
+
+import asyncio
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+# ============================================================================
+# PROTOCOL TYPES (ResponseItem equivalents)
+# ============================================================================
+
+
+class MessageRole(Enum):
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+
+
+@dataclass
+class Message:
+    role: MessageRole
+    content: str
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+@dataclass
+class ToolCall:
+    call_id: str
+    tool_name: str
+    arguments: Dict[str, Any]
+
+
+@dataclass
+class ToolOutput:
+    call_id: str
+    content: str
+    success: bool = True
+
+
+# ============================================================================
+# CONTEXT MANAGER (like context_manager/history.rs)
+# ============================================================================
+
+
+class ContextManager:
+    """
+    Manages conversation history with normalization and truncation.
+    Based on codex-rs/core/src/context_manager/history.rs
+    """
+
+    def __init__(self, max_history_length: int = 1000):
+        self.items: List[Any] = []  # Oldest → Newest
+        self.token_count: int = 0
+        self.max_history_length = max_history_length
+
+    def record_items(self, items: List[Any]) -> None:
+        """Record new items to history (like record_items in history.rs:41)"""
+        for item in items:
+            # Filter and process items
+            if self._is_api_message(item):
+                processed = self._process_item(item)
+                self.items.append(processed)
+
+    def _is_api_message(self, item: Any) -> bool:
+        """Filter out system messages (like is_api_message in history.rs:157)"""
+        if isinstance(item, Message):
+            return item.role != MessageRole.SYSTEM
+        return isinstance(item, (ToolCall, ToolOutput))
+
+    def _process_item(self, item: Any) -> Any:
+        """Process item before adding (like process_item in history.rs:119)"""
+        # Truncate long outputs
+        if isinstance(item, ToolOutput):
+            if len(item.content) > 2000:
+                item.content = item.content[:2000] + "...[truncated]"
+        return item
+
+    def get_history_for_prompt(self) -> List[Any]:
+        """
+        Get normalized history ready for model
+        (like get_history_for_prompt in history.rs:65)
+        """
+        self._normalize_history()
+        return self.items.copy()
+
+    def _normalize_history(self) -> None:
+        """
+        Enforce invariants (like normalize_history in history.rs:102):
+        1. Every tool call has corresponding output
+        2. Every output has corresponding call
+        """
+        # Build mapping of call_id → call
+        calls = {}
+        outputs = {}
+
+        for item in self.items:
+            if isinstance(item, ToolCall):
+                calls[item.call_id] = item
+            elif isinstance(item, ToolOutput):
+                outputs[item.call_id] = item
+
+        # Remove orphan outputs (no matching call)
+        self.items = [
+            item
+            for item in self.items
+            if not isinstance(item, ToolOutput) or item.call_id in calls
+        ]
+
+        # Add missing outputs for calls (create synthetic outputs)
+        for call_id, call in calls.items():
+            if call_id not in outputs:
+                self.items.append(
+                    ToolOutput(
+                        call_id=call_id, content="[No output recorded]", success=False
+                    )
+                )
+
+    def remove_first_item(self) -> None:
+        """Remove oldest item for compaction (like remove_first_item in history.rs:71)"""
+        if self.items:
+            removed = self.items.pop(0)
+            # Also remove corresponding pair if needed
+            if isinstance(removed, ToolCall):
+                self.items = [
+                    item
+                    for item in self.items
+                    if not (
+                        isinstance(item, ToolOutput) and item.call_id == removed.call_id
+                    )
+                ]
+            elif isinstance(removed, ToolOutput):
+                self.items = [
+                    item
+                    for item in self.items
+                    if not (
+                        isinstance(item, ToolCall) and item.call_id == removed.call_id
+                    )
+                ]
+
+    def compact(self, target_size: int) -> None:
+        """Remove old items until we're under target size"""
+        while len(self.items) > target_size:
+            self.remove_first_item()
+
+
+# ============================================================================
+# OPERATIONS (like Op enum in codex.rs)
+# ============================================================================
+
+
+class OpType(Enum):
+    USER_INPUT = "user_input"
+    EXEC_APPROVAL = "exec_approval"
+    INTERRUPT = "interrupt"
+    UNDO = "undo"
+    COMPACT = "compact"
+    SHUTDOWN = "shutdown"
+
+
+@dataclass
+class Operation:
+    op_type: OpType
+    data: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class Submission:
+    id: str
+    operation: Operation
+
+
+# ============================================================================
+# EVENTS (like Event in codex-rs)
+# ============================================================================
+
+
+@dataclass
+class Event:
+    event_type: str
+    data: Optional[Dict[str, Any]] = None
+
+
+# ============================================================================
+# SESSION STATE (like Session in codex.rs)
+# ============================================================================
+
+
+class Session:
+    """
+    Maintains agent session state
+    Similar to Session in codex-rs/core/src/codex.rs
+    """
+
+    def __init__(self, event_queue: asyncio.Queue):
+        self.context_manager = ContextManager()
+        self.event_queue = event_queue
+        self.is_running = True
+        self.current_task: Optional[asyncio.Task] = None
+
+    async def send_event(self, event: Event) -> None:
+        """Send event back to client"""
+        await self.event_queue.put(event)
+
+    def interrupt(self) -> None:
+        """Interrupt current running task"""
+        if self.current_task and not self.current_task.done():
+            self.current_task.cancel()
+
+
+# ============================================================================
+# OPERATION HANDLERS (like handlers module in codex.rs:1343)
+# ============================================================================
+
+
+class Handlers:
+    """Handler functions for each operation type"""
+
+    @staticmethod
+    async def user_input(session: Session, text: str) -> None:
+        """Handle user input (like user_input_or_turn in codex.rs:1291)"""
+        # Add user message to history
+        user_msg = Message(role=MessageRole.USER, content=text)
+        session.context_manager.record_items([user_msg])
+
+        # Send event that we're processing
+        await session.send_event(
+            Event(event_type="processing", data={"message": "Processing user input"})
+        )
+
+        # Simulate agent processing
+        await asyncio.sleep(0.1)
+
+        # Generate mock assistant response
+        assistant_msg = Message(
+            role=MessageRole.ASSISTANT, content=f"I received: {text}"
+        )
+        session.context_manager.record_items([assistant_msg])
+
+        # Simulate tool call
+        tool_call = ToolCall(
+            call_id="call_123", tool_name="bash", arguments={"command": "echo 'hello'"}
+        )
+        session.context_manager.record_items([tool_call])
+
+        # Simulate tool execution
+        await asyncio.sleep(0.1)
+
+        tool_output = ToolOutput(call_id="call_123", content="hello\n", success=True)
+        session.context_manager.record_items([tool_output])
+
+        # Send completion event
+        await session.send_event(
+            Event(
+                event_type="turn_complete",
+                data={"history_size": len(session.context_manager.items)},
+            )
+        )
+
+    @staticmethod
+    async def interrupt(session: Session) -> None:
+        """Handle interrupt (like interrupt in codex.rs:1266)"""
+        session.interrupt()
+        await session.send_event(Event(event_type="interrupted"))
+
+    @staticmethod
+    async def compact(session: Session) -> None:
+        """Handle compact (like compact in codex.rs:1317)"""
+        old_size = len(session.context_manager.items)
+        session.context_manager.compact(target_size=10)
+        new_size = len(session.context_manager.items)
+
+        await session.send_event(
+            Event(
+                event_type="compacted",
+                data={"removed": old_size - new_size, "remaining": new_size},
+            )
+        )
+
+    @staticmethod
+    async def undo(session: Session) -> None:
+        """Handle undo (like undo in codex.rs:1314)"""
+        # Remove last user turn and all following items
+        # Simplified: just remove last 2 items
+        for _ in range(min(2, len(session.context_manager.items))):
+            session.context_manager.items.pop()
+
+        await session.send_event(Event(event_type="undo_complete"))
+
+    @staticmethod
+    async def shutdown(session: Session) -> bool:
+        """Handle shutdown (like shutdown in codex.rs:1329)"""
+        session.is_running = False
+        await session.send_event(Event(event_type="shutdown"))
+        return True
+
+
+# ============================================================================
+# MAIN AGENT LOOP (like submission_loop in codex.rs:1259)
+# ============================================================================
+
+
+async def submission_loop(
+    submission_queue: asyncio.Queue, event_queue: asyncio.Queue
+) -> None:
+    """
+    Main agent loop - processes submissions and dispatches to handlers.
+    This is the core of the agent (like submission_loop in codex.rs:1259-1340)
+    """
+    session = Session(event_queue)
+
+    print("🤖 Agent loop started")
+
+    # Main processing loop
+    while session.is_running:
+        try:
+            # Wait for next submission (like rx_sub.recv() in codex.rs:1262)
+            submission = await submission_queue.get()
+
+            print(f"📨 Received: {submission.operation.op_type.value}")
+
+            # Dispatch to handler based on operation type
+            # (like match in codex.rs:1264-1337)
+            op = submission.operation
+
+            if op.op_type == OpType.USER_INPUT:
+                text = op.data.get("text", "") if op.data else ""
+                await Handlers.user_input(session, text)
+
+            elif op.op_type == OpType.INTERRUPT:
+                await Handlers.interrupt(session)
+
+            elif op.op_type == OpType.COMPACT:
+                await Handlers.compact(session)
+
+            elif op.op_type == OpType.UNDO:
+                await Handlers.undo(session)
+
+            elif op.op_type == OpType.SHUTDOWN:
+                if await Handlers.shutdown(session):
+                    break
+
+            else:
+                print(f"⚠️  Unknown operation: {op.op_type}")
+
+        except asyncio.CancelledError:
+            break
+        except Exception as e:
+            print(f"❌ Error in agent loop: {e}")
+            await session.send_event(Event(event_type="error", data={"error": str(e)}))
+
+    print("🛑 Agent loop exited")
+
+
+# ============================================================================
+# CODEX INTERFACE (like Codex struct in codex.rs:154)
+# ============================================================================
+
+
+class Codex:
+    """
+    Main interface to the agent (like Codex in codex.rs:154-246)
+    Provides submit() and next_event() methods
+    """
+
+    def __init__(self):
+        self.submission_queue = asyncio.Queue()
+        self.event_queue = asyncio.Queue()
+        self.agent_task: Optional[asyncio.Task] = None
+        self.submission_counter = 0
+
+    async def spawn(self) -> None:
+        """Spawn the agent loop (like Codex::spawn in codex.rs:156)"""
+        self.agent_task = asyncio.create_task(
+            submission_loop(self.submission_queue, self.event_queue)
+        )
+
+    async def submit(self, operation: Operation) -> str:
+        """Submit operation to agent (like Codex::submit in codex.rs:218)"""
+        self.submission_counter += 1
+        submission = Submission(
+            id=f"sub_{self.submission_counter}", operation=operation
+        )
+        await self.submission_queue.put(submission)
+        return submission.id
+
+    async def next_event(self) -> Optional[Event]:
+        """Get next event from agent (like Codex::next_event in codex.rs:238)"""
+        try:
+            return await asyncio.wait_for(self.event_queue.get(), timeout=1.0)
+        except asyncio.TimeoutError:
+            return None
+
+    async def shutdown(self) -> None:
+        """Shutdown the agent"""
+        await self.submit(Operation(op_type=OpType.SHUTDOWN))
+        if self.agent_task:
+            await self.agent_task
+
+
+# ============================================================================
+# DEMO / EXAMPLE USAGE
+# ============================================================================
+
+
+async def main():
+    """Demo of the agent system"""
+    print("=" * 60)
+    print("Codex Agent Loop Demo (Python MVP)")
+    print("=" * 60)
+
+    # Create and spawn agent
+    codex = Codex()
+    await codex.spawn()
+
+    # Submit some operations
+    print("\n1️⃣  Submitting user input...")
+    await codex.submit(
+        Operation(op_type=OpType.USER_INPUT, data={"text": "Hello, agent!"})
+    )
+
+    # Receive events
+    for _ in range(3):
+        event = await codex.next_event()
+        if event:
+            print(f"   ✅ Event: {event.event_type} - {event.data}")
+
+    print("\n2️⃣  Submitting another input...")
+    await codex.submit(
+        Operation(op_type=OpType.USER_INPUT, data={"text": "What's the weather?"})
+    )
+
+    for _ in range(3):
+        event = await codex.next_event()
+        if event:
+            print(f"   ✅ Event: {event.event_type} - {event.data}")
+
+    print("\n3️⃣  Compacting history...")
+    await codex.submit(Operation(op_type=OpType.COMPACT))
+
+    event = await codex.next_event()
+    if event:
+        print(f"   ✅ Event: {event.event_type} - {event.data}")
+
+    print("\n4️⃣  Undoing last turn...")
+    await codex.submit(Operation(op_type=OpType.UNDO))
+
+    event = await codex.next_event()
+    if event:
+        print(f"   ✅ Event: {event.event_type}")
+
+    # Shutdown
+    print("\n5️⃣  Shutting down...")
+    await codex.shutdown()
+
+    print("\n" + "=" * 60)
+    print("Demo complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agent/config.py

@@ -0,0 +1,16 @@
+from litellm import Tool
+from pydantic import BaseModel
+
+
+class Config(BaseModel):
+    """Configuration manager"""
+
+    model_name: str
+    tools: list[Tool]
+    system_prompt_path: str
+
+
+def load_config(config_path: str = "config.json") -> Config:
+    """Load configuration from file"""
+    with open(config_path, "r") as f:
+        return Config.model_validate_json(f.read())

agent/context_manager/__init__.py

@@ -0,0 +1,7 @@
+"""
+Prompt templates and management
+"""
+
+from agent.prompts.manager import PromptManager
+
+__all__ = ["PromptManager"]

agent/context_manager/manager.py

@@ -0,0 +1,27 @@
+"""
+Prompt template management
+"""
+
+from litellm import Message
+
+
+class ContextManager:
+    """Manages context templates for the agent"""
+
+    def __init__(self):
+        self.system_prompt = self._load_system_prompt()
+        self.messages: list[Message] = [
+            Message(role="system", content=self.system_prompt)
+        ]
+
+    def _load_system_prompt(self):
+        """Load the system prompt"""
+
+        # TODO: get system prompt from jinja template
+        return "You are a helpful assistant."
+
+    def add_message(self, message: Message) -> None:
+        self.messages.append(message)
+
+    def get_messages(self) -> list[Message]:
+        return self.messages

agent/core/__init__.py

@@ -0,0 +1,8 @@
+"""
+Core agent implementation
+Contains the main agent logic, decision-making, and orchestration
+"""
+
+from agent.core.executor import ToolExecutor
+
+__all__ = ["ToolExecutor"]

agent/core/agent_loop.py

@@ -0,0 +1,183 @@
+"""
+Main agent implementation
+"""
+
+import asyncio
+
+from litellm import (
+    ChatCompletionMessageToolCall,
+    Message,
+    ModelResponse,
+    acompletion,
+)
+
+from agent.core.session import Event, OpType, Session
+
+ToolCall = ChatCompletionMessageToolCall
+
+
+class Handlers:
+    """Handler functions for each operation type"""
+
+    @staticmethod
+    async def run_agent(session: Session, text: str, max_iterations: int = 10) -> None:
+        """Handle user input (like user_input_or_turn in codex.rs:1291)"""
+        # Add user message to history
+        user_msg = Message(role="user", content=text)
+        session.context_manager.add_message(user_msg)
+
+        # Send event that we're processing
+        await session.send_event(
+            Event(event_type="processing", data={"message": "Processing user input"})
+        )
+
+        # Agentic loop - continue until model doesn't call tools or max iterations is reached
+        iteration = 0
+        while iteration < max_iterations:
+            messages = session.context_manager.get_messages()
+
+            try:
+                response: ModelResponse = await acompletion(
+                    model=session.config.model_name,
+                    messages=messages,
+                    tools=session.config.tools,
+                )
+                message = response.choices[0].message
+
+                # Extract content and tool calls
+                content = message.content
+                tool_calls: list[ToolCall] = message.get("tool_calls", [])
+
+                # Record assistant message if there's content
+                if content:
+                    assistant_msg = Message(role="assistant", content=content)
+                    session.context_manager.add_message(assistant_msg)
+
+                    await session.send_event(
+                        Event(
+                            event_type="assistant_message",
+                            data={"message": assistant_msg},
+                        )
+                    )
+
+                # If no tool calls, we're done
+                if not tool_calls:
+                    break
+
+                for tool_call in tool_calls:
+                    result = await session.tool_executor.execute_tool(tool_call)
+
+                    tool_output = Message(role="tool", content=result.output)
+                    session.context_manager.add_message(tool_output)
+
+                    await session.send_event(
+                        Event(
+                            event_type="tool_output",
+                            data={"message": tool_output},
+                        )
+                    )
+
+                iteration += 1
+
+            except Exception as e:
+                await session.send_event(
+                    Event(event_type="error", data={"error": str(e)})
+                )
+                break
+
+        # Send completion event
+        await session.send_event(
+            Event(
+                event_type="turn_complete",
+                data={"history_size": len(session.context_manager.items)},
+            )
+        )
+
+    @staticmethod
+    async def interrupt(session: Session) -> None:
+        """Handle interrupt (like interrupt in codex.rs:1266)"""
+        session.interrupt()
+        await session.send_event(Event(event_type="interrupted"))
+
+    @staticmethod
+    async def compact(session: Session) -> None:
+        """Handle compact (like compact in codex.rs:1317)"""
+        old_size = len(session.context_manager.items)
+        session.context_manager.compact(target_size=10)
+        new_size = len(session.context_manager.items)
+
+        await session.send_event(
+            Event(
+                event_type="compacted",
+                data={"removed": old_size - new_size, "remaining": new_size},
+            )
+        )
+
+    @staticmethod
+    async def undo(session: Session) -> None:
+        """Handle undo (like undo in codex.rs:1314)"""
+        # Remove last user turn and all following items
+        # Simplified: just remove last 2 items
+        for _ in range(min(2, len(session.context_manager.items))):
+            session.context_manager.items.pop()
+
+        await session.send_event(Event(event_type="undo_complete"))
+
+    @staticmethod
+    async def shutdown(session: Session) -> bool:
+        """Handle shutdown (like shutdown in codex.rs:1329)"""
+        session.is_running = False
+        await session.send_event(Event(event_type="shutdown"))
+        return True
+
+
+async def submission_loop(
+    submission_queue: asyncio.Queue, event_queue: asyncio.Queue
+) -> None:
+    """
+    Main agent loop - processes submissions and dispatches to handlers.
+    This is the core of the agent (like submission_loop in codex.rs:1259-1340)
+    """
+    session = Session(event_queue)
+
+    print("🤖 Agent loop started")
+
+    # Main processing loop
+    while session.is_running:
+        try:
+            # Wait for next submission (like rx_sub.recv() in codex.rs:1262)
+            submission = await submission_queue.get()
+
+            print(f"📨 Received: {submission.operation.op_type.value}")
+
+            # Dispatch to handler based on operation type
+            op = submission.operation
+
+            if op.op_type == OpType.USER_INPUT:
+                text = op.data.get("text", "") if op.data else ""
+                await Handlers.run_agent(session, text, max_iterations=10)
+
+            elif op.op_type == OpType.INTERRUPT:
+                # im not currently sure what this does lol
+                await Handlers.interrupt(session)
+
+            elif op.op_type == OpType.COMPACT:
+                await Handlers.compact(session)
+
+            elif op.op_type == OpType.UNDO:
+                await Handlers.undo(session)
+
+            elif op.op_type == OpType.SHUTDOWN:
+                if await Handlers.shutdown(session):
+                    break
+
+            else:
+                print(f"⚠️  Unknown operation: {op.op_type}")
+
+        except asyncio.CancelledError:
+            break
+        except Exception as e:
+            print(f"❌ Error in agent loop: {e}")
+            await session.send_event(Event(event_type="error", data={"error": str(e)}))
+
+    print("🛑 Agent loop exited")

agent/core/executor.py

@@ -0,0 +1,21 @@
+"""
+Task execution engine
+"""
+
+from typing import Any, Dict, List
+
+from litellm import ChatCompletionMessageToolCall
+
+ToolCall = ChatCompletionMessageToolCall
+
+
+class ToolExecutor:
+    """Executes planned tasks using available tools"""
+
+    def __init__(self, tools: List[Any] = None):
+        self.tools = tools or []
+
+    async def execute_tool(self, tool_call: ToolCall) -> Dict[str, Any]:
+        """Execute a single step in the plan"""
+        # TODO: Implement step execution
+        return {"status": "success", "result": None}

agent/core/session.py

@@ -0,0 +1,53 @@
+import asyncio
+from enum import Enum
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+from agent.context_manager.manager import ContextManager
+from agent.core import ToolExecutor
+
+
+class OpType(Enum):
+    USER_INPUT = "user_input"
+    EXEC_APPROVAL = "exec_approval"
+    INTERRUPT = "interrupt"
+    UNDO = "undo"
+    COMPACT = "compact"
+    SHUTDOWN = "shutdown"
+
+
+class Event(BaseModel):
+    event_type: Literal[
+        "processing",
+        "turn_complete",
+        "compacted",
+        "undo_complete",
+        "shutdown",
+        "error",
+        "interrupted",
+    ]  # Dummy events for now
+    data: dict[str, Any] | None = None
+
+
+class Session:
+    """
+    Maintains agent session state
+    Similar to Session in codex-rs/core/src/codex.rs
+    """
+
+    def __init__(self, event_queue: asyncio.Queue):
+        self.context_manager = ContextManager()
+        self.tool_executor = ToolExecutor()
+        self.event_queue = event_queue
+        self.is_running = True
+        self.current_task: asyncio.Task | None = None
+
+    async def send_event(self, event: Event) -> None:
+        """Send event back to client"""
+        await self.event_queue.put(event)
+
+    def interrupt(self) -> None:
+        """Interrupt current running task"""
+        if self.current_task and not self.current_task.done():
+            self.current_task.cancel()

agent/tests/__init__.py

@@ -0,0 +1,3 @@
+"""
+Test suite for HF Agent
+"""

agent/tests/unit/test_base.py

@@ -0,0 +1,10 @@
+"""
+Unit tests for base agent components
+"""
+
+
+def test_base_agent_initialization():
+    """Test that BaseAgent can be initialized with config"""
+    # This will fail because BaseAgent is abstract
+    # Subclasses should implement this
+    pass

agent/tools/__init__.py

@@ -0,0 +1,8 @@
+"""
+Agent tools and actions
+Tools are the actions the agent can take to interact with the environment
+"""
+
+from agent.tools.base import BaseTool, ToolRegistry
+
+__all__ = ["BaseTool", "ToolRegistry"]

agent/utils/__init__.py

@@ -0,0 +1,7 @@
+"""
+Utility functions and helpers
+"""
+
+from agent.utils.logging import setup_logger
+
+__all__ = ["setup_logger"]

agent/utils/logging.py

@@ -0,0 +1,40 @@
+"""
+Logging utilities
+"""
+
+import logging
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+def setup_logger(
+    name: str = "hf_agent", level: int = logging.INFO, log_file: Optional[Path] = None
+) -> logging.Logger:
+    """Setup and configure logger"""
+
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+
+    # Remove existing handlers
+    logger.handlers = []
+
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(level)
+    console_format = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+    console_handler.setFormatter(console_format)
+    logger.addHandler(console_handler)
+
+    # File handler if log_file specified
+    if log_file:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setLevel(level)
+        file_handler.setFormatter(console_format)
+        logger.addHandler(file_handler)
+
+    return logger