Add Python project structure, models, and tools

Co-authored-by: MinecraftFuns <25814618+MinecraftFuns@users.noreply.github.com>

Author: Copilot

python/langchain/.python-version

@@ -0,0 +1 @@
+3.12

python/langchain/README.md

@@ -0,0 +1,133 @@
+# PromptPipe Agent
+
+LangChain-based agentic conversation flow for PromptPipe. This Python service handles all intelligent conversation processing, while the Go layer acts as a pure message delivery service.
+
+## Architecture
+
+This service implements a 3-bot architecture using LangChain:
+
+- **Coordinator Agent**: Routes conversations and manages overall flow
+- **Intake Agent**: Conducts intake conversations and builds user profiles
+- **Feedback Agent**: Tracks user feedback and updates profiles
+
+### Tools
+
+Each agent has access to specialized tools:
+
+- **StateTransitionTool**: Manages transitions between conversation states
+- **ProfileSaveTool**: Saves and retrieves user profiles
+- **SchedulerTool**: Schedules daily habit prompts
+- **PromptGeneratorTool**: Generates personalized habit prompts
+
+## Installation
+
+This project uses `uv` for package management:
+
+```bash
+# Install dependencies
+uv sync
+
+# Install with dev dependencies
+uv sync --extra dev
+```
+
+## Configuration
+
+Create a `.env` file:
+
+```bash
+OPENAI_API_KEY=your_openai_api_key
+OPENAI_MODEL=gpt-4o-mini
+OPENAI_TEMPERATURE=0.1
+
+# Path to Go application state directory
+PROMPTPIPE_STATE_DIR=/var/lib/promptpipe
+
+# Prompt files
+INTAKE_BOT_PROMPT_FILE=../../prompts/intake_bot_system.txt
+COORDINATOR_PROMPT_FILE=../../prompts/conversation_system_3bot.txt
+FEEDBACK_TRACKER_PROMPT_FILE=../../prompts/feedback_tracker_system.txt
+PROMPT_GENERATOR_PROMPT_FILE=../../prompts/prompt_generator_system.txt
+
+# Timeouts
+FEEDBACK_INITIAL_TIMEOUT=15m
+FEEDBACK_FOLLOWUP_DELAY=3h
+
+# API Configuration
+API_HOST=0.0.0.0
+API_PORT=8001
+```
+
+## Running
+
+```bash
+# Development mode
+uv run uvicorn promptpipe_agent.api.main:app --reload --port 8001
+
+# Production mode
+uv run uvicorn promptpipe_agent.api.main:app --host 0.0.0.0 --port 8001
+```
+
+## Testing
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=promptpipe_agent --cov-report=html
+
+# Run specific test file
+uv run pytest tests/unit/test_coordinator_agent.py
+```
+
+## Development
+
+```bash
+# Format code
+uv run black promptpipe_agent tests
+
+# Lint
+uv run ruff check promptpipe_agent tests
+
+# Type check
+uv run mypy promptpipe_agent
+```
+
+## API Endpoints
+
+### POST /process-message
+
+Process a user message through the conversation flow.
+
+**Request:**
+```json
+{
+  "participant_id": "part_abc123",
+  "message": "User's message text",
+  "phone_number": "+15551234567"
+}
+```
+
+**Response:**
+```json
+{
+  "response": "Agent's response text",
+  "state": "COORDINATOR",
+  "metadata": {}
+}
+```
+
+### GET /health
+
+Health check endpoint.
+
+## Integration with Go Service
+
+The Go service delegates message processing to this Python service via HTTP:
+
+1. Go receives WhatsApp message
+2. Go calls Python's `/process-message` endpoint
+3. Python processes message through appropriate agent
+4. Python returns response
+5. Go sends response via WhatsApp

python/langchain/promptpipe_agent/__init__.py

@@ -0,0 +1,68 @@
+"""Configuration management for PromptPipe Agent."""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # OpenAI Configuration
+    openai_api_key: str = Field(..., description="OpenAI API key")
+    openai_model: str = Field(default="gpt-4o-mini", description="OpenAI model to use")
+    openai_temperature: float = Field(default=0.1, description="OpenAI temperature")
+
+    # State Directory
+    promptpipe_state_dir: str = Field(
+        default="/var/lib/promptpipe", description="PromptPipe state directory"
+    )
+
+    # Prompt Files (relative to project root or absolute paths)
+    intake_bot_prompt_file: str = Field(
+        default="../../prompts/intake_bot_system.txt",
+        description="Path to intake bot system prompt",
+    )
+    coordinator_prompt_file: str = Field(
+        default="../../prompts/conversation_system_3bot.txt",
+        description="Path to coordinator system prompt",
+    )
+    feedback_tracker_prompt_file: str = Field(
+        default="../../prompts/feedback_tracker_system.txt",
+        description="Path to feedback tracker system prompt",
+    )
+    prompt_generator_prompt_file: str = Field(
+        default="../../prompts/prompt_generator_system.txt",
+        description="Path to prompt generator system prompt",
+    )
+
+    # Timeouts
+    feedback_initial_timeout: str = Field(
+        default="15m", description="Initial feedback timeout (e.g., 15m)"
+    )
+    feedback_followup_delay: str = Field(
+        default="3h", description="Follow-up feedback delay (e.g., 3h)"
+    )
+
+    # Chat History
+    chat_history_limit: int = Field(
+        default=-1,
+        description="Limit for chat history (-1: unlimited, 0: none, N: last N messages)",
+    )
+
+    # API Configuration
+    api_host: str = Field(default="0.0.0.0", description="API host")
+    api_port: int = Field(default=8001, description="API port")
+
+    # Debug Mode
+    debug: bool = Field(default=False, description="Enable debug mode")
+
+
+# Global settings instance
+settings = Settings()

python/langchain/promptpipe_agent/agents/__init__.py

@@ -0,0 +1,89 @@
+"""Data models for PromptPipe Agent."""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ConversationState(str, Enum):
+    """Conversation flow states."""
+
+    COORDINATOR = "COORDINATOR"
+    INTAKE = "INTAKE"
+    FEEDBACK = "FEEDBACK"
+    CONVERSATION_ACTIVE = "CONVERSATION_ACTIVE"
+
+
+class MessageRole(str, Enum):
+    """Message roles in conversation."""
+
+    USER = "user"
+    ASSISTANT = "assistant"
+    SYSTEM = "system"
+
+
+class ConversationMessage(BaseModel):
+    """A single message in the conversation history."""
+
+    role: MessageRole
+    content: str
+    timestamp: datetime = Field(default_factory=datetime.now)
+
+
+class ConversationHistory(BaseModel):
+    """Full conversation history for a participant."""
+
+    messages: list[ConversationMessage] = Field(default_factory=list)
+
+
+class UserProfile(BaseModel):
+    """User profile containing personalization data."""
+
+    participant_id: str
+    habit_domain: Optional[str] = None
+    prompt_anchor: Optional[str] = None
+    motivational_frame: Optional[str] = None
+    preferred_time: Optional[str] = None
+    other_personalization: Optional[str] = None
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)
+
+    def to_context_string(self) -> str:
+        """Convert profile to a context string for LLM."""
+        parts = []
+        if self.habit_domain:
+            parts.append(f"Habit Domain: {self.habit_domain}")
+        if self.prompt_anchor:
+            parts.append(f"Prompt Anchor: {self.prompt_anchor}")
+        if self.motivational_frame:
+            parts.append(f"Motivational Frame: {self.motivational_frame}")
+        if self.preferred_time:
+            parts.append(f"Preferred Time: {self.preferred_time}")
+        if self.other_personalization:
+            parts.append(f"Other Personalization: {self.other_personalization}")
+        return "\n".join(parts) if parts else "No profile data available."
+
+
+class ProcessMessageRequest(BaseModel):
+    """Request to process a user message."""
+
+    participant_id: str
+    message: str
+    phone_number: str
+
+
+class ProcessMessageResponse(BaseModel):
+    """Response from processing a user message."""
+
+    response: str
+    state: ConversationState
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class HealthResponse(BaseModel):
+    """Health check response."""
+
+    status: str
+    version: str = "0.1.0"