add claude files (#1157)

Author: zzstoatzz

CLAUDE.md

@@ -0,0 +1,44 @@
+# Marvin - AI Engineering Toolkit
+
+Marvin is a lightweight AI engineering toolkit for building natural language interfaces that are reliable, scalable, and easy to trust.
+
+## Architecture & Design Philosophy
+
+- **Aggressively minimal and elegant**: Keep implementations simple and focused
+- **Functional first**: Prefer functional approaches, use classes where justified  
+- **Type-safe**: Full type annotations, modern Python syntax (3.10+)
+- **Private internals**: Keep implementation details "private" (e.g. `def _impl`)
+
+## Key Components
+
+- **Engine**: Core AI interaction layer
+- **Tasks**: Structured AI task definitions and execution
+- **Tools**: Extensible function calling capabilities
+- **Agents**: AI agents with tool access and memory
+- **Memory**: Persistent conversation and context storage
+- **Handlers**: Event processing and routing
+- **CLI**: Command-line interface for common operations
+
+## Development Guidelines
+
+### Type Hints
+- Use `X | Y` instead of `Union[X, Y]`
+- Use builtins like `list`, `dict` instead of `typing.List`, `typing.Dict`
+- Use `T | None` instead of `Optional`
+
+### Dependencies & Running
+- Use `uv` for dependency management and script execution
+- Install deps: `uv sync` or `uv sync --extra foo`
+- Run scripts: `uv run some/script.py` or `uv run --with pandas script.py`
+- Testing: `uv run pytest` or `uv run pytest -n3` for parallel
+
+### Finding Things
+- Use `rg` for searching, not grep
+- Use `ls` and `tree` for navigation
+- Check git context with `gh` and `git` commands
+- Think like a hacker with good intentions - search in site-packages when needed
+
+### Linter Philosophy
+- Empirically understand by running code
+- Linter tells basic truths but may be orthogonal to goals
+- Don't obsess over upstream linter errors, use as clues when relevant 

examples/slackbot/CLAUDE.md

@@ -0,0 +1,52 @@
+# Marvin Slackbot
+
+An intelligent Slack bot built with Marvin that provides AI-powered assistance in Slack channels.
+
+## Architecture
+
+- **`slack.py`**: Core Slack API integration and event handling
+- **`core.py`**: Bot logic and message processing pipeline  
+- **`api.py`**: FastAPI web server for Slack webhooks
+- **`modules.py`**: Modular bot functionality and plugins
+- **`search.py`**: Search capabilities and knowledge retrieval
+- **`wrap.py`**: Message formatting and response wrapping
+- **`strings.py`**: String constants and templates
+- **`settings.py`**: Configuration management
+
+## Key Features
+
+- Event-driven message processing
+- Modular plugin system for extensibility
+- Context-aware conversations with memory
+- Search integration for knowledge lookup
+- FastAPI webhook endpoint for Slack events
+- Docker deployment ready
+
+## Development Notes
+
+- Bot runs as FastAPI server listening for Slack events
+- Uses Slack's Events API for real-time message processing
+- Maintains conversation context and memory across interactions
+- Modular design allows easy addition of new capabilities
+- Environment-based configuration via settings
+
+## Running the Bot
+
+```bash
+# Install dependencies
+uv sync
+
+# Start the bot server
+uv run examples/slackbot/start.py
+
+# Or with Docker
+docker build -f examples/slackbot/Dockerfile.slackbot -t marvin-slackbot .
+docker run marvin-slackbot
+```
+
+## Configuration
+
+Set up environment variables or `.env` file:
+- Slack bot token and signing secret
+- AI model configuration  
+- Database settings for memory persistence 

goose_horror_story.txt

@@ -0,0 +1,36 @@
+# Marvin Agents
+
+AI agents with tool access, memory, and autonomous decision-making capabilities.
+
+## Core Concepts
+
+- **Agent**: Autonomous AI entity that can use tools and maintain memory
+- **Tool Integration**: Seamless function calling with type safety
+- **Memory Persistence**: Conversation history and context retention
+- **Decision Making**: Goal-oriented task execution
+
+## Key Components
+
+- Agent class with tool orchestration
+- Memory management for context persistence  
+- Tool registration and execution framework
+- Event handling for agent actions
+
+## Usage Patterns
+
+```python
+from marvin import Agent
+
+# Create agent with tools
+agent = Agent(tools=[my_tool_fn])
+
+# Run autonomous task
+result = agent.run("Analyze the data and create a report")
+```
+
+## Design Notes
+
+- Agents are stateful and maintain conversation context
+- Tools are regular Python functions with type hints
+- Memory is automatically managed and persisted
+- Agents can chain tool calls to accomplish complex tasks 

src/marvin/agents/CLAUDE.md

@@ -0,0 +1,35 @@
+# Marvin Engine
+
+Task orchestration and execution engine that coordinates actors, manages conversations, and handles tool calls.
+
+## Core Components
+
+- **`orchestrator.py`**: Main execution loop - manages task dependencies, actor turns, message flow, and MCP servers
+- **`streaming.py`**: Real-time event handling during agent execution  
+- **`end_turn.py`**: Special tools that end agent turns (MarkTaskSuccessful, DelegateToActor, PostMessage, etc.)
+- **`events.py`**: Event types for tool calls, completions, errors
+- **`llm.py`**: Basic LLM message types
+
+## Orchestrator Flow
+
+1. **Task Collection**: Gathers ready tasks and dependencies via `get_all_tasks()`
+2. **Tool Assembly**: Collects regular tools + end-turn tools from tasks/actors
+3. **Memory Integration**: Auto-searches memories based on recent messages
+4. **System Prompt**: Builds context from actor, instructions, and assigned tasks
+5. **Agent Execution**: Runs pydantic-ai agent with streaming event handling
+6. **Turn Management**: Processes end-turn tools, updates task states
+
+## Key Classes
+
+- `Orchestrator`: Main coordinator with `run()` and `run_once()` methods
+- `SystemPrompt`: Jinja template combining actor, instructions, and tasks
+- `EndTurn` subclasses: Tools that mark tasks complete/failed/skipped or delegate
+
+## Usage
+
+```python
+from marvin.engine.orchestrator import Orchestrator
+
+orchestrator = Orchestrator(tasks=[my_task], thread=thread)
+results = await orchestrator.run(max_turns=5)
+``` 

src/marvin/engine/CLAUDE.md

@@ -0,0 +1,38 @@
+# Marvin Tasks
+
+Structured AI task definitions and execution framework for reliable, type-safe AI operations.
+
+## Core Concepts
+
+- **Task**: Declarative AI operation with clear inputs/outputs
+- **Type Safety**: Full Pydantic validation of task parameters and results
+- **Reliability**: Built-in retry logic and error handling
+- **Composability**: Tasks can be chained and combined
+
+## Task Types
+
+- **Classification**: Categorize inputs into predefined classes
+- **Extraction**: Pull structured data from unstructured text
+- **Generation**: Create content based on specifications
+- **Transformation**: Convert data from one format to another
+
+## Usage Patterns
+
+```python
+from marvin import task
+
+@task
+def extract_contact_info(text: str) -> ContactInfo:
+    """Extract contact information from text"""
+    ...
+
+# Task automatically handles AI interaction
+result = extract_contact_info("Call John at 555-1234")
+```
+
+## Design Philosophy
+
+- Tasks are pure functions with AI capabilities
+- Type hints drive behavior and validation
+- Docstrings provide context to the AI model
+- Results are guaranteed to match return type annotations 

src/marvin/tasks/CLAUDE.md

@@ -0,0 +1,43 @@
+# Marvin Tools
+
+Minimal tool infrastructure - most tools come from agents, tasks, memories, and MCP servers.
+
+## What's Here
+
+- **`thread.py`**: Single function `post_message_to_agents()` for inter-agent communication
+- **`interactive/cli.py`**: Interactive CLI tools for user input during agent execution
+
+## Tool Sources
+
+Tools are provided by:
+- **Agent.get_tools()**: Agent-specific functions  
+- **Task.get_tools()**: Task-related functions
+- **Memory.get_tools()**: Memory search/retrieval functions
+- **MCP Servers**: External tools via Model Context Protocol
+
+## Utilities (`utilities/tools.py`)
+
+- **`update_fn()`**: Modify function name/docstring dynamically
+- **`wrap_tool_errors()`**: Convert exceptions to `ModelRetry` for pydantic-ai
+- **`ResultTool`**: Dataclass for result-type tools
+
+## Tool Error Handling
+
+```python
+# All tools get wrapped automatically
+@wrap_tool_errors  
+def my_tool():
+    # Any exception becomes ModelRetry
+    raise ValueError("Tool failed")
+```
+
+## MCP Integration
+
+External tools via MCP servers are discovered and wrapped automatically:
+- Server tools converted to pydantic-ai format
+- Full async/sync support  
+- Error handling via `_mcp_tool_wrapper()`
+
+## Usage Pattern
+
+Tools are regular Python functions - no special base classes required. Function signature + docstring = tool schema.