mojentic 0.7.1__py3-none-any.whl → 0.7.3__py3-none-any.whl

_examples/broker_as_tool.py

@@ -2,7 +2,7 @@ import os
 from mojentic.agents.base_llm_agent import BaseLLMAgent
 from mojentic.llm.llm_broker import LLMBroker
 from mojentic.llm.tools.date_resolver import ResolveDateTool
-from mojentic.llm.tools.file_manager import FileManager, ListFilesTool, ReadFileTool, WriteFileTool
+from mojentic.llm.tools.file_manager import FileManager, ListFilesTool, ReadFileTool, WriteFileTool, FilesystemGateway
 from mojentic.llm.tools.tool_wrapper import ToolWrapper
 
 #
@@ -15,19 +15,22 @@ temporal_specialist = BaseLLMAgent(
     behaviour="You are a historian and sociologist who focuses on sorting out temporal events, determining what happened or will happen when."
 )
 
+if not os.path.exists("local"):
+    os.mkdir("local")
+
+# Create a filesystem gateway for the local directory
+fs = FilesystemGateway(base_path="local")
+
 knowledge_specialist = BaseLLMAgent(
     llm=LLMBroker(model="llama3.3-70b-32k"),
     tools=[
-        ListFilesTool(path="local"),
-        ReadFileTool(path="local"),
-        WriteFileTool(path="local"),
+        ListFilesTool(fs),
+        ReadFileTool(fs),
+        WriteFileTool(fs),
     ],
     behaviour="You are a knowledge management agent who focuses on sorting out facts and information, able to organize elemental ideas and make connections between them. You can list files to find out where you stored information, read files to review that information, and write files to store that information for later retrieval."
 )
 
