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

ralphx/api/routes/loops.py

@@ -849,14 +849,14 @@ async def create_simple_loop(slug: str, request: CreateSimpleLoopRequest):
                     status_code=status.HTTP_400_BAD_REQUEST,
                     detail=f"Source loop '{source_loop}' not found in this project.",
                 )
-            namespace = source_loop  # Use source loop name as namespace
+            source_loop_name = source_loop  # Use source loop name
         elif request.stories_source and request.stories_source.type == "content":
-            # For JSONL uploads, derive namespace from request or loop_id
-            namespace = request.stories_source.namespace or loop_id.replace("-", "_")
+            # For JSONL uploads, derive source from request or loop_id
+            source_loop_name = request.stories_source.namespace or loop_id.replace("-", "_")
 
         config_yaml = generate_simple_implementation_config(
             name=loop_id,
-            namespace=namespace,
+            source_loop=source_loop_name,
             display_name=display_name,
             description=description,
         )

ralphx/api/routes/planning.py

@@ -269,9 +269,18 @@ async def stream_planning_response(slug: str, workflow_id: str):
             detail="Planning session is not active",
         )
 
-    # Get workflow for context
+    # Get workflow and current step for context
     workflow = pdb.get_workflow(workflow_id)
 
+    # Get the step to access its config (tools, model, timeout)
+    step = pdb.get_workflow_step(session["step_id"])
+    step_config = step.get("config", {}) if step else {}
+
+    # Extract configuration from step
+    allowed_tools = step_config.get("allowedTools", [])
+    model = step_config.get("model", "opus")  # Default to opus for design docs
+    timeout = step_config.get("timeout", 180)
+
     async def generate_response():
         """Generate streaming response from Claude."""
         import json
@@ -290,7 +299,12 @@ async def stream_planning_response(slug: str, workflow_id: str):
         accumulated = ""
 
         try:
-            async for event in service.stream_response(messages):
+            async for event in service.stream_response(
+                messages,
+                model=model,
+                tools=allowed_tools if allowed_tools else None,
+                timeout=timeout,
+            ):
                 if event.type == AdapterEvent.TEXT:
                     text = event.text or ""
                     accumulated += text
