WitsV3 LLM Orchestration Development
Development assistant for WitsV3, an async LLM orchestration system with CLI-first approach, ReAct pattern, and tool registry architecture.
Overview
This skill helps you develop and maintain WitsV3, a Python-based LLM wrapper system with async-first design, agent orchestration, and extensible tool architecture.
Instructions
Initial Context Loading
1. **Always read `PLANNING.md` first** when starting a new conversation to understand:
- LLM wrapper architecture
- Project goals and design decisions
- Core architectural patterns
2. **Check `TASK.md` before any work**:
- Review existing tasks
- Add new tasks with dates if not listed
- Update task status after completion
- Log discovered work under "Discovered During Work" section
Architecture Understanding
**Core Project Structure:**
`agents/` - Agent implementations (BaseAgent, Orchestrators, Control Center)`core/` - Core functionality (config, LLM interface, memory, schemas)`tools/` - Tool implementations extending BaseTool`tests/` - pytest test suite mirroring source structure**Key Architectural Patterns:**
Fully async I/O operationsReAct pattern (Reason-Act-Observe) in orchestratorsTool registry for dynamic tool loadingStreamData for agent communicationMemory Manager integrationConfig-driven design via `config.yaml`Python & Async Best Practices
**Language Requirements:**
Python 3.10+Type hints throughout all codePEP8 compliance with black formattingPydantic models for data validation (use `core/schemas.py`)**Async Patterns:**
All agent/tool methods MUST be asyncUse `async`/`await` for all I/O operationsReturn `AsyncGenerator` for streaming responsesNever mix synchronous I/O with async code**Import Style:**
Relative imports within packages (`from .module import Class`)Absolute imports for cross-package (`from witsv3.core import Config`)Code Structure & Modularity
**File Size Limits:**
Maximum 500 lines per fileSplit into modules when approaching limitMaintain logical separation of concerns**Adding New Components:**
*New Tools:*
Place in `tools/` directoryMust extend `BaseTool` classImplement `get_llm_description()` for registryRegister with tool registry pattern*New Agents:*
Place in `agents/` directoryMust extend `BaseAgent` classUse `StreamData` for communicationIntegrate with Memory Manager via `store_memory()` and `search_memory()`**Logging Pattern:**
Use `self.logger` in all classesLog important state changes and errorsInclude context in log messagesTesting Requirements
**Create pytest tests for ALL new features in `/tests` directory:**
**Required Test Coverage per Feature:**
Happy path test (normal operation)Error handling test (failure scenarios)Edge case test (boundary conditions)**Async Testing:**
Use pytest-asyncio for async function testsMock external services (Ollama, file system) in testsEnsure tests don't require live Ollama connection**Test Execution:**
Run existing test functions at bottom of modules when updatingVerify all tests pass before committing**Example Test Structure:**
```python
import pytest
from witsv3.tools.my_tool import MyTool
@pytest.mark.asyncio
async def test_my_tool_happy_path():
"""Test normal operation of MyTool."""
tool = MyTool()
result = await tool.execute(param="valid")
assert result.success
@pytest.mark.asyncio
async def test_my_tool_error_handling():
"""Test MyTool handles errors gracefully."""
tool = MyTool()
with pytest.raises(ValueError):
await tool.execute(param="invalid")
```
WitsV3-Specific Conventions
**StreamData Communication:**
Use `stream_thinking()` for reasoningUse `stream_action()` for tool executionUse `stream_observation()` for resultsUse `stream_error()` for error handling**LLM Integration:**
Ollama is primary LLM providerSupport streaming responses via `AsyncGenerator`Parse LLM responses robustly using `ResponseParser`Handle tool calls through `ToolCall`/`ToolResult` schemasHandle connection failures gracefully**Memory Management:**
Use `MemoryManager` for persistent storageCall `store_memory()` to save important contextCall `search_memory()` to retrieve relevant historyEnsure `MemorySegment` serialization works correctly**Configuration:**
Use `WitsV3Config` for all settingsLoad configuration from `config.yaml`Never hardcode configuration valuesMake configurable: model names, ports, paths, timeoutsDocumentation Standards
**Update Documentation When:**
Adding new featuresChanging setup proceduresModifying core architectureUpdating dependencies**Docstring Format (Google-style):**
```python
async def method_name(self, param: str) -> StreamData:
"""
Brief description of what this method does.
Args:
param: Description of the parameter
Yields:
StreamData objects for streaming responses
Raises:
ValueError: When param is invalid
"""
```
**Code Comments:**
Comment non-obvious logic with `# Reason:` explanationsExplain "why" not "what" for complex codeDocument assumptions and constraintsTask & Commit Management
**Task Management in TASK.md:**
Update after completing tasksAdd discovered work with datesLog progress in task descriptionsTrack blockers and dependencies**Commit Guidelines:**
Summarize actual changes in commit messagesFollow repository commit style conventionsInclude detailed descriptions in PR summariesReference related tasks/issuesCritical Rules (NEVER Break These)
**Async Integrity:**
Never break async patternsAll I/O operations MUST be asyncNever use synchronous blocking calls**Architecture Preservation:**
Preserve ReAct loop in orchestrators (Reason-Act-Observe)Maintain backward compatibility with existing tools/agentsDon't create circular imports between packagesDon't modify core schemas without updating all dependent code**Testing Requirements:**
Test with Ollama running for integration testsMock Ollama for unit testsEnsure Unicode handling works correctlyVerify memory persistence functionsDon't Do
❌ Don't use synchronous I/O operations❌ Don't create circular imports between packages❌ Don't modify core schemas without updating dependent code❌ Don't hardcode configuration values❌ Don't forget to handle LLM connection failures❌ Don't exceed 500 lines per file without refactoring❌ Don't skip writing tests for new features❌ Don't forget to update TASK.md after work❌ Don't break the ReAct pattern in orchestratorsExamples
**Adding a New Tool:**
```python
tools/my_new_tool.py
from witsv3.core.tool import BaseTool
from witsv3.core.schemas import ToolResult
from typing import Dict, Any
class MyNewTool(BaseTool):
"""
Description of what this tool does.
This tool extends BaseTool and provides [specific functionality].
"""
async def execute(self, **params: Dict[str, Any]) -> ToolResult:
"""
Execute the tool with given parameters.
Args:
params: Tool-specific parameters
Returns:
ToolResult with execution outcome
"""
try:
# Async implementation here
result = await self._do_async_work(params)
return ToolResult(success=True, data=result)
except Exception as e:
self.logger.error(f"Tool execution failed: {e}")
return ToolResult(success=False, error=str(e))
@classmethod
def get_llm_description(cls) -> Dict[str, Any]:
"""Return tool description for LLM tool registry."""
return {
"name": "my_new_tool",
"description": "Brief description for LLM",
"parameters": {
"param1": {"type": "string", "description": "Param description"}
}
}
```
**Testing Pattern:**
```python
tests/tools/test_my_new_tool.py
import pytest
from witsv3.tools.my_new_tool import MyNewTool
@pytest.mark.asyncio
async def test_my_new_tool_happy_path():
"""Test normal operation."""
tool = MyNewTool()
result = await tool.execute(param1="valid")
assert result.success
assert result.data is not None
@pytest.mark.asyncio
async def test_my_new_tool_invalid_params():
"""Test error handling with invalid parameters."""
tool = MyNewTool()
result = await tool.execute(param1="")
assert not result.success
assert result.error is not None
```
Notes
WitsV3 emphasizes clean text output and proper Unicode handlingThe system is CLI-first but designed for potential UI integrationOllama connection is required for many features - handle disconnection gracefullyThe ReAct pattern is core to orchestration - maintain the Reason-Act-Observe loopTool registry enables dynamic tool discovery and LLM tool use