mojentic 0.6.2__py3-none-any.whl → 0.7.2__py3-none-any.whl

_examples/coding_file_tool.py

@@ -1,88 +1,181 @@
+"""
+This example demonstrates the use of all the file management tools available in mojentic.
+
+It creates an IterativeProblemSolver with access to a comprehensive set of file management tools:
+- ListFilesTool: List files in the top-level directory
+- ListAllFilesTool: List all files recursively
+- ReadFileTool: Read the content of a file
+- WriteFileTool: Write content to a file
+- CreateDirectoryTool: Create a new directory
+- FindFilesByGlobTool: Find files matching a glob pattern
+- FindFilesContainingTool: Find files containing text matching a regex pattern
+- FindLinesMatchingTool: Find lines in a file matching a regex pattern
+- EditFileWithDiffTool: Edit a file by applying a diff
+
+The solver is then given a task that requires using all of these tools.
+"""
+
 import os
 from pathlib import Path
 
-from pydantic import BaseModel
-
-from mojentic.agents.base_llm_agent import BaseLLMAgent
-from mojentic.agents.output_agent import OutputAgent
-from mojentic.dispatcher import Dispatcher
-from mojentic.event import Event
+from mojentic.agents.iterative_problem_solver import IterativeProblemSolver
 from mojentic.llm.gateways import OpenAIGateway
 from mojentic.llm.llm_broker import LLMBroker
-from mojentic.llm.tools.file_manager import ReadFileTool, WriteFileTool
-from mojentic.router import Router
-
-
-class RequestEvent(Event):
-    text: str
-
-
-class ResponseEvent(Event):
-    text: str
-
-
-class ResponseModel(BaseModel):
-    text: str
-
-
-base_dir = Path(__file__).parent.parent.parent.parent / "code-playground"
-
-
-class RequestAgent(BaseLLMAgent):
-    def __init__(self, llm: LLMBroker):
-        super().__init__(llm,
-                         "You are a helpful assistant.")
-        self.add_tool(ReadFileTool(str(base_dir)))
-        self.add_tool(WriteFileTool(str(base_dir)))
-
-    def receive_event(self, event):
-        response = self.generate_response(event.text)
-        return [ResponseEvent(source=type(self), correlation_id=event.correlation_id, text=response)]
+from mojentic.llm.tools.ephemeral_task_manager import EphemeralTaskList, AppendTaskTool, \
+    ClearTasksTool, CompleteTaskTool, InsertTaskAfterTool, ListTasksTool, PrependTaskTool, \
+    StartTaskTool
+from mojentic.llm.tools.file_manager import (
+    ReadFileTool, WriteFileTool, ListFilesTool, ListAllFilesTool,
+    FindFilesByGlobTool, FindFilesContainingTool, FindLinesMatchingTool,
+    EditFileWithDiffTool, CreateDirectoryTool, FilesystemGateway
+)
 
+base_dir = Path(__file__).parent.parent.parent.parent / "code-playground2"
 
-# with open(base_dir / "spec.md", 'w') as file:
-#     file.write("""
-# Primes
-#
-# You are to write some python code that will generate the first 100 prime numbers.
-#
-# Store the code in a file called primes.py
-# """.strip())
+# Initialize the LLM broker
 
-#
-# OK this example is fun, it shows trying to make 2 consecutive
-# tool calls. The first tool call reads a file, the second writes a file.
-#
-# Ollama 3.1 70b seems to handle this consistently, 3.3 70b seems flakey, flakier when num_ctx is set to 32768
-# Ollama 3.1 8b seems to handle it about 1/3 the time
-# OpenAI gpt-4o-mini handles it perfectly every single time
-#
-
-
-# llm = LLMBroker("qwen2.5-coder:32b")
-# llm = LLMBroker("llama3.3")
 api_key = os.getenv("OPENAI_API_KEY")
 gateway = OpenAIGateway(api_key)