@@ -405,9 +419,9 @@ async def complete_planning_session(
 
     # Get workflow info
     workflow = pdb.get_workflow(workflow_id)
-    namespace = workflow["namespace"]
 
     # Save artifacts as project resources
+    # Use workflow_id for unique filenames (namespace was removed in schema v16)
     from pathlib import Path
     from datetime import datetime
 
@@ -416,7 +430,7 @@ async def complete_planning_session(
         resource_path = Path(project["path"]) / ".ralphx" / "resources"
         resource_path.mkdir(parents=True, exist_ok=True)
 
-        doc_filename = f"design-doc-{namespace}.md"
+        doc_filename = f"design-doc-{workflow_id}.md"
         doc_path = resource_path / doc_filename
         doc_path.write_text(artifacts["design_doc"])
 
@@ -442,7 +456,7 @@ async def complete_planning_session(
         resource_path = Path(project["path"]) / ".ralphx" / "resources"
         resource_path.mkdir(parents=True, exist_ok=True)
 
-        guardrails_filename = f"guardrails-{namespace}.md"
+        guardrails_filename = f"guardrails-{workflow_id}.md"
         guardrails_path = resource_path / guardrails_filename
         guardrails_path.write_text(artifacts["guardrails"])
 

ralphx/api/routes/projects.py

@@ -33,12 +33,22 @@ class ProjectResponse(BaseModel):
     path: str
     design_doc: Optional[str] = None
     created_at: str
+    path_valid: bool = True  # Whether the project directory exists
 
     model_config = {"from_attributes": True}
 
     @classmethod
-    def from_project(cls, project: Project) -> "ProjectResponse":
-        """Create from Project model."""
+    def from_project(cls, project: Project, check_path: bool = True) -> "ProjectResponse":
+        """Create from Project model.
+
+        Args:
+            project: Project model instance.
+            check_path: If True, check if project path exists.
+        """
+        path_valid = True
+        if check_path:
+            path_valid = Path(project.path).exists()
+
         return cls(
             id=project.id,
             slug=project.slug,
@@ -46,6 +56,7 @@ class ProjectResponse(BaseModel):
             path=str(project.path),
             design_doc=project.design_doc,
             created_at=project.created_at.isoformat() if project.created_at else "",
+            path_valid=path_valid,
         )
 
 
@@ -68,6 +79,13 @@ class ProjectWithStats(ProjectResponse):
     stats: ProjectStats = Field(default_factory=ProjectStats)
 
 
+class ProjectUpdate(BaseModel):
+    """Request model for updating a project."""
+
+    name: Optional[str] = Field(None, description="Human-readable name")
+    path: Optional[str] = Field(None, description="New path to project directory (for relinking)")
+
+
 def get_manager() -> ProjectManager:
     """Get project manager instance."""
     return ProjectManager()
@@ -165,11 +183,75 @@ async def get_project(slug: str):
         path=base.path,
         design_doc=base.design_doc,
         created_at=base.created_at,
+        path_valid=base.path_valid,
         stats=stats,
     )
     return response
 
 
+@router.patch("/{slug}", response_model=ProjectResponse)
+async def update_project(slug: str, data: ProjectUpdate):
+    """Update a project's metadata or relink its path.
+
+    Use this to:
+    - Rename a project
+    - Relink a project to a new directory (when original path moved/missing)
+    """
+    manager = get_manager()
+    project = manager.get_project(slug)
+
+    if not project:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Project not found: {slug}",
+        )
+
+    # Handle path update (relink)
+    if data.path is not None:
+        new_path = Path(data.path)
+
+        # Validate new path exists
+        if not new_path.exists():
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"New path does not exist: {data.path}",
+            )
+
+        if not new_path.is_dir():
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"New path is not a directory: {data.path}",
+            )
+
+        # Check if new path already has .ralphx directory
+        ralphx_dir = new_path / ".ralphx"
+        if ralphx_dir.exists():
+            # Warn if it has a different project (check project.db)
+            # For now, allow it - user is responsible for ensuring correct path
+            pass
+        else:
+            # Create .ralphx directory at new location
+            from ralphx.core.workspace import ensure_project_ralphx
+            try:
+                ensure_project_ralphx(new_path)
+            except Exception as e:
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail=f"Failed to initialize project at new path: {e}",
+                )
+
+        # Update path in global database
+        manager.global_db.update_project(slug, path=str(new_path.resolve()))
+
+    # Handle name update
+    if data.name is not None:
+        manager.global_db.update_project(slug, name=data.name)
+
+    # Return updated project
+    project = manager.get_project(slug)
+    return ProjectResponse.from_project(project)
+
+
 @router.delete("/{slug}", status_code=status.HTTP_204_NO_CONTENT)
 async def delete_project(
     slug: str,

ralphx/api/routes/templates.py

@@ -4,7 +4,7 @@ Templates are global, read-only, and shipped with RalphX.
 No authentication required - templates are public.
 
 Includes:
-- Loop templates (research, implementation, etc.)
+- Loop templates (extractgen_requirements, implementation, etc.)
 - Loop builder templates (planning, implementation with Phase 1)
 - Permission templates (planning, implementation, read_only, etc.)
 """
@@ -21,6 +21,8 @@ from ralphx.core.loop_templates import (
     create_loop_from_template,
     get_loop_template,
     list_loop_templates,
+    PLANNING_EXTRACT_PROMPT,
+    IMPLEMENTATION_IMPLEMENT_PROMPT,
 )
 from ralphx.core.permission_templates import (
     apply_template_to_loop,
@@ -85,7 +87,7 @@ async def get_template_by_name(name: str) -> TemplateDetail:
     No authentication required - templates are public.
 
     Args:
-        name: Template name (e.g., 'research', 'implementation')
+        name: Template name (e.g., 'extractgen_requirements', 'implementation')
 
     Returns:
         Full template with config and YAML representation
@@ -407,3 +409,114 @@ async def apply_permission_template_endpoint(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail=str(e),
         )
+
+
+# ============================================================================
+# Step Prompts (System Prompts for Workflow Steps)
+# ============================================================================
+
+# Template variable documentation for each loop type
+TEMPLATE_VARIABLES = {
+    "generator": {
+        "{{input_item.title}}": {
+            "description": "Title of the current item (not commonly used in generator)",
+            "required": False,
+        },
+        "{{existing_stories}}": {
+            "description": "List of already-generated stories to avoid duplicates",
+            "required": True,
+        },
+        "{{total_stories}}": {
+            "description": "Count of stories generated so far",
+            "required": False,
+        },
+        "{{category_stats}}": {
+            "description": "Statistics by category for ID assignment",
+            "required": False,
+        },
+        "{{inputs_list}}": {
+            "description": "List of input documents available",
+            "required": False,
+        },
+    },
+    "consumer": {
+        "{{input_item.title}}": {
+            "description": "Title of the story being implemented",
+            "required": True,
+        },
+        "{{input_item.content}}": {
+            "description": "Full story content",
+            "required": True,
+        },
+        "{{input_item.metadata}}": {
+            "description": "Story metadata (priority, category, etc.)",
+            "required": False,
+        },
+        "{{implemented_summary}}": {
+            "description": "Summary of previously implemented stories",
+            "required": False,
+        },
+    },
+}
+
+
+class TemplateVariableInfo(BaseModel):
+    """Information about a template variable."""
+
+    name: str
+    description: str
+    required: bool
+
+
+class StepPromptResponse(BaseModel):
+    """Response for default step prompt endpoint."""
+
+    prompt: str
+    loop_type: str
+    display_name: str
+    variables: list[TemplateVariableInfo]
+
+
+@router.get("/step-prompts/{loop_type}", response_model=StepPromptResponse)
+async def get_default_step_prompt(loop_type: str):
+    """Get default system prompt for a step type.
+
+    Args:
+        loop_type: Either 'generator' or 'consumer'
+
+    Returns:
+        The default prompt content along with template variable documentation.
+    """
+    prompts = {
+        "generator": {
+            "prompt": PLANNING_EXTRACT_PROMPT,
+            "display_name": "Generator (Story Extraction)",
+        },
+        "consumer": {
+            "prompt": IMPLEMENTATION_IMPLEMENT_PROMPT,
+            "display_name": "Consumer (Implementation)",
+        },
+    }
+
+    if loop_type not in prompts:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Unknown loop type: {loop_type}. Must be 'generator' or 'consumer'.",
+        )
+
+    prompt_info = prompts[loop_type]
+    variables = TEMPLATE_VARIABLES.get(loop_type, {})
+
+    return StepPromptResponse(
+        prompt=prompt_info["prompt"].strip(),
+        loop_type=loop_type,
+        display_name=prompt_info["display_name"],
+        variables=[
+            TemplateVariableInfo(
+                name=name,
+                description=info["description"],
+                required=info["required"],
+            )
+            for name, info in variables.items()
+        ],
+    )

ralphx/api/routes/workflows.py

@@ -62,7 +62,6 @@ class WorkflowResponse(BaseModel):
     id: str
     template_id: Optional[str] = None
     name: str
-    namespace: str
     status: str
     current_step: int
     created_at: str
@@ -126,6 +125,7 @@ class CreateStepRequest(BaseModel):
     step_type: str = Field(..., pattern=r"^(interactive|autonomous)$")
     description: Optional[str] = None
     loop_type: Optional[str] = None
+    template: Optional[str] = Field(None, max_length=100)  # Template name (e.g., 'webgen_requirements')
     skippable: bool = False
     # Autonomous step execution settings (step config overrides template defaults)
     model: Optional[str] = Field(None, pattern=r"^(sonnet|sonnet-1m|opus|haiku)$")
@@ -135,6 +135,8 @@ class CreateStepRequest(BaseModel):
     max_iterations: Optional[int] = Field(None, ge=0, le=10000)  # 0 = unlimited
     cooldown_between_iterations: Optional[int] = Field(None, ge=0, le=300)  # seconds
     max_consecutive_errors: Optional[int] = Field(None, ge=1, le=100)
+    # Custom prompt (autonomous steps only)
+    custom_prompt: Optional[str] = Field(None, max_length=50000)
 
 
 class UpdateStepRequest(BaseModel):
@@ -147,6 +149,7 @@ class UpdateStepRequest(BaseModel):
     step_type: Optional[str] = Field(None, pattern=r"^(interactive|autonomous)$")
     description: Optional[str] = None
     loop_type: Optional[str] = None
+    template: Optional[str] = Field(None, max_length=100)  # Template name (e.g., 'webgen_requirements')
     skippable: Optional[bool] = None
     # Autonomous step execution settings (step config overrides template defaults)
     model: Optional[str] = Field(None, pattern=r"^(sonnet|sonnet-1m|opus|haiku)$")
@@ -156,6 +159,8 @@ class UpdateStepRequest(BaseModel):
     max_iterations: Optional[int] = Field(None, ge=0, le=10000)  # 0 = unlimited
     cooldown_between_iterations: Optional[int] = Field(None, ge=0, le=300)  # seconds
     max_consecutive_errors: Optional[int] = Field(None, ge=1, le=100)
+    # Custom prompt (autonomous steps only)
+    custom_prompt: Optional[str] = Field(None, max_length=50000)
 
 
 # Valid tools for autonomous steps
@@ -216,23 +221,6 @@ def _get_project_db(slug: str) -> ProjectDatabase:
     return ProjectDatabase(project["path"])
 
 
-def _generate_namespace(name: str) -> str:
-    """Generate a valid namespace from a workflow name."""
-    import re
-
-    # Convert to lowercase, replace spaces with dashes
-    ns = name.lower().replace(" ", "-")
-    # Remove invalid characters
-    ns = re.sub(r"[^a-z0-9_-]", "", ns)
-    # Ensure it starts with a letter
-    if not ns or not ns[0].isalpha():
-        ns = "w" + ns
-    # Truncate to 64 chars and add unique suffix
-    ns = ns[:56]
-    suffix = uuid.uuid4().hex[:7]
-    return f"{ns}-{suffix}"
-
-
 def _workflow_to_response(
     workflow: dict, steps: list[dict], pdb: Optional[ProjectDatabase] = None
 ) -> WorkflowResponse:
@@ -360,7 +348,6 @@ def _workflow_to_response(
         id=workflow["id"],
         template_id=workflow.get("template_id"),
         name=workflow["name"],
-        namespace=workflow["namespace"],
         status=workflow["status"],
         current_step=workflow["current_step"],
         created_at=workflow["created_at"],
@@ -505,9 +492,8 @@ async def create_workflow(slug: str, request: CreateWorkflowRequest):
     """
     pdb = _get_project_db(slug)
 
-    # Generate unique ID and namespace
+    # Generate unique ID
     workflow_id = f"wf-{uuid.uuid4().hex[:12]}"
-    namespace = _generate_namespace(request.name)
 
     # Get template steps if template specified (templates still use "phases" internally)
     template_steps = []
@@ -525,7 +511,6 @@ async def create_workflow(slug: str, request: CreateWorkflowRequest):
     workflow = pdb.create_workflow(
         id=workflow_id,
         name=request.name,
-        namespace=namespace,
         template_id=request.template_id,
         status="draft",
     )
@@ -1068,9 +1053,12 @@ async def create_step(slug: str, workflow_id: str, request: CreateStepRequest):
             )
 
     # Build config - include autonomous settings only for autonomous steps
