mojentic 0.8.4__tar.gz → 1.0.0__tar.gz

{mojentic-0.8.4/src/mojentic.egg-info → mojentic-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mojentic
-Version: 0.8.4
+Version: 1.0.0
 Summary: Mojentic is an agentic framework that aims to provide a simple and flexible way to assemble teams of agents to solve complex problems.
 Author-email: Stacey Vetzal <stacey@vetzal.com>
 Project-URL: Homepage, https://github.com/svetzal/mojentic
@@ -11,30 +11,32 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
-Requires-Dist: pydantic
-Requires-Dist: structlog
-Requires-Dist: numpy
-Requires-Dist: ollama
-Requires-Dist: openai
-Requires-Dist: anthropic
-Requires-Dist: tiktoken
-Requires-Dist: parsedatetime
-Requires-Dist: pytz
-Requires-Dist: serpapi
-Requires-Dist: colorama
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: structlog>=25.5.0
+Requires-Dist: numpy>=2.3.5
+Requires-Dist: ollama>=0.1.6
+Requires-Dist: openai>=2.8.1
+Requires-Dist: anthropic>=0.74.1
+Requires-Dist: tiktoken>=0.12.0
+Requires-Dist: parsedatetime>=2.6
+Requires-Dist: pytz>=2025.2
+Requires-Dist: serpapi>=0.1.5
+Requires-Dist: colorama>=0.4.6
 Provides-Extra: dev
-Requires-Dist: pytest>=7.0.0; extra == "dev"
-Requires-Dist: pytest-asyncio; extra == "dev"
-Requires-Dist: pytest-spec; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest>=9.0.1; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
+Requires-Dist: pytest-spec>=5.2.0; extra == "dev"
+Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
-Requires-Dist: flake8>=6.0.0; extra == "dev"
-Requires-Dist: mkdocs; extra == "dev"
-Requires-Dist: mkdocs-material; extra == "dev"
-Requires-Dist: mkdocs-llmstxt; extra == "dev"
-Requires-Dist: mkdocstrings[python]; extra == "dev"
-Requires-Dist: griffe-fieldz; extra == "dev"
-Requires-Dist: pymdown-extensions; extra == "dev"
+Requires-Dist: flake8>=7.3.0; extra == "dev"
+Requires-Dist: bandit>=1.7.0; extra == "dev"
+Requires-Dist: pip-audit>=2.0.0; extra == "dev"
+Requires-Dist: mkdocs>=1.5.2; extra == "dev"
+Requires-Dist: mkdocs-material>=9.6.10; extra == "dev"
+Requires-Dist: mkdocs-llmstxt>=0.4.0; extra == "dev"
+Requires-Dist: mkdocstrings[python]>=0.21.0; extra == "dev"
+Requires-Dist: griffe-fieldz>=0.3.0; extra == "dev"
+Requires-Dist: pymdown-extensions>=10.3; extra == "dev"
 Dynamic: license-file
 
 # Mojentic
@@ -64,16 +66,26 @@ Mojentic is a framework that provides a simple and flexible way to interact with
 
 ## 🔧 Installation
 
+We recommend using [uv](https://docs.astral.sh/uv/) for fast, reliable Python project management.
+
 ```bash
-# Install from PyPI
+# Install from PyPI using uv
+uv pip install mojentic
+
+# Or with pip
 pip install mojentic
 ```
 
-Or install from source
+Or install from source:
 
 ```bash
 git clone https://github.com/svetzal/mojentic.git
 cd mojentic
+
+# Using uv (recommended)
+uv sync
+
+# Or with pip
 pip install -e .
 ```
 
@@ -91,7 +103,7 @@ openai_llm = LLMBroker(model="gpt-5", gateway=OpenAIGateway(api_key="your_api_ke
 # Or use other models: "gpt-4o", "gpt-4.1", "o1-mini", "o3-mini", etc.
 
 # Or use Ollama for local LLMs
-ollama_llm = LLMBroker(model="llama3")
+ollama_llm = LLMBroker(model="qwen3:32b")
 
 # Simple text generation
 result = openai_llm.generate(messages=[LLMMessage(content='Hello, how are you?')])
@@ -121,6 +133,35 @@ result = openai_llm.generate(messages=[
 print(result)
 ```
 
+## 🔑 OpenAI configuration
+
+OpenAIGateway now supports environment-variable defaults so you can get started without hardcoding secrets:
+
+- If you omit `api_key`, it will use the `OPENAI_API_KEY` environment variable.
+- If you omit `base_url`, it will use the `OPENAI_API_ENDPOINT` environment variable (useful for custom endpoints like Azure/OpenAI-compatible proxies).
+- Precedence: values you pass explicitly to `OpenAIGateway(api_key=..., base_url=...)` always override environment variables.
+
+Examples:
+
+```python
+from mojentic.llm import LLMBroker
+from mojentic.llm.gateways import OpenAIGateway
+
+# 1) Easiest: rely on environment variables
+#    export OPENAI_API_KEY=sk-...
+#    export OPENAI_API_ENDPOINT=https://api.openai.com/v1   # optional
+llm = LLMBroker(
+    model="gpt-4o-mini",
+    gateway=OpenAIGateway()  # picks up OPENAI_API_KEY/OPENAI_API_ENDPOINT automatically
+)
+
+# 2) Explicitly override one or both values
+llm = LLMBroker(
+    model="gpt-4o-mini",
+    gateway=OpenAIGateway(api_key="your_key", base_url="https://api.openai.com/v1")
+)
+```
+
 ## 🤖 OpenAI Model Support
 
 The framework automatically handles parameter differences between model types, so you can switch between any models without code changes.
@@ -163,11 +204,19 @@ Visit [the documentation](https://svetzal.github.io/mojentic/) for comprehensive
 git clone https://github.com/svetzal/mojentic.git
 cd mojentic
 
-# Install dependencies
+# Using uv (recommended)
+uv sync --extra dev
+
+# Or with pip
 pip install -e ".[dev]"
 
 # Run tests
 pytest
+
+# Quality checks
+flake8 src          # Linting
+bandit -r src       # Security scan
+pip-audit           # Dependency vulnerabilities
 ```
 
 ## ✅ Project Status

{mojentic-0.8.4 → mojentic-1.0.0}/README.md

@@ -25,16 +25,26 @@ Mojentic is a framework that provides a simple and flexible way to interact with
 
 ## 🔧 Installation
 
+We recommend using [uv](https://docs.astral.sh/uv/) for fast, reliable Python project management.
+
 ```bash
-# Install from PyPI
+# Install from PyPI using uv
+uv pip install mojentic
+
+# Or with pip
 pip install mojentic
 ```
 
-Or install from source
+Or install from source:
 
 ```bash
 git clone https://github.com/svetzal/mojentic.git
 cd mojentic
+
+# Using uv (recommended)
+uv sync
+
+# Or with pip
 pip install -e .
 ```
 
@@ -52,7 +62,7 @@ openai_llm = LLMBroker(model="gpt-5", gateway=OpenAIGateway(api_key="your_api_ke
 # Or use other models: "gpt-4o", "gpt-4.1", "o1-mini", "o3-mini", etc.
 
 # Or use Ollama for local LLMs
-ollama_llm = LLMBroker(model="llama3")
+ollama_llm = LLMBroker(model="qwen3:32b")
 
 # Simple text generation
 result = openai_llm.generate(messages=[LLMMessage(content='Hello, how are you?')])
@@ -82,6 +92,35 @@ result = openai_llm.generate(messages=[
 print(result)
 ```
 
+## 🔑 OpenAI configuration
+
+OpenAIGateway now supports environment-variable defaults so you can get started without hardcoding secrets:
+
+- If you omit `api_key`, it will use the `OPENAI_API_KEY` environment variable.
+- If you omit `base_url`, it will use the `OPENAI_API_ENDPOINT` environment variable (useful for custom endpoints like Azure/OpenAI-compatible proxies).
+- Precedence: values you pass explicitly to `OpenAIGateway(api_key=..., base_url=...)` always override environment variables.
+
+Examples:
+
+```python
+from mojentic.llm import LLMBroker
+from mojentic.llm.gateways import OpenAIGateway
+
+# 1) Easiest: rely on environment variables
+#    export OPENAI_API_KEY=sk-...
+#    export OPENAI_API_ENDPOINT=https://api.openai.com/v1   # optional
+llm = LLMBroker(
+    model="gpt-4o-mini",
+    gateway=OpenAIGateway()  # picks up OPENAI_API_KEY/OPENAI_API_ENDPOINT automatically
+)
+
+# 2) Explicitly override one or both values
+llm = LLMBroker(
+    model="gpt-4o-mini",
+    gateway=OpenAIGateway(api_key="your_key", base_url="https://api.openai.com/v1")
+)
+```
+
 ## 🤖 OpenAI Model Support
 
 The framework automatically handles parameter differences between model types, so you can switch between any models without code changes.
@@ -124,11 +163,19 @@ Visit [the documentation](https://svetzal.github.io/mojentic/) for comprehensive
 git clone https://github.com/svetzal/mojentic.git
 cd mojentic
 
-# Install dependencies
+# Using uv (recommended)
+uv sync --extra dev
+
+# Or with pip
 pip install -e ".[dev]"
 
 # Run tests
 pytest
+
+# Quality checks
+flake8 src          # Linting
+bandit -r src       # Security scan
+pip-audit           # Dependency vulnerabilities
 ```
 
 ## ✅ Project Status

{mojentic-0.8.4 → mojentic-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mojentic"
-version = "0.8.4"
+version = "1.0.0"
 authors = [
     { name = "Stacey Vetzal", email = "stacey@vetzal.com" },
 ]
@@ -14,33 +14,35 @@ classifiers = [
 ]
 
 dependencies = [
-    "pydantic",
-    "structlog",
-    "numpy",
-    "ollama",
-    "openai",
-    "anthropic",
-    "tiktoken",
-    "parsedatetime",
-    "pytz",
-    "serpapi",
-    "colorama",
+    "pydantic>=2.8.0",
+    "structlog>=25.5.0",
+    "numpy>=2.3.5",
+    "ollama>=0.1.6",
+    "openai>=2.8.1",
+    "anthropic>=0.74.1",
+    "tiktoken>=0.12.0",
+    "parsedatetime>=2.6",
+    "pytz>=2025.2",
+    "serpapi>=0.1.5",
+    "colorama>=0.4.6",
 ]
 
 [project.optional-dependencies]
 dev = [
-    "pytest>=7.0.0",
-    "pytest-asyncio",
-    "pytest-spec",
-    "pytest-cov",
+    "pytest>=9.0.1",
+    "pytest-asyncio>=1.3.0",
+    "pytest-spec>=5.2.0",
+    "pytest-cov>=7.0.0",
     "pytest-mock>=3.10.0",
-    "flake8>=6.0.0",
-    "mkdocs",
-    "mkdocs-material",
-    "mkdocs-llmstxt",
-    "mkdocstrings[python]",
-    "griffe-fieldz",
-    "pymdown-extensions",
+    "flake8>=7.3.0",
+    "bandit>=1.7.0",
+    "pip-audit>=2.0.0",
+    "mkdocs>=1.5.2",
+    "mkdocs-material>=9.6.10",
+    "mkdocs-llmstxt>=0.4.0",
+    "mkdocstrings[python]>=0.21.0",
+    "griffe-fieldz>=0.3.0",
+    "pymdown-extensions>=10.3",
 ]
 
 [build-system]

{mojentic-0.8.4 → mojentic-1.0.0}/src/_examples/async_dispatcher_example.py

@@ -62,7 +62,11 @@ class TextAnalyzerAgent(BaseAsyncLLMAgent):
     def __init__(self, llm: LLMBroker):
         super().__init__(
             llm=llm,
-            behaviour="You are a text analysis assistant. Your job is to provide a detailed analysis of the given text, including key themes, structure, and notable elements.",
+            behaviour=(
+                "You are a text analysis assistant. "
+                "Your job is to provide a detailed analysis of the given text, "
+                "including key themes, structure, and notable elements."
+            ),
             response_model=AnalysisResponse
         )
 
@@ -93,7 +97,11 @@ class TextSummarizerAgent(BaseAsyncLLMAgent):
     def __init__(self, llm: LLMBroker):
         super().__init__(
             llm=llm,
-            behaviour="You are a text summarization assistant. Your job is to provide concise, accurate summaries of texts while preserving the key information and main points.",
+            behaviour=(
+                "You are a text summarization assistant. "
+                "Your job is to provide concise, accurate summaries of texts "
+                "while preserving the key information and main points."
+            ),
             response_model=SummaryResponse
         )
 
@@ -143,8 +151,8 @@ Analysis: {analysis_event.analysis}
 
 Summary: {summary_event.summary}
 
-Please create a well-structured, insightful report that integrates the analysis and summary, 
-highlighting the most important aspects of the text. The report should provide a comprehensive 
+Please create a well-structured, insightful report that integrates the analysis and summary,
+highlighting the most important aspects of the text. The report should provide a comprehensive
 understanding of the text's content, structure, and significance.
 """
             # Create a temporary LLM agent to generate the response

{mojentic-0.8.4 → mojentic-1.0.0}/src/_examples/async_llm_example.py

@@ -5,14 +5,13 @@ This script shows how to create and use asynchronous LLM agents with the AsyncDi
 """
 
 import asyncio
-from typing import List, Optional
+from typing import List
 
 from pydantic import BaseModel, Field
 
 from mojentic.agents.async_aggregator_agent import AsyncAggregatorAgent
 from mojentic.agents.async_llm_agent import BaseAsyncLLMAgent
 from mojentic.async_dispatcher import AsyncDispatcher
-from mojentic.context.shared_working_memory import SharedWorkingMemory
 from mojentic.event import Event
 from mojentic.llm import LLMBroker
 from mojentic.router import Router

mojentic-1.0.0/src/_examples/broker_as_tool.py

@@ -0,0 +1,83 @@
+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 ListFilesTool, ReadFileTool, WriteFileTool, FilesystemGateway
+from mojentic.llm.tools.tool_wrapper import ToolWrapper
+
+#
+# This is largely a fail, but it was interesting.
+#
+
+temporal_specialist = BaseLLMAgent(
+    llm=LLMBroker(model="qwen3:7b"),
+    tools=[ResolveDateTool()],
+    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="qwen3:32b"),
+    tools=[
+        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."
+    )
+)
+
+
+coordinator = BaseLLMAgent(
+    llm=LLMBroker(model="qwen3:32b"),
+    behaviour="You are a coordinator who can manage multiple agents and delegate tasks to them to solve problems.",
+    tools=[
+        ToolWrapper(
+            temporal_specialist,
+            "temporal_specialist",
+            "A historian and sociologist who focuses on sorting out temporal events, figuring out "
+            "dates, determining what happened or will happen when."
+        ),
+        ToolWrapper(
+            knowledge_specialist,
+            "knowledge_specialist",
+            "A knowledge management specialist who focuses on sorting out facts and information, "
+            "able to organize elemental ideas and make connections between them. 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."
+        ),
+    ]
+)
+
+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)

{mojentic-0.8.4 → mojentic-1.0.0}/src/_examples/broker_examples.py

@@ -1,18 +1,16 @@
 import logging
 import os
-
-from mojentic.llm import LLMBroker
-from mojentic.llm.gateways import OpenAIGateway
-
-logging.basicConfig(level=logging.WARN)
-
 from pathlib import Path
 
 from pydantic import BaseModel, Field
 
+from mojentic.llm import LLMBroker
+from mojentic.llm.gateways import OpenAIGateway
 from mojentic.llm.gateways.models import LLMMessage
 from mojentic.llm.tools.date_resolver import ResolveDateTool
 
+logging.basicConfig(level=logging.WARN)
+
 
 def openai_llm(model="gpt-5"):
     api_key = os.getenv("OPENAI_API_KEY")
@@ -21,7 +19,7 @@ def openai_llm(model="gpt-5"):
     return llm
 
 
-def ollama_llm(model="llama3.3-70b-32k"):
+def ollama_llm(model="qwen3:32b"):
     llm = LLMBroker(model=model)
     return llm
 

{mojentic-0.8.4 → mojentic-1.0.0}/src/_examples/broker_image_examples.py

@@ -13,7 +13,7 @@ def openai_llm(model="gpt-4o"):
     return llm
 
 
-def ollama_llm(model="llama3.3-70b-32k"):
+def ollama_llm(model="qwen3:32b"):
     llm = LLMBroker(model=model)
     return llm
 

{mojentic-0.8.4 → mojentic-1.0.0}/src/_examples/characterize_ollama.py

@@ -1,7 +1,7 @@
 from ollama import chat
 from pydantic import BaseModel, Field
 
-from mojentic.llm.gateways.models import LLMMessage, MessageRole
+from mojentic.llm.gateways.models import LLMMessage
 from mojentic.llm.gateways.ollama import OllamaGateway
 from mojentic.llm.tools.date_resolver import ResolveDateTool
 
@@ -13,7 +13,7 @@ def check_ollama_gateway():
         label: str = Field(..., description="The label describing the feeling.")
 
     response = gateway.complete(
-        model="llama3.2:1b",
+        model="qwen3:7b",
         messages=[LLMMessage(content="Hello, how are you?")],
         object_model=Feeling,
         temperature=1.0,
@@ -25,7 +25,7 @@ def check_ollama_gateway():
 
 def check_tools_call():
     response = chat(
-        model="llama3.3-70b-32k",
+        model="qwen3:32b",
         messages=[
             # {
             #     'role': 'user',

{mojentic-0.8.4 → mojentic-1.0.0}/src/_examples/characterize_openai.py

@@ -2,7 +2,7 @@ import os
 
 from pydantic import BaseModel, Field
 
-from mojentic.llm.gateways.models import LLMMessage, MessageRole
+from mojentic.llm.gateways.models import LLMMessage
 from mojentic.llm.gateways.openai import OpenAIGateway
 
 api_key = os.getenv("OPENAI_API_KEY")

{mojentic-0.8.4 → mojentic-1.0.0}/src/_examples/chat_session.py

@@ -1,6 +1,6 @@
 from mojentic.llm import ChatSession, LLMBroker
 
-llm_broker = LLMBroker(model="llama3.3-70b-32k")
+llm_broker = LLMBroker(model="qwen3:32b")
 chat_session = ChatSession(llm_broker)
 
 while True:
@@ -9,4 +9,4 @@ while True:
         break
     else:
         response = chat_session.send(query)
-        print(response)
+        print(response)

{mojentic-0.8.4 → mojentic-1.0.0}/src/_examples/chat_session_with_tool.py

@@ -1,7 +1,7 @@
 from mojentic.llm import ChatSession, LLMBroker
 from mojentic.llm.tools.date_resolver import ResolveDateTool
 
-llm_broker = LLMBroker(model="llama3.3-70b-32k")
+llm_broker = LLMBroker(model="qwen3:32b")
 chat_session = ChatSession(llm_broker, tools=[ResolveDateTool()])
 
 while True:
@@ -10,4 +10,4 @@ while True:
         break
     else:
         response = chat_session.send(query)
-        print(response)
+        print(response)

{mojentic-0.8.4 → mojentic-1.0.0}/src/_examples/coding_file_tool.py

@@ -30,7 +30,7 @@ from mojentic.llm.tools.file_manager import (
     EditFileWithDiffTool, CreateDirectoryTool, FilesystemGateway
 )
 
-base_dir = Path(__file__).parent.parent.parent.parent / "code-playground2"
+base_dir = Path(__file__).parent.parent.parent.parent / "code-playground3"
 
 # Initialize the LLM broker
 
@@ -38,9 +38,7 @@ api_key = os.getenv("OPENAI_API_KEY")
 gateway = OpenAIGateway(api_key)
 llm = LLMBroker(model="o4-mini", gateway=gateway)
 
-# llm = LLMBroker("qwen2.5-coder:32b")
-# llm = LLMBroker("llama3.3")
-# llm = LLMBroker(model="qwen3-128k:32b")
+llm = LLMBroker("qwen3-coder:30b")
 
 # Create a filesystem gateway for the sandbox
 fs = FilesystemGateway(base_path=str(base_dir))
@@ -75,28 +73,28 @@ solver = IterativeProblemSolver(
     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 
+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 
+* **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; 
+  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; 
+* **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 
+* **Version‑control etiquette** — descriptive commit messages, branch from `main`, PRs require
 green CI.
 
 # 2 - Python‑Specific Conventions
@@ -115,21 +113,21 @@ green CI.
 
 ## 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 
+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 
+* 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 
+* **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.
@@ -144,14 +142,14 @@ line.
 
 * 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 
+* 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 
+* 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.
@@ -162,7 +160,7 @@ visible).
 # 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 
+- 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.