-llm = LLMBroker(model="gpt-4o", gateway=gateway)
-request_agent = RequestAgent(llm)
-output_agent = OutputAgent()
-
-router = Router({
-    RequestEvent: [request_agent, output_agent],
-    ResponseEvent: [output_agent]
-})
-
-dispatcher = Dispatcher(router)
-dispatcher.dispatch(RequestEvent(source=str, text="""
-# Mandelbrodt Set
+llm = LLMBroker(model="o4-mini", gateway=gateway)
 
-You are to implement a program that will generate an image of the Mandelbrot set.
-
-The program should be written in Swift for macOS utilizing SwiftUI.
-
-The program should generate an image of the Mandelbrot set and display it in a window.
-
-Generate any files you require to store the source code.
-
-Generate a README.md file that includes instructions on how to run the program.
-"""))
+# llm = LLMBroker("qwen2.5-coder:32b")
+# llm = LLMBroker("llama3.3")
+# llm = LLMBroker(model="qwen3-128k:32b")
+
+# Create a filesystem gateway for the sandbox
+fs = FilesystemGateway(base_path=str(base_dir))
+
+task_manager = EphemeralTaskList()
+
+# Create a list of all file management tools
+tools = [
+    ReadFileTool(fs),
+    WriteFileTool(fs),
+    ListFilesTool(fs),
+    ListAllFilesTool(fs),
+    CreateDirectoryTool(fs),
+    FindFilesByGlobTool(fs),
+    FindFilesContainingTool(fs),
+    FindLinesMatchingTool(fs),
+    EditFileWithDiffTool(fs),
+    AppendTaskTool(task_manager),
+    ClearTasksTool(task_manager),
+    CompleteTaskTool(task_manager),
+    InsertTaskAfterTool(task_manager),
+    ListTasksTool(task_manager),
+    PrependTaskTool(task_manager),
+    StartTaskTool(task_manager),
+]
+
+# Create the iterative problem solver with the tools
+solver = IterativeProblemSolver(
+    llm=llm,
+    available_tools=tools,
+    max_iterations=5,
+    system_prompt="""
+# 0 - Project Identity & Context
+
+You are an expert and principled software engineer, well versed in writing Python games. You work 
+carefully and purposefully and always check your work with an eye to testability and correctness. 
+You know that every line of code you write is a liability, and you take care that every line 
+matters.
+
+# 1 - Universal Engineering Principles
+
+* **Code is communication** — optimise for the next human reader.
+* **Simple Design Heuristics** — guiding principles, not iron laws; consult the user when you 
+need to break them.
+  1. **All tests pass** — correctness is non‑negotiable.
+  2. **Reveals intent** — code should read like an explanation.
+  3. **No *****knowledge***** duplication** — avoid multiple spots that must change together; 
+  identical code is only a smell when it hides duplicate *decisions*.
+  4. **Minimal entities** — remove unnecessary indirection, classes, or parameters.
+* **Small, safe increments** — single‑reason commits; avoid speculative work (**YAGNI**).
+* **Tests are the executable spec** — red first, green always; test behaviour not implementation.
+* **Compose over inherit**; favour pure functions where practical, avoid side-effects.
+* **Functional core, imperative shell** — isolate pure business logic from I/O and side effects; 
+push mutations to the system boundaries, build mockable gateways at those boundaries.
+* **Psychological safety** — review code, not colleagues; critique ideas, not authors.
+* **Version‑control etiquette** — descriptive commit messages, branch from `main`, PRs require 
+green CI.
+
+# 2 - Python‑Specific Conventions
+
+## 2.1 Runtime & Environment
+
+* **Python ≥ 3.12** (support the two most recent LTS releases).
+* Create an isolated environment:
+
+  ```bash
+  python -m venv .venv
+  source .venv/bin/activate
+  pip install -e ".[dev]"
+  ```
+* Enforce `pre‑commit` hooks (flake8, mypy, black, pytest).
+
+## 2.2 Core Libraries
+
+Mandatory: pydantic, structlog, pytest, pytest-spec, pytest-cov, pytest-mock, flake8, black, 
+pre‑commit, mkdocs‑material. Add new libs only when they eliminate **significant** boilerplate or 
+risk.
+
+## 2.3 Project Structure & Imports
+
+* **src‑layout**: code in `src/<package_name>/`; tests live beside code as `*_spec.py`.
+* Import order: 1) stdlib, 2) third‑party, 3) first‑party — each group alphabetised with a blank 
+line.
+
+## 2.4 Naming & Style
+
+* `snake_case` for functions & vars, `PascalCase` for classes, `UPPER_SNAKE` for constants.
+* Prefix intentionally unused vars/args with `_`.
+* **flake8** (with plugins) handles linting, and **black** auto‑formats code. Max line length 
+**100**.
+* Cyclomatic complexity cap: **10** (flake8 `C901`).
+* Use **f‑strings**; avoid magic numbers.
+
+## 2.5 Type Hints & Docstrings
+
+* **100% type coverage**; code must pass `mypy --strict`.
+* Use `pydantic.BaseModel` for data models; don't use bare `@dataclass` if validation is needed.
+* Docstrings in Google format; omit the obvious.
+
+## 2.6 Logging & Observability
+
+* Configure **structlog** for JSON output by default.
+* Never use `print` for diagnostics; reserve for user‑facing CLI UX.
+* Log levels: `DEBUG` (dev detail) → `INFO` (lifecycle) → `WARNING` (recoverable) → `ERROR` (user 
+visible).
+
+## 2.7 Testing Strategy
+
+* **pytest** with **pytest-spec** for specification-style output.
+* Test files end with `_spec.py` and live in the same folder as the code under test.
+* Use **Arrange / Act / Assert** blocks separated by a blank line (no comments) **or** BDD 
+`describe/should` classes.
+* Function names: use `should_*` and BDD-style specifications.
+* Class names: use `Describe*` and BDD-style test suites.
+* **Mocking**: Use `pytest-mock`'s `mocker` fixture; don't use `unittest.mock.MagicMock` directly.
+* One behavioural expectation per test. Fixtures are helpers, not magic.
+* Tests should fail for one reason, avoid multiple assert statements, split the test cases
+
+# 3 - Planning and Goal Tracking
+
+- Use the provided task manager tools to create your plans and work through them step by step.
+- Before declaring yourself finished list all tasks, ensure they are all complete, and that you 
+have not missed any steps
+- If you've missed or forgotten some steps, add them to the task list and continue
+- When all tasks are complete, and you can think of no more to add, declare yourself finished.
+    """
+)
+
+# Define the task
+task = """
+Create a new Python project that is a graphical clone of Windows MineSweeper.
+
+Ensure it is well tested.
+"""
+
+# Solve the task and print the result
+result = solver.solve(task)
+print(result)

