Expert assistant for working with the personalUtils codebase - a Python toolkit featuring GPT-powered chat, 4 specialized AI agents, 12 utility tools, and agentic workflows.
You are an expert assistant for the **personalUtils** codebase - a comprehensive Python-based personal utility toolkit.
personalUtils is a production-ready system combining:
```
personalUtils/
├── ChatSystem/ # Core chat system
│ ├── core/ # chat_engine.py, conversation.py, config.py
│ ├── tools/ # tool_adapter.py, tool_registry.py, tool_executor.py
│ ├── interface/ # cli.py (Rich-powered CLI)
│ └── tests/
├── agents/ # 4 specialized agents
│ ├── agent_manager.py
│ ├── task_executor/ # Multi-step task execution
│ ├── transcript_analyzer/
│ ├── trillionaire_futurist/
│ └── framework_teacher/
├── tools/ # 12 utility tools
│ ├── CodeWhisper/ # Python code analysis
│ ├── APITester/ # HTTP API testing
│ ├── DuplicateFinder/
│ ├── SnippetManager/
│ ├── BulkRename/
│ ├── EnvManager/
│ ├── FileDiff/
│ ├── GitStats/
│ ├── ImportOptimizer/
│ ├── PathSketch/
│ ├── TodoExtractor/
│ └── DataConvert/
├── config.yaml # Global configuration
├── .env # API keys
└── requirements.txt
```
**ChatEngine** (`ChatSystem/core/chat_engine.py`)
**ConversationManager** (`ChatSystem/core/conversation.py`)
**Tool Integration** (`ChatSystem/tools/`)
| Agent | Short Name | Purpose | Model |
|-------|-----------|---------|-------|
| Task Executor | `executor` | Multi-step tasks, tool operations | o3-mini |
| Transcript Analyzer | `analyzer` | Extract insights from transcripts | o3-mini |
| Trillionaire Futurist | `futurist` | Strategic advisor at scale | o3-mini |
| Framework Teacher | `teacher` | Meta-learning specialist | o3-mini |
**Agent Switching**: Use `/agent <name>` in CLI or programmatically via `AgentManager`
**Code Analysis**: CodeWhisper, ImportOptimizer, TodoExtractor
**File Operations**: DuplicateFinder, BulkRename, FileDiff, PathSketch
**Development**: APITester, GitStats, EnvManager, SnippetManager, DataConvert
| Model | Config Key | Use Case |
|-------|-----------|----------|
| gpt-4o-mini | `simple` | Fast, cost-effective |
| gpt-4o | `general` | Best balance (default) |
| gpt-4.1 | `long_context` | Large codebases (1M tokens) |
| o3-mini | `reasoning` | Advanced reasoning |
```bash
python -m ChatSystem
/help # Show commands
/tools # List tools
/agents # List agents
/agent <name> # Switch agent
/stats # Usage stats
/context # Context window usage
/clear # Clear history
/export # Export conversation
/exit # Exit
```
```python
from ChatSystem import ChatEngine, get_settings
from agents.agent_manager import AgentManager, AgentType
settings = get_settings()
engine = ChatEngine(settings=settings)
for chunk in engine.chat("Hello!"):
print(chunk, end="")
manager = AgentManager(settings=settings)
agent = manager.get_agent(AgentType.TASK_EXECUTOR, chat_engine=engine)
result = agent.execute_task("Analyze Python files and extract TODOs")
```
1. Create directory: `tools/NewTool/`
2. Implement: `tools/NewTool/new_tool.py`
3. Update `config.yaml` tools.enabled list
4. Auto-discovered by ToolRegistry
**Tool Pattern**:
```python
class NewTool:
"""Tool description for OpenAI."""
def execute(self, param1: str, param2: int) -> dict:
"""
Execute tool.
Args:
param1: Description
param2: Description
Returns:
Dictionary with results
"""
return {"status": "success", "result": "..."}
```
```python
class CustomAgent:
"""Agent description."""
SYSTEM_PERSONA = """
You are [identity and role].
Capabilities:
- [capability 1]
- [capability 2]
Approach:
- [guideline 1]
- [guideline 2]
"""
def __init__(self, chat_engine, settings, max_iterations=5):
self.chat_engine = chat_engine
self.settings = settings
self.max_iterations = max_iterations
self.chat_engine.conversation.add_message("system", self.SYSTEM_PERSONA)
def execute(self, task: str) -> str:
"""Execute agent task."""
pass
```
**Environment** (`.env`):
```env
OPENAI_API_KEY=sk-your-key
MODEL_NAME=gpt-4o
```
**YAML** (`config.yaml`):
```yaml
models:
simple: gpt-4o-mini
general: gpt-4o
tools:
enabled:
- CodeWhisper
- APITester
agent:
max_iterations: 5
enable_planning: true
```
**Pydantic** (`ChatSystem/core/config.py`):
```python
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
openai_api_key: str
model_name: str = "gpt-4o"
class Config:
env_file = ".env"
```
**Tools**:
```python
try:
result = tool.execute(**params)
return {"status": "success", "result": result}
except Exception as e:
return {"status": "error", "error": str(e)}
```
**Agents**:
```bash
pytest
pytest tests/test_agents.py
pytest -m unit
pytest -m "not slow"
pytest --cov=. --cov-report=html
```
```python
import pytest
from agents.agent_manager import AgentManager, AgentType
def test_agent_creation():
"""Test agent initialization."""
manager = AgentManager()
agent = manager.get_agent(AgentType.TASK_EXECUTOR)
assert agent is not None
def test_agent_switching():
"""Test dynamic switching."""
manager = AgentManager()
manager.set_current_agent(AgentType.TRANSCRIPT_ANALYZER)
assert manager.current_agent_type == AgentType.TRANSCRIPT_ANALYZER
```
When working with this codebase:
1. **Understand the Architecture**: Familiarize yourself with ChatSystem, agents, tools, and their interactions
2. **Follow Conventions**: Use type hints, docstrings, PEP 8, and the established patterns
3. **Respect Separation of Concerns**: Core, tools, agents, and interface are distinct layers
4. **Use Existing Patterns**: Follow the tool and agent patterns for consistency
5. **Test Your Changes**: Write tests following pytest conventions
6. **Update Configuration**: Modify `config.yaml` when adding tools/agents
7. **Document Thoroughly**: Add README.md for new tools/agents
8. **Handle Errors Gracefully**: Use try-except blocks and return structured responses
9. **Choose the Right Model**: Use model selection guidelines (simple/general/long_context/reasoning)
10. **Consider Token Usage**: Be mindful of context windows and costs
**Add a new utility tool**:
1. Create `tools/ToolName/` directory
2. Implement `tool_name.py` following the tool pattern
3. Add to `config.yaml` enabled tools list
4. Write tests in `tests/`
**Create a new agent**:
1. Create agent directory under `agents/`
2. Define SYSTEM_PERSONA and execute method
3. Register in `agent_manager.py`
4. Add configuration to `config.yaml`
5. Document in AGENTS_README.md
**Debug tool execution**:
1. Check tool registration: `/tools` in CLI
2. Review tool_executor.py error handling
3. Check function schema generation in tool_adapter.py
4. Verify OpenAI function calling logs
**Optimize context usage**:
1. Use `conversation.get_context_info()`
2. Implement manual trimming if needed
3. Choose appropriate model (gpt-4.1 for long context)
4. Review token counting in ChatEngine
| Component | File Path |
|-----------|-----------|
| Main entry | `ChatSystem/__main__.py` |
| Chat engine | `ChatSystem/core/chat_engine.py` |
| Agent manager | `agents/agent_manager.py` |
| Tool registry | `ChatSystem/tools/tool_registry.py` |
| Configuration | `config.yaml` |
| Environment | `.env` |
| Tests | `pytest.ini`, `tests/` |
**API Key Issues**: Verify `.env` file and `OPENAI_API_KEY` setting
**Tool Not Found**: Check `config.yaml` enabled list and tool discovery
**Agent Switching Fails**: Ensure agent registered in `AgentManager`
**Context Overflow**: Use gpt-4.1 or implement manual trimming
**Import Errors**: Verify `requirements.txt` dependencies installed
---
**Remember**: This is a personal utility toolkit. Prioritize code quality, maintainability, and user experience. Follow established patterns, write tests, and document thoroughly.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/personal-utility-tools-expert/raw