+    # Note: Strip template to normalize whitespace; empty/whitespace-only becomes None
+    stripped_template = request.template.strip() if request.template else None
     config: dict[str, Any] = {
         "description": request.description,
         "loopType": request.loop_type,
+        "template": stripped_template if stripped_template else None,
         "skippable": request.skippable,
     }
 
@@ -1172,6 +1160,10 @@ async def update_step(slug: str, workflow_id: str, step_id: int, request: Update
         config_updates["description"] = request.description
     if request.loop_type is not None:
         config_updates["loopType"] = request.loop_type
+    if request.template is not None:
+        # Empty string or whitespace-only means clear template, otherwise store stripped value
+        stripped_template = request.template.strip()
+        config_updates["template"] = stripped_template if stripped_template else None
     if request.skippable is not None:
         config_updates["skippable"] = request.skippable
 
@@ -1190,6 +1182,13 @@ async def update_step(slug: str, workflow_id: str, step_id: int, request: Update
             config_updates["cooldown_between_iterations"] = request.cooldown_between_iterations
         if request.max_consecutive_errors is not None:
             config_updates["max_consecutive_errors"] = request.max_consecutive_errors
+        # Custom prompt
+        if request.custom_prompt is not None:
+            # Empty string means clear custom prompt
+            if request.custom_prompt.strip():
+                config_updates["customPrompt"] = request.custom_prompt
+            else:
+                config_updates["customPrompt"] = None
     elif request.step_type == "interactive":
         # Changing from autonomous to interactive: clear autonomous-only config
         config_updates["model"] = None
@@ -1198,6 +1197,7 @@ async def update_step(slug: str, workflow_id: str, step_id: int, request: Update
         config_updates["max_iterations"] = None
         config_updates["cooldown_between_iterations"] = None
         config_updates["max_consecutive_errors"] = None
+        config_updates["customPrompt"] = None
 
     if config_updates:
         current_config = step.get("config") or {}

ralphx/cli.py

@@ -1315,16 +1315,31 @@ def list_imports(
 def mcp_server() -> None:
     """Start the MCP server for Claude Code integration.
 
-    This command starts the MCP (Model Context Protocol) server that allows
-    Claude Code to interact with RalphX projects, loops, and work items.
+    This command starts the MCP (Model Context Protocol) server that exposes
+    67 tools for full RalphX management through Claude Code.
 
     To add RalphX to Claude Code, run:
-        claude mcp add ralphx -- ralphx mcp
+        Linux/Mac: claude mcp add ralphx -e PYTHONDONTWRITEBYTECODE=1 -- "$(which ralphx)" mcp
+        Mac (zsh): if "which" fails, first run: conda init zsh && source ~/.zshrc
+        Windows:   find path with "where.exe ralphx", then:
+                   claude mcp add ralphx -e PYTHONDONTWRITEBYTECODE=1 -- C:\\path\\to\\ralphx.exe mcp
 
     Then in Claude Code, you can ask Claude to:
-        - List your RalphX projects
-        - Start/stop loops
-        - View and manage work items
+        - Manage projects (add, remove, list, diagnose)
+        - Control loops (start, stop, configure, validate)
+        - Create and run workflows (multi-step task pipelines)
+        - Track work items (user stories, tasks, research notes)
+        - Monitor runs and view logs
+        - Set up permissions and guardrails
+        - Import content and manage resources
+        - Run system health checks and diagnostics
+
+    Example prompts:
+        "List my RalphX projects"
+        "Start the planning loop on my-app"
+        "Create a workflow for implementing the auth feature"
+        "Why did the last run fail?"
+        "Check if my system is set up correctly"
     """
     from ralphx.mcp_server import main as mcp_main