ralphx 0.2.2__py3-none-any.whl → 0.3.5__py3-none-any.whl

ralphx/examples/sample_project/DESIGN.md

@@ -0,0 +1,345 @@
+# Excuse Generator - Design Document
+
+## Overview
+
+The Excuse Generator is a fun, lightweight web application that helps users generate creative excuses for various life situations. Whether you're late to a meeting, forgot a birthday, or missed a deadline, this app provides entertaining (and sometimes surprisingly convincing) excuses at the click of a button.
+
+## Goals
+
+1. **Entertainment First** - The app should be fun to use and generate amusing content
+2. **Simple & Fast** - No account required, instant results, mobile-friendly
+3. **Customizable Output** - Users can tune excuses by category and tone
+4. **Memorable** - Save favorites and track history for repeat use
+
+## Features
+
+### Core Features
+
+#### 1. Excuse Generation
+- Select a **category** for the situation:
+  - Late to work/meeting
+  - Missed deadline
+  - Forgot birthday/anniversary
+  - Didn't reply to message
+  - Skipped event/party
+  - Generic/Other
+- Select a **tone** for the excuse:
+  - Professional (workplace appropriate, formal)
+  - Casual (friendly, conversational)
+  - Dramatic (over-the-top, theatrical)
+  - Absurd (ridiculous, comedy-focused)
+- Click "Generate" to get a random excuse matching the criteria
+- Each excuse is built from templates with variable substitution for variety
+
+#### 2. Favorites System
+- Click a heart icon to save an excuse to favorites
+- View all saved favorites in a dedicated tab
+- Remove excuses from favorites
+- Favorites persist in the database
+
+#### 3. Believability Rating
+- After generating an excuse, rate it 1-5 stars for "believability"
+- Ratings are stored and can be viewed in history
+- Optional: Show average rating for excuse templates
+
+#### 4. History View
+- Browse all previously generated excuses
+- Search by keyword
+- Filter by category, tone, or date range
+- See when each excuse was generated
+- View ratings given
+
+#### 5. Excuse of the Day
+- Homepage displays a featured "Excuse of the Day"
+- Rotates daily (seeded by date for consistency)
+- Pulls from curated high-quality excuse templates
+
+#### 6. Copy to Clipboard
+- One-click button to copy excuse text
+- Visual feedback (checkmark animation) on successful copy
+- Works on mobile and desktop
+
+## Technical Architecture
+
+### Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| Backend | FastAPI (Python 3.10+) |
+| Database | SQLite |
+| Frontend | Vanilla HTML/CSS/JS |
+| Styling | Custom CSS (no framework) |
+
+### Project Structure
+
+```
+excuse-generator/
+├── main.py              # FastAPI application
+├── database.py          # SQLite database operations
+├── models.py            # Pydantic models
+├── templates.py         # Excuse template data
+├── requirements.txt     # Python dependencies
+├── data/
+│   └── excuses.db       # SQLite database file
+└── static/
+    ├── index.html       # Main SPA page
+    ├── styles.css       # Application styles
+    └── app.js           # Frontend JavaScript
+```
+
+### Database Schema
+
+```sql
+-- Excuse templates (seed data)
+CREATE TABLE excuse_templates (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    category TEXT NOT NULL,
+    tone TEXT NOT NULL,
+    template TEXT NOT NULL,
+    variables TEXT,  -- JSON array of variable names
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Generated excuses (history)
+CREATE TABLE generated_excuses (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    template_id INTEGER REFERENCES excuse_templates(id),
+    excuse_text TEXT NOT NULL,
+    category TEXT NOT NULL,
+    tone TEXT NOT NULL,
+    rating INTEGER,  -- 1-5 stars, NULL if not rated
+    is_favorite BOOLEAN DEFAULT FALSE,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Daily excuse selection
+CREATE TABLE daily_excuse (
+    date TEXT PRIMARY KEY,  -- YYYY-MM-DD format
+    template_id INTEGER REFERENCES excuse_templates(id),
+    excuse_text TEXT NOT NULL
+);
+```
+
+### API Endpoints
+
+#### GET /api/health
+Health check endpoint.
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "version": "1.0.0"
+}
+```
+
+#### GET /api/generate
+Generate a random excuse.
+
+**Query Parameters:**
+- `category` (string, optional): Filter by category
+- `tone` (string, optional): Filter by tone
+
+**Response:**
+```json
+{
+  "id": 42,
+  "excuse": "My cat accidentally unplugged my alarm clock while chasing a ghost.",
+  "category": "late",
+  "tone": "absurd",
+  "template_id": 15
+}
+```
+
+#### POST /api/excuses/{id}/favorite
+Toggle favorite status for an excuse.
+
+**Response:**
+```json
+{
+  "id": 42,
+  "is_favorite": true
+}
+```
+
+#### POST /api/excuses/{id}/rate
+Rate an excuse.
+
+**Request Body:**
+```json
+{
+  "rating": 4
+}
+```
+
+**Response:**
+```json
+{
+  "id": 42,
+  "rating": 4
+}
+```
+
+#### GET /api/favorites
+Get all favorited excuses.
+
+**Response:**
+```json
+{
+  "favorites": [
+    {
+      "id": 42,
+      "excuse": "...",
+      "category": "late",
+      "tone": "absurd",
+      "rating": 4,
+      "created_at": "2024-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+#### GET /api/history
+Get excuse generation history.
+
+**Query Parameters:**
+- `category` (string, optional): Filter by category
+- `tone` (string, optional): Filter by tone
+- `search` (string, optional): Search in excuse text
+- `limit` (int, default 50): Max results
+- `offset` (int, default 0): Pagination offset
+
+**Response:**
+```json
+{
+  "excuses": [...],
+  "total": 150,
+  "limit": 50,
+  "offset": 0
+}
+```
+
+#### GET /api/excuse-of-the-day
+Get today's featured excuse.
+
+**Response:**
+```json
+{
+  "excuse": "The traffic was terrible because a family of ducks decided to cross the highway.",
+  "category": "late",
+  "tone": "casual",
+  "date": "2024-01-15"
+}
+```
+
+#### GET /api/categories
+Get list of available categories.
+
+**Response:**
+```json
+{
+  "categories": ["late", "deadline", "birthday", "message", "event", "other"]
+}
+```
+
+#### GET /api/tones
+Get list of available tones.
+
+**Response:**
+```json
+{
+  "tones": ["professional", "casual", "dramatic", "absurd"]
+}
+```
+
+## User Interface
+
+### Layout
+
+The app uses a single-page layout with tabs:
+
+```
++------------------------------------------+
+|  EXCUSE GENERATOR           [History] [*] |
++------------------------------------------+
+|                                          |
+|  Category: [Late ▼]    Tone: [Casual ▼]  |
+|                                          |
+|  +------------------------------------+  |
+|  |                                    |  |
+|  |  "Sorry I'm late, my neighbor's   |  |
+|  |   parrot learned to mimic my      |  |
+|  |   alarm and kept hitting snooze." |  |
+|  |                                    |  |
+|  |  [Copy]  [♡]  Rating: ★★★★☆      |  |
+|  +------------------------------------+  |
+|                                          |
+|        [ Generate New Excuse ]           |
+|                                          |
++------------------------------------------+
+|  Excuse of the Day:                      |
+|  "My GPS took me through a time warp..." |
++------------------------------------------+
+```
+
+### Responsive Design
+
+- Mobile-first approach
+- Single column on phones (<768px)
+- Centered card layout on tablets/desktop
+- Touch-friendly buttons (44px minimum)
+
+### Color Scheme
+
+- Primary: #6366F1 (Indigo)
+- Background: #F8FAFC (Light gray)
+- Card: #FFFFFF
+- Text: #1E293B (Slate)
+- Accent: #F59E0B (Amber for favorites)
+
+## Excuse Template System
+
+Excuses are generated from templates with variable placeholders:
+
+```python
+templates = [
+    {
+        "category": "late",
+        "tone": "absurd",
+        "template": "My {pet} accidentally {action} my {item}.",
+        "variables": {
+            "pet": ["cat", "dog", "hamster", "goldfish"],
+            "action": ["ate", "hid", "unplugged", "sat on"],
+            "item": ["car keys", "alarm clock", "shoes", "phone"]
+        }
+    }
+]
+```
+
+The generator:
+1. Filters templates by category and tone
+2. Picks a random template
+3. Substitutes variables with random choices
+4. Returns the complete excuse
+
+## Error Handling
+
+- All API errors return consistent JSON format:
+  ```json
+  {
+    "error": {
+      "code": "not_found",
+      "message": "Excuse not found"
+    }
+  }
+  ```
+- Frontend shows user-friendly error toasts
+- Database errors are logged server-side
+
+## Future Enhancements (Out of Scope)
+
+- User accounts and cloud sync
+- Sharing excuses on social media
+- Community-submitted templates
+- AI-generated excuses
+- Multi-language support

ralphx/examples/sample_project/README.md

@@ -0,0 +1,37 @@
+# Excuse Generator
+
+A fun web app that generates creative excuses for any situation.
+
+This is a sample project automatically created by RalphX to help you get started.
+Location: `~/.ralphx/samples/excuse-generator/`
+
+## What's Included
+
+- **DESIGN.md** - Complete design document with features, architecture, and API specs
+- **stories.jsonl** - 10 user stories ready for implementation
+- **guardrails.md** - Project-specific coding guidelines
+
+## How to Use
+
+1. Open RalphX dashboard at http://localhost:8765
+2. Click on "Excuse-Generator" project
+3. Open the pre-created workflow "Build Excuse Generator"
+4. Start the Implementation step and watch Claude build your excuse generator!
+
+## The App
+
+When built, the Excuse Generator will feature:
+
+- **Category selection** - Late to work, missed deadline, forgot birthday, etc.
+- **Tone modes** - Professional, casual, dramatic, absurd
+- **Favorites** - Save your best excuses
+- **Believability rating** - Rate how convincing each excuse is
+- **History** - Browse all your generated excuses
+- **Excuse of the day** - Featured excuse on the homepage
+- **Copy to clipboard** - One-click sharing
+
+## Tech Stack
+
+- **Backend**: FastAPI (Python)
+- **Database**: SQLite
+- **Frontend**: Vanilla HTML/CSS/JS (no framework)

ralphx/examples/sample_project/guardrails.md

@@ -0,0 +1,57 @@
+# Excuse Generator - Project Guardrails
+
+## Content Guidelines
+
+- Keep all excuses **PG-rated** and workplace-appropriate
+- No offensive, discriminatory, or harmful content
+- Excuses should be clearly fictional/humorous - avoid anything that could be used maliciously
+- No references to violence, illegal activities, or sensitive topics
+
+## Technical Guidelines
+
+### Frontend
+
+- Use **vanilla JavaScript only** - no React, Vue, or other frameworks
+- No npm dependencies for the frontend
+- Keep JavaScript in a single `app.js` file
+- Use modern ES6+ syntax (const/let, arrow functions, template literals)
+- CSS should be custom - no Tailwind, Bootstrap, or CSS frameworks
+
+### Backend
+
+- Use **FastAPI** for the Python backend
+- SQLite for database - no PostgreSQL, MySQL, or other databases
+- Keep dependencies minimal - only what's in requirements.txt
+- Use Pydantic models for request/response validation
+
+### Code Style
+
+- Follow PEP 8 for Python code
+- Use meaningful variable and function names
+- Add docstrings to all public functions
+- Keep functions small and focused (< 30 lines ideally)
+
+### Database
+
+- All data stored in SQLite at `data/excuses.db`
+- Use parameterized queries to prevent SQL injection
+- Include proper indexes for frequently queried columns
+
+### Performance
+
+- Page load should be instant (< 1 second)
+- No unnecessary API calls
+- Cache static assets appropriately
+
+### Accessibility
+
+- Use semantic HTML elements
+- Include ARIA labels where needed
+- Ensure color contrast meets WCAG AA standards
+- All interactive elements must be keyboard accessible
+
+### Mobile Support
+
+- Mobile-first responsive design
+- Touch targets at least 44x44 pixels
+- No horizontal scrolling on mobile devices

ralphx/examples/sample_project/stories.jsonl

@@ -0,0 +1,10 @@
+{"id": "EXC-001", "title": "Set up project structure", "description": "Initialize the FastAPI application with SQLite database and static file serving for the Excuse Generator web app.", "category": "infrastructure", "priority": "high", "acceptance_criteria": ["FastAPI app runs on localhost:8000", "SQLite database file created at data/excuses.db", "Static files served from /static path", "Health check endpoint at /api/health returns 200 OK", "requirements.txt includes fastapi, uvicorn, and other dependencies"], "dependencies": []}
+{"id": "EXC-002", "title": "Create database schema and models", "description": "Design and implement the SQLite database schema with tables for excuse templates, generated excuses, and daily excuse tracking. Create corresponding Pydantic models.", "category": "backend", "priority": "high", "acceptance_criteria": ["excuse_templates table stores category, tone, template text, and variables", "generated_excuses table tracks history with ratings and favorites", "daily_excuse table stores the excuse of the day", "Pydantic models defined for all database entities", "Database initialization creates tables on startup"], "dependencies": ["EXC-001"]}
+{"id": "EXC-003", "title": "Build excuse template system", "description": "Implement the excuse template system with variable substitution. Create a collection of 20+ excuse templates across all categories and tones.", "category": "backend", "priority": "high", "acceptance_criteria": ["Template system supports variable placeholders like {pet}, {action}, {item}", "Variables are randomly substituted from predefined lists", "At least 20 templates covering all 6 categories", "At least 5 templates per tone (professional, casual, dramatic, absurd)", "Templates seeded into database on first run"], "dependencies": ["EXC-002"]}
+{"id": "EXC-004", "title": "Implement generate excuse endpoint", "description": "Create the /api/generate endpoint that returns a randomly generated excuse based on optional category and tone filters.", "category": "backend", "priority": "high", "acceptance_criteria": ["GET /api/generate returns a random excuse", "Optional category query param filters templates", "Optional tone query param filters templates", "Response includes excuse text, category, tone, and ID", "Generated excuse is saved to history"], "dependencies": ["EXC-003"]}
+{"id": "EXC-005", "title": "Create homepage UI", "description": "Build the main homepage with category/tone selectors, generate button, and excuse display card using vanilla HTML/CSS/JS.", "category": "frontend", "priority": "high", "acceptance_criteria": ["Dropdown selectors for category and tone", "Generate button triggers API call", "Excuse displays in a styled card", "Loading state shown while generating", "Responsive design works on mobile and desktop", "Matches color scheme from design doc"], "dependencies": ["EXC-004"]}
+{"id": "EXC-006", "title": "Add favorites functionality", "description": "Implement the ability to save excuses to favorites, view saved favorites, and remove from favorites.", "category": "feature", "priority": "medium", "acceptance_criteria": ["Heart icon toggles favorite status", "POST /api/excuses/{id}/favorite toggles is_favorite", "GET /api/favorites returns all favorited excuses", "Favorites tab shows saved excuses", "Visual indication when excuse is favorited", "Can unfavorite from the favorites view"], "dependencies": ["EXC-005"]}
+{"id": "EXC-007", "title": "Implement believability rating", "description": "Add a 1-5 star rating system for excuses to track how believable users find them.", "category": "feature", "priority": "medium", "acceptance_criteria": ["Star rating component displays below excuse", "Clicking a star submits rating via API", "POST /api/excuses/{id}/rate saves the rating", "Rating persists and shows in history view", "Visual feedback on rating selection"], "dependencies": ["EXC-005"]}
+{"id": "EXC-008", "title": "Build history view", "description": "Create a history tab showing all previously generated excuses with search and filtering capabilities.", "category": "feature", "priority": "medium", "acceptance_criteria": ["GET /api/history returns paginated excuse history", "History tab displays excuses in chronological order", "Search box filters by excuse text", "Dropdown filters for category and tone", "Pagination or infinite scroll for large history", "Shows rating and favorite status for each item"], "dependencies": ["EXC-006", "EXC-007"]}
+{"id": "EXC-009", "title": "Build excuse of the day feature", "description": "Implement the daily featured excuse that rotates each day and displays prominently on the homepage.", "category": "feature", "priority": "medium", "acceptance_criteria": ["GET /api/excuse-of-the-day returns today's featured excuse", "Daily excuse is deterministic based on date (seeded random)", "Excuse of the day displays at bottom of homepage", "Different excuse shown each calendar day", "Uses curated selection of best templates"], "dependencies": ["EXC-003"]}
+{"id": "EXC-010", "title": "Add copy to clipboard", "description": "Implement one-click copy functionality with visual feedback for easy sharing of excuses.", "category": "feature", "priority": "low", "acceptance_criteria": ["Copy button appears on each excuse card", "Clicking copies excuse text to clipboard", "Button shows checkmark animation on success", "Works on both mobile and desktop browsers", "Fallback for browsers without clipboard API"], "dependencies": ["EXC-005"]}

ralphx/mcp/__init__.py

@@ -3,8 +3,12 @@
 This module provides a modular MCP server implementation that exposes RalphX
 functionality as tools that Claude Code can use.
 
-Usage:
-    claude mcp add ralphx -- ralphx mcp
+Usage (Linux/Mac):
+    claude mcp add ralphx -e PYTHONDONTWRITEBYTECODE=1 -- "$(which ralphx)" mcp
+    # Mac zsh: if "which" fails, run: conda init zsh && source ~/.zshrc
+
+Usage (Windows - find path first with: where.exe ralphx):
+    claude mcp add ralphx -e PYTHONDONTWRITEBYTECODE=1 -- C:\\path\\to\\ralphx.exe mcp
 """
 
 from ralphx.mcp.server import MCPServer

ralphx/mcp/registry.py

@@ -39,11 +39,11 @@ class ToolRegistry:
         """Check if a tool is registered."""
         return name in self._tools
 
-    def call(self, name: str, **kwargs) -> Any:
+    def call(self, tool_name: str, **kwargs) -> Any:
         """Call a tool by name with arguments."""
-        tool = self._tools.get(name)
+        tool = self._tools.get(tool_name)
         if not tool:
-            raise KeyError(f"Unknown tool: {name}")
+            raise KeyError(f"Unknown tool: {tool_name}")
         return tool.handler(**kwargs)
 
     def get_definitions(self) -> list[dict]:

ralphx/mcp/server.py

@@ -16,6 +16,26 @@ from ralphx.mcp.tools import get_all_tools
 # Version from pyproject.toml
 VERSION = "0.1.5"
 
+# MCP protocol version we support
+PROTOCOL_VERSION = "2025-03-26"
+
+# Server instructions for Claude - explains what RalphX is and how to use it
+SERVER_INSTRUCTIONS = """RalphX is an Autonomous AI Loop Orchestration system. It helps you run autonomous AI workflows.
+
+Key concepts:
+- Project: A directory registered with RalphX (your codebase)
+- Loop: An autonomous workflow defined in YAML that runs repeatedly
+- Work Item: Data generated/consumed by loops (user stories, tasks, etc.)
+- Workflow: A multi-step pipeline (research → implement → test)
+
+Start with ralphx_help to see common workflows and all 67 available tools.
+
+Quick start:
+1. ralphx_list_projects - See registered projects
+2. ralphx_list_loops - See available loops in a project
+3. ralphx_start_loop - Run a loop
+4. ralphx_list_runs - Monitor progress"""
+
 
 class MCPServer:
     """MCP protocol handler for RalphX.
@@ -28,13 +48,11 @@ class MCPServer:
         """Initialize the MCP server with all registered tools."""
         self.registry = ToolRegistry()
         self.registry.register_all(get_all_tools())
+        self._initialized = False  # Track whether initialize handshake completed
 
     def run(self) -> None:
         """Run the MCP server, reading from stdin and writing to stdout."""
-        # Send initialization message
-        self._send_init()
-
-        # Process messages
+        # Process messages - wait for client to initiate
         try:
             for line in sys.stdin:
                 line = line.strip()
@@ -55,22 +73,6 @@ class MCPServer:
             # Exit gracefully
             pass
 
-    def _send_init(self) -> None:
-        """Send MCP initialization message."""
-        self._send({
-            "jsonrpc": "2.0",
-            "method": "initialized",
-            "params": {
-                "serverInfo": {
-                    "name": "ralphx",
-                    "version": VERSION,
-                },
-                "capabilities": {
-                    "tools": True,
-                },
-            },
-        })
-
     def _send(self, message: dict) -> None:
         """Send a JSON-RPC message to stdout."""
         print(json.dumps(message), flush=True)
@@ -92,11 +94,23 @@ class MCPServer:
         params = message.get("params", {})
         msg_id = message.get("id")
 
+        # Per MCP spec: ping is allowed before initialization
+        if method == "ping":
+            return {
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "result": {},
+            }
+
         if method == "initialize":
+            # Respond to client's initialize request per MCP spec
+            # Client will then send notifications/initialized to signal ready
+            self._initialized = True
             return {
                 "jsonrpc": "2.0",
                 "id": msg_id,
                 "result": {
+                    "protocolVersion": PROTOCOL_VERSION,
                     "serverInfo": {
                         "name": "ralphx",
                         "version": VERSION,
@@ -106,6 +120,19 @@ class MCPServer:
                             "listChanged": False,
                         },
                     },
+                    "instructions": SERVER_INSTRUCTIONS,
+                },
+            }
+
+        # Per MCP spec: most requests require initialization first
+        # (ping and initialize are handled above)
+        if not self._initialized and msg_id is not None:
+            return {
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "error": {
+                    "code": -32600,
+                    "message": "Server not initialized. Send 'initialize' request first.",
                 },
             }
 
@@ -123,11 +150,13 @@ class MCPServer:
             arguments = params.get("arguments", {})
 
             if not self.registry.has(tool_name):
+                # Per MCP spec: unknown tool is Invalid params (-32602), not Method not found
+                # because tools/call method exists, the tool name is a parameter
                 return {
                     "jsonrpc": "2.0",
                     "id": msg_id,
                     "error": {
-                        "code": -32601,
+                        "code": -32602,
                         "message": f"Unknown tool: {tool_name}",
                     },
                 }
@@ -135,11 +164,27 @@ class MCPServer:
             try:
                 result = self.registry.call(tool_name, **arguments)
 
-                # Format result
-                if isinstance(result, dict):
-                    result_text = json.dumps(result, indent=2)
-                else:
-                    result_text = str(result)
+                # Format result - handle serialization errors gracefully
+                try:
+                    if isinstance(result, dict):
+                        result_text = json.dumps(result, indent=2)
+                    else:
+                        result_text = str(result)
+                except (TypeError, ValueError) as serialize_err:
+                    # Non-JSON-serializable result - return as tool error, not protocol error
+                    return {
+                        "jsonrpc": "2.0",
+                        "id": msg_id,
+                        "result": {
+                            "content": [
+                                {
+                                    "type": "text",
+                                    "text": f"Tool returned non-serializable result: {serialize_err}",
+                                }
+                            ],
+                            "isError": True,
+                        },
+                    }
 
                 return {
                     "jsonrpc": "2.0",
@@ -169,18 +214,43 @@ class MCPServer:
                     },
                 }
             except Exception as e:
+                # Unexpected tool execution error - return as tool error for LLM recovery
                 return {
                     "jsonrpc": "2.0",
                     "id": msg_id,
-                    "error": {
-                        "code": -32603,
-                        "message": str(e),
+                    "result": {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": f"Tool execution error: {e}",
+                            }
+                        ],
+                        "isError": True,
                     },
                 }
 
+        if method == "notifications/initialized":
+            # Client signals it's ready for normal operations
+            # No response needed for notifications
+            return None
+
         if method == "notifications/cancelled":
+            # Client cancelled a request
             return None
 
+        # Unknown method handling per JSON-RPC 2.0:
+        # - If it has an id, it's a request and MUST return error
+        # - If no id, it's a notification and can be silently ignored
+        if msg_id is not None:
+            return {
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "error": {
+                    "code": -32601,
+                    "message": f"Method not found: {method}",
+                },
+            }
+        # Notification we don't handle - ignore silently per JSON-RPC spec
         return None