_examples/file_tool.py

@@ -5,7 +5,7 @@ from mojentic.agents.output_agent import OutputAgent
 from mojentic.dispatcher import Dispatcher
 from mojentic.event import Event
 from mojentic.llm.llm_broker import LLMBroker
-from mojentic.llm.tools.file_manager import ReadFileTool, WriteFileTool
+from mojentic.llm.tools.file_manager import ReadFileTool, WriteFileTool, FilesystemGateway
 from mojentic.router import Router
 
 
@@ -25,8 +25,10 @@ class RequestAgent(BaseLLMAgent):
     def __init__(self, llm: LLMBroker):
         super().__init__(llm,
                          "You are a helpful assistant.")
-        self.add_tool(ReadFileTool("/tmp"))
-        self.add_tool(WriteFileTool("/tmp"))
+        # Create a filesystem gateway for the /tmp directory
+        fs = FilesystemGateway(base_path="/tmp")
+        self.add_tool(ReadFileTool(fs))
+        self.add_tool(WriteFileTool(fs))
 
     def receive_event(self, event):
         response = self.generate_response(event.text)

mojentic/__init__.py

@@ -7,10 +7,12 @@ import logging
 
 import structlog
 
+# Core components
 from .dispatcher import Dispatcher
 from .event import Event
 from .router import Router
 