-if not os.path.exists("local"):
-    os.mkdir("local")
-
 
 
 coordinator = BaseLLMAgent(
@@ -42,14 +45,14 @@ coordinator = BaseLLMAgent(
 result = coordinator.generate_response("""
 
 I have several things I need to do this week:
-                                       
+
 - On Monday, I need to ensure that I have called Scotiabank and ordered replacement cards for my current, credit, and line of credit accounts.
 - On Wednesday, I need to drive into Toronto for work. While in Toronto I need to pick up razors. I need to make sure I see Gregg, Britney and Vikram.
 - On Thursday, I need to ensure I'm up by 7am so that I can be showered and ready for work by 9.
 - On Friday, I need to ensure that I have my laundry done and my bags packed for my trip to Ottawa.
-                                       
+
 Create me a markdown file for each day of the week, named "YYYY-MM-DD-ToDo.md" where the date is the date of that day.
 Make a list of to-do items in the markdown file, and add a section for the day's daily notes that I can fill out each day.
 """)
 
-print(result)
+print(result)

_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/context/__init__.py

@@ -1 +1,5 @@
+"""
+Mojentic context module for managing shared working memory and context.
+"""
+
 from .shared_working_memory import SharedWorkingMemory

mojentic/llm/__init__.py

@@ -1,4 +1,16 @@
+"""
+Mojentic LLM module for interacting with Large Language Models.
+"""
+
+# Main LLM components
 from .llm_broker import LLMBroker
-from .registry.llm_registry import LLMRegistry
 from .chat_session import ChatSession
-from .message_composers import MessageBuilder, FileTypeSensor
+from .message_composers import MessageBuilder, FileTypeSensor
+from .registry.llm_registry import LLMRegistry
+
+# Re-export gateway components at the LLM level
+from .gateways.models import (
+    LLMMessage,
+    LLMGatewayResponse,
+    MessageRole
+)

mojentic/llm/gateways/__init__.py

@@ -1,3 +1,25 @@
+"""
+Mojentic LLM gateways module for connecting to various LLM providers.
+"""
+
+# Gateway implementations
 from .llm_gateway import LLMGateway
 from .ollama import OllamaGateway
 from .openai import OpenAIGateway
+from .anthropic import AnthropicGateway
+from .file_gateway import FileGateway
+from .embeddings_gateway import EmbeddingsGateway
+from .tokenizer_gateway import TokenizerGateway
+
+# Message adapters
+from .anthropic_messages_adapter import adapt_messages_to_anthropic
+from .ollama_messages_adapter import adapt_messages_to_ollama
+from .openai_messages_adapter import adapt_messages_to_openai
+
+# Common models
+from .models import (
+    LLMMessage,
+    MessageRole,
+    LLMGatewayResponse,
+    LLMToolCall
+)

mojentic/llm/gateways/anthropic.py

@@ -29,7 +29,7 @@ class AnthropicGateway(LLMGateway):
         response = self.client.messages.create(
             **anthropic_args,
             temperature=args.get('temperature', 1.0),
-            max_tokens=args.get('num_predict', 2000),
+            max_tokens=args.get('max_tokens', args.get('num_predict', 2000)),
             # thinking={
             #     "type": "enabled",
             #     "budget_tokens": 32768,

mojentic/llm/gateways/llm_gateway.py

@@ -19,7 +19,7 @@ class LLMGateway:
                  object_model: Optional[Type[BaseModel]] = None,
                  tools: Optional[List[LLMTool]] = None,
                  temperature: float = 1.0,
-                 num_ctx: int = 32768,
+                 num_ctx: int = 32768, max_tokens: int = 16384,
                  num_predict: int = -1) -> LLMGatewayResponse:
         """
         Complete the LLM request.
@@ -39,6 +39,8 @@ class LLMGateway:
             The temperature to use for the response. Defaults to 1.0.
         num_ctx : int
             The number of context tokens to use. Defaults to 32768.
+        max_tokens : int
+            The maximum number of tokens to generate. Defaults to 16384.
         num_predict : int
             The number of tokens to predict. Defaults to no limit.
 

mojentic/llm/gateways/ollama.py

@@ -35,6 +35,8 @@ class OllamaGateway(LLMGateway):
         )
         if args.get('num_predict', 0) > 0:
             options.num_predict = args['num_predict']
+        if 'max_tokens' in args:
+            options.num_predict = args['max_tokens']
         return options
 
     def complete(self, **args) -> LLMGatewayResponse:
@@ -56,6 +58,8 @@ class OllamaGateway(LLMGateway):
             The temperature to use for the response. Defaults to 1.0.
         num_ctx : int, optional
             The number of context tokens to use. Defaults to 32768.
+        max_tokens : int, optional
+            The maximum number of tokens to generate. Defaults to 16384.
         num_predict : int, optional
             The number of tokens to predict. Defaults to no limit.
 
@@ -120,6 +124,8 @@ class OllamaGateway(LLMGateway):
             The temperature to use for the response. Defaults to 1.0.
         num_ctx : int, optional
             The number of context tokens to use. Defaults to 32768.
+        max_tokens : int, optional
+            The maximum number of tokens to generate. Defaults to 16384.
         num_predict : int, optional
             The number of tokens to predict. Defaults to no limit.
 

mojentic/llm/gateways/openai.py

@@ -46,6 +46,8 @@ class OpenAIGateway(LLMGateway):
             The temperature to use for the response. Defaults to 1.0.
         num_ctx : int, optional
             The number of context tokens to use. Defaults to 32768.
+        max_tokens : int, optional
+            The maximum number of tokens to generate. Defaults to 16384.
         num_predict : int, optional
             The number of tokens to predict. Defaults to no limit.
 
@@ -68,6 +70,9 @@ class OpenAIGateway(LLMGateway):
         if 'tools' in args and args['tools'] is not None:
             openai_args['tools'] = [t.descriptor for t in args['tools']]
 
+        if 'max_tokens' in args:
+            openai_args['max_tokens'] = args['max_tokens']
+
         response = completion(**openai_args)
 
         object = None