+# Initialize logging
 logging.basicConfig(level=logging.INFO)
 structlog.configure(logger_factory=structlog.stdlib.LoggerFactory(), processors=[
     structlog.stdlib.filter_by_level,
@@ -22,13 +24,6 @@ structlog.configure(logger_factory=structlog.stdlib.LoggerFactory(), processors=
 logger = structlog.get_logger()
 logger.info("Starting logger")
 
-# logger = logging.getLogger("mojentic")
-# path = Path().cwd()
-# log_filename = path / 'output.log'
-# print(f"Logging to {log_filename}")
-# logging.basicConfig(filename=log_filename, level=logging.DEBUG)
-# logger.info("Starting logger")
-
 
 __version__: str
 try:

mojentic/agents/__init__.py

@@ -1,7 +1,16 @@
+"""
+Mojentic agents module for creating and working with various agent types.
+"""
+
+# Base agent types
 from .base_agent import BaseAgent
-from .base_llm_agent import BaseLLMAgent
-from .base_llm_agent import BaseLLMAgentWithMemory
+from .base_llm_agent import BaseLLMAgent, BaseLLMAgentWithMemory
+
+# Special purpose agents
 from .correlation_aggregator_agent import BaseAggregatingAgent
 from .output_agent import OutputAgent
 from .iterative_problem_solver import IterativeProblemSolver
 from .simple_recursive_agent import SimpleRecursiveAgent
+
+# Agent brokering
+from .agent_broker import AgentBroker

mojentic/agents/async_aggregator_agent.py

@@ -0,0 +1,162 @@
+import asyncio
+import structlog
+
+from mojentic.agents.base_async_agent import BaseAsyncAgent
+from mojentic.event import Event
+
+logger = structlog.get_logger()
+
+
+class AsyncAggregatorAgent(BaseAsyncAgent):
+    """
+    AsyncAggregatorAgent is an asynchronous version of the BaseAggregatingAgent.
+    It aggregates events based on their correlation_id and processes them when all required events are available.
+    """
+    def __init__(self, event_types_needed=None):
+        """
+        Initialize the AsyncAggregatorAgent.
+
+        Parameters
+        ----------
+        event_types_needed : list, optional
+            List of event types that need to be captured before processing
+        """
+        super().__init__()
+        self.results = {}
+        self.event_types_needed = event_types_needed or []
+        self.futures = {}  # Maps correlation_id to Future objects
+
+    async def _get_and_reset_results(self, event):
+        """
+        Get and reset the results for a specific correlation_id.
+
+        Parameters
+        ----------
+        event : Event
+            The event to get results for
+
+        Returns
+        -------
+        list
+            The results for the event
+        """
+        results = self.results[event.correlation_id]
+        self.results[event.correlation_id] = None
+        return results
+
+    async def _capture_results_if_needed(self, event):
+        """
+        Capture results for a specific correlation_id.
+
+        Parameters
+        ----------
+        event : Event
+            The event to capture results for
+        """
+        results = self.results.get(event.correlation_id, [])
+        results.append(event)
+        self.results[event.correlation_id] = results
+
+        # Check if we have all needed events and set the future if we do
+        event_types_captured = [type(e) for e in self.results.get(event.correlation_id, [])]
+        finished = all([event_type in event_types_captured for event_type in self.event_types_needed])
+
+        if finished and event.correlation_id in self.futures:
+            future = self.futures[event.correlation_id]
+            if not future.done():
+                future.set_result(self.results[event.correlation_id])
+
+    async def _has_all_needed(self, event):
+        """
+        Check if all needed event types have been captured for a specific correlation_id.
+
+        Parameters
+        ----------
+        event : Event
+            The event to check
+
+        Returns
+        -------
+        bool
+            True if all needed event types have been captured, False otherwise
+        """
+        event_types_captured = [type(e) for e in self.results.get(event.correlation_id, [])]
+        finished = all([event_type in event_types_captured for event_type in self.event_types_needed])
+        logger.debug(f"Captured: {event_types_captured}, Needed: {self.event_types_needed}, Finished: {finished}")
+        return finished
+
+    async def wait_for_events(self, correlation_id, timeout=None):
+        """
+        Wait for all needed events for a specific correlation_id.
+
+        Parameters
+        ----------
+        correlation_id : str
+            The correlation_id to wait for
+        timeout : float, optional
+            The timeout in seconds
+
+        Returns
+        -------
+        list
+            The events for the correlation_id
+        """
+        if correlation_id not in self.futures:
+            self.futures[correlation_id] = asyncio.Future()
+
+        # If we already have all needed events, return them
+        if correlation_id in self.results:
+            event_types_captured = [type(e) for e in self.results.get(correlation_id, [])]
+            if all([event_type in event_types_captured for event_type in self.event_types_needed]):
+                return self.results[correlation_id]
+
+        # Otherwise, wait for the future to be set
+        try:
+            return await asyncio.wait_for(self.futures[correlation_id], timeout)
+        except asyncio.TimeoutError:
+            logger.warning(f"Timeout waiting for events for correlation_id {correlation_id}")
+            return self.results.get(correlation_id, [])
+
+    async def receive_event_async(self, event: Event) -> list:
+        """
+        Receive an event and process it if all needed events are available.
+
+        Parameters
+        ----------
+        event : Event
+            The event to process
+
+        Returns
+        -------
+        list
+            The events to be processed next
+        """
+        # First capture the event
+        await self._capture_results_if_needed(event)
+
+        # Then check if we have all needed events
+        event_types_captured = [type(e) for e in self.results.get(event.correlation_id, [])]
+        finished = all([event_type in event_types_captured for event_type in self.event_types_needed])
+
+        # If we have all needed events, process them
+        if finished:
+            return await self.process_events(await self._get_and_reset_results(event))
+
+        return []
+
+    async def process_events(self, events):
+        """
+        Process a list of events.
+        This method should be overridden by subclasses.
+
+        Parameters
+        ----------
+        events : list
+            The events to process
+
+        Returns
+        -------
+        list
+            The events to be processed next
+        """
+        return []