gobby 0.2.5__py3-none-any.whl

gobby/config/persistence.py

@@ -0,0 +1,247 @@
+"""
+Persistence configuration module.
+
+Contains storage and sync-related Pydantic config models:
+- MemoryConfig: Memory system settings (injection, decay, search)
+- MemorySyncConfig: Memory file sync settings (debounce, export path)
+
+Extracted from app.py using Strangler Fig pattern for code decomposition.
+"""
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field, field_validator
+
+__all__ = [
+    "MemoryConfig",
+    "MemorySyncConfig",
+    "Mem0Config",
+    "MemUConfig",
+    "OpenMemoryConfig",
+]
+
+
+class Mem0Config(BaseModel):
+    """Mem0 backend configuration.
+
+    Configure this section when using backend: 'mem0' for cloud-based
+    semantic memory storage via the Mem0 AI service (mem0ai package).
+
+    Requires: pip install mem0ai
+    """
+
+    api_key: str | None = Field(
+        default=None,
+        description="Mem0 API key for authentication (required when backend='mem0')",
+    )
+    user_id: str | None = Field(
+        default=None,
+        description="Default user ID for memories (optional, defaults to 'default')",
+    )
+    org_id: str | None = Field(
+        default=None,
+        description="Organization ID for multi-tenant use (optional)",
+    )
+
+
+class MemUConfig(BaseModel):
+    """MemU backend configuration.
+
+    Configure this section when using backend: 'memu' for structured
+    memory storage via the MemU SDK (NevaMind-AI/memU via memu-py).
+
+    Requires: pip install memu-py
+    """
+
+    database_type: str = Field(
+        default="inmemory",
+        description="Database type: 'inmemory', 'sqlite', or 'postgres'",
+    )
+    database_url: str | None = Field(
+        default=None,
+        description="Database connection URL (for sqlite/postgres)",
+    )
+    llm_api_key: str | None = Field(
+        default=None,
+        description="LLM API key for embeddings (optional, uses OpenAI by default)",
+    )
+    llm_base_url: str | None = Field(
+        default=None,
+        description="LLM API base URL (optional)",
+    )
+    user_id: str | None = Field(
+        default=None,
+        description="Default user ID for memories (optional)",
+    )
+
+
+class OpenMemoryConfig(BaseModel):
+    """OpenMemory backend configuration.
+
+    Configure this section when using backend: 'openmemory' for self-hosted
+    embedding-based memory storage via the OpenMemory REST API.
+
+    OpenMemory provides semantic search over memories using local embeddings.
+    """
+
+    base_url: str = Field(
+        default="http://localhost:8080",
+        description="OpenMemory server base URL (required when backend='openmemory')",
+    )
+    api_key: str | None = Field(
+        default=None,
+        description="Optional API key for authentication",
+    )
+    user_id: str | None = Field(
+        default=None,
+        description="Default user ID for memories (optional, defaults to 'default')",
+    )
+
+    @field_validator("base_url")
+    @classmethod
+    def validate_url(cls, v: str) -> str:
+        """Validate base_url is a valid URL format."""
+        if not v.startswith(("http://", "https://")):
+            raise ValueError("base_url must start with http:// or https://")
+        # Remove trailing slash for consistency
+        return v.rstrip("/")
+
+
+class MemoryConfig(BaseModel):
+    """Memory system configuration."""
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable persistent memory system",
+    )
+    backend: str = Field(
+        default="sqlite",
+        description=(
+            "Storage backend for memories. Options: "
+            "'sqlite' (default, local SQLite database), "
+            "'mem0' (Mem0 cloud-based semantic memory via mem0ai), "
+            "'memu' (MemU structured memory via memu-py), "
+            "'openmemory' (self-hosted OpenMemory REST API), "
+            "'null' (no persistence, for testing)"
+        ),
+    )
+    mem0: Mem0Config = Field(
+        default_factory=Mem0Config,
+        description="Mem0 backend configuration (only used when backend='mem0')",
+    )
+    memu: MemUConfig = Field(
+        default_factory=MemUConfig,
+        description="MemU backend configuration (only used when backend='memu')",
+    )
+    openmemory: OpenMemoryConfig = Field(
+        default_factory=OpenMemoryConfig,
+        description="OpenMemory backend configuration (only used when backend='openmemory')",
+    )
+    importance_threshold: float = Field(
+        default=0.7,
+        description="Minimum importance score for memory injection",
+    )
+    decay_enabled: bool = Field(
+        default=True,
+        description="Enable memory importance decay over time",
+    )
+    decay_rate: float = Field(
+        default=0.05,
+        description="Importance decay rate per month",
+    )
+    decay_floor: float = Field(
+        default=0.1,
+        description="Minimum importance score after decay",
+    )
+    search_backend: str = Field(
+        default="tfidf",
+        description=(
+            "Search backend for memory recall. Options: "
+            "'tfidf' (default, zero-dependency local search), "
+            "'text' (simple substring matching)"
+        ),
+    )
+    auto_crossref: bool = Field(
+        default=False,
+        description="Automatically create cross-references between similar memories",
+    )
+    crossref_threshold: float = Field(
+        default=0.3,
+        description="Minimum similarity score to create a cross-reference (0.0-1.0)",
+    )
+    crossref_max_links: int = Field(
+        default=5,
+        description="Maximum number of cross-references to create per memory",
+    )
+    access_debounce_seconds: int = Field(
+        default=60,
+        description="Minimum seconds between access stat updates for the same memory",
+    )
+
+    @field_validator("importance_threshold", "decay_rate", "decay_floor", "crossref_threshold")
+    @classmethod
+    def validate_probability(cls, v: float) -> float:
+        """Validate value is between 0.0 and 1.0."""
+        if not (0.0 <= v <= 1.0):
+            raise ValueError("Value must be between 0.0 and 1.0")
+        return v
+
+    @field_validator("crossref_max_links")
+    @classmethod
+    def validate_positive_links(cls, v: int) -> int:
+        """Validate crossref_max_links is positive."""
+        if v < 1:
+            raise ValueError("crossref_max_links must be at least 1")
+        return v
+
+    @field_validator("search_backend")
+    @classmethod
+    def validate_search_backend(cls, v: str) -> str:
+        """Validate search_backend is a supported option."""
+        valid_backends = {"tfidf", "text"}
+        if v not in valid_backends:
+            raise ValueError(
+                f"Invalid search_backend '{v}'. Must be one of: {sorted(valid_backends)}"
+            )
+        return v
+
+    @field_validator("backend")
+    @classmethod
+    def validate_backend(cls, v: str) -> str:
+        """Validate backend is a supported storage option."""
+        valid_backends = {"sqlite", "mem0", "memu", "openmemory", "null"}
+        if v not in valid_backends:
+            raise ValueError(f"Invalid backend '{v}'. Must be one of: {sorted(valid_backends)}")
+        return v
+
+
+class MemorySyncConfig(BaseModel):
+    """Memory backup configuration (filesystem export).
+
+    Note: This was previously named for "sync" but is actually a backup mechanism.
+    Memories are stored in the database via MemoryBackendProtocol; this config
+    controls the JSONL backup file export (for disaster recovery/migration).
+
+    TODO: Consider renaming to MemoryBackupConfig in a future breaking change.
+    """
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable memory synchronization to filesystem",
+    )
+    export_debounce: float = Field(
+        default=5.0,
+        description="Seconds to wait before exporting after a change",
+    )
+    export_path: Path = Field(
+        default=Path(".gobby/memories.jsonl"),
+        description="Path to the memories export file (relative to project root or absolute)",
+    )
+
+    @field_validator("export_debounce")
+    @classmethod
+    def validate_positive(cls, v: float) -> float:
+        """Validate value is non-negative."""
+        if v < 0:
+            raise ValueError("Value must be non-negative")
+        return v

gobby/config/servers.py

@@ -0,0 +1,141 @@
+"""
+Server configuration module.
+
+Contains server and networking Pydantic config models:
+- WebSocketSettings: WebSocket server settings (port, ping interval)
+- MCPClientProxyConfig: MCP proxy settings (timeouts, embeddings, search mode)
+
+Extracted from app.py using Strangler Fig pattern for code decomposition.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+__all__ = ["WebSocketSettings", "MCPClientProxyConfig"]
+
+
+class WebSocketSettings(BaseModel):
+    """WebSocket server configuration."""
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable WebSocket server for real-time communication",
+    )
+    port: int = Field(
+        default=8766,
+        description="Port for WebSocket server to listen on",
+    )
+    ping_interval: int = Field(
+        default=30,
+        description="Ping interval in seconds for keepalive",
+    )
+    ping_timeout: int = Field(
+        default=10,
+        description="Pong timeout in seconds before considering connection dead",
+    )
+
+    @field_validator("port")
+    @classmethod
+    def validate_port(cls, v: int) -> int:
+        """Validate port number is in valid range."""
+        if not (1024 <= v <= 65535):
+            raise ValueError("Port must be between 1024 and 65535")
+        return v
+
+    @field_validator("ping_interval", "ping_timeout")
+    @classmethod
+    def validate_positive(cls, v: int) -> int:
+        """Validate value is positive."""
+        if v <= 0:
+            raise ValueError("Value must be positive")
+        return v
+
+
+class MCPClientProxyConfig(BaseModel):
+    """MCP client proxy configuration for downstream MCP servers."""
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable MCP client proxy for downstream MCP servers",
+    )
+    connect_timeout: float = Field(
+        default=30.0,
+        description="Timeout in seconds for establishing connections to MCP servers",
+    )
+    proxy_timeout: int = Field(
+        default=30,
+        description="Timeout in seconds for proxy calls to downstream MCP servers",
+    )
+    tool_timeout: int = Field(
+        default=30,
+        description="Timeout in seconds for tool schema operations",
+    )
+    tool_timeouts: dict[str, float] = Field(
+        default_factory=dict,
+        description="Map of tool names to specific timeouts in seconds",
+    )
+
+    # Semantic search and embeddings
+    search_mode: Literal["llm", "semantic", "hybrid"] = Field(
+        default="llm",
+        description="Default search mode for tool recommendations: 'llm' (LLM-based), 'semantic' (embedding similarity), 'hybrid' (both)",
+    )
+    embedding_provider: str = Field(
+        default="openai",
+        description="Provider for embedding generation (openai, litellm)",
+    )
+    embedding_model: str = Field(
+        default="text-embedding-3-small",
+        description="Model to use for tool embedding generation",
+    )
+    min_similarity: float = Field(
+        default=0.3,
+        description="Minimum similarity threshold for semantic search results (0.0-1.0)",
+    )
+    top_k: int = Field(
+        default=10,
+        description="Default number of results to return for semantic search",
+    )
+
+    # Refresh settings
+    refresh_on_server_add: bool = Field(
+        default=True,
+        description="Automatically refresh tool embeddings when adding a new MCP server",
+    )
+    refresh_timeout: float = Field(
+        default=300.0,
+        description="Timeout in seconds for tool refresh operations (embedding generation)",
+    )
+
+    @field_validator("connect_timeout", "refresh_timeout")
+    @classmethod
+    def validate_connect_timeout(cls, v: float) -> float:
+        """Validate timeout is positive."""
+        if v <= 0:
+            raise ValueError("Timeout must be positive")
+        return v
+
+    @field_validator("proxy_timeout", "tool_timeout")
+    @classmethod
+    def validate_timeout(cls, v: int) -> int:
+        """Validate timeout is positive."""
+        if v <= 0:
+            raise ValueError("Timeout must be positive")
+        return v
+
+    @field_validator("min_similarity")
+    @classmethod
+    def validate_min_similarity(cls, v: float) -> float:
+        """Validate min_similarity is between 0 and 1."""
+        if not 0.0 <= v <= 1.0:
+            raise ValueError("min_similarity must be between 0.0 and 1.0")
+        return v
+
+    @field_validator("top_k")
+    @classmethod
+    def validate_top_k(cls, v: int) -> int:
+        """Validate top_k is positive."""
+        if v <= 0:
+            raise ValueError("top_k must be positive")
+        return v

gobby/config/sessions.py

@@ -0,0 +1,250 @@
+"""
+Session configuration module.
+
+Contains session-related Pydantic config models:
+- ContextInjectionConfig: Subagent context injection settings
+- SessionSummaryConfig: Session summary generation settings
+- TitleSynthesisConfig: Session title synthesis settings
+- MessageTrackingConfig: Session message tracking settings
+- SessionLifecycleConfig: Session lifecycle management settings
+
+Extracted from app.py using Strangler Fig pattern for code decomposition.
+"""
+
+from pydantic import BaseModel, Field, field_validator
+
+__all__ = [
+    "ArtifactHandoffConfig",
+    "ContextInjectionConfig",
+    "SessionSummaryConfig",
+    "TitleSynthesisConfig",
+    "MessageTrackingConfig",
+    "SessionLifecycleConfig",
+]
+
+
+class ArtifactHandoffConfig(BaseModel):
+    """Configuration for artifact inclusion in session handoffs.
+
+    Controls how artifacts are collected and formatted when generating
+    handoff context for session continuation.
+    """
+
+    max_artifacts_in_handoff: int = Field(
+        default=10,
+        description="Maximum number of artifacts to include in handoff context",
+    )
+    max_context_size: int = Field(
+        default=50000,
+        description="Maximum size in characters for handoff context",
+    )
+    include_parent_artifacts: bool = Field(
+        default=True,
+        description="Include artifacts from parent session in handoff",
+    )
+    max_lineage_depth: int = Field(
+        default=3,
+        description="Maximum depth to traverse session lineage for artifacts",
+    )
+
+    @field_validator("max_artifacts_in_handoff", "max_context_size", "max_lineage_depth")
+    @classmethod
+    def validate_positive(cls, v: int) -> int:
+        """Validate value is positive."""
+        if v <= 0:
+            raise ValueError("Value must be positive")
+        return v
+
+
+class ContextInjectionConfig(BaseModel):
+    """Context injection configuration for subagent spawning.
+
+    Controls how context is resolved and injected into subagent prompts.
+    """
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable context injection for subagents",
+    )
+    default_source: str = Field(
+        default="summary_markdown",
+        description="Default context source when not specified. "
+        "Options: summary_markdown, compact_markdown, session_id:<id>, "
+        "transcript:<n>, file:<path>",
+    )
+    max_file_size: int = Field(
+        default=51200,
+        description="Maximum file size in bytes for file: source (default: 50KB)",
+    )
+    max_content_size: int = Field(
+        default=51200,
+        description="Maximum content size in bytes for all sources (default: 50KB)",
+    )
+    max_transcript_messages: int = Field(
+        default=100,
+        description="Maximum number of messages for transcript: source",
+    )
+    truncation_suffix: str = Field(
+        default="\n\n[truncated: {bytes} bytes remaining]",
+        description="Suffix template appended when content is truncated",
+    )
+    context_template: str | None = Field(
+        default=None,
+        description="Custom template for context injection. "
+        "Use {{ context }} and {{ prompt }} placeholders. "
+        "If None, uses the default template.",
+    )
+
+    @field_validator("max_file_size", "max_content_size", "max_transcript_messages")
+    @classmethod
+    def validate_positive(cls, v: int) -> int:
+        """Validate value is positive."""
+        if v <= 0:
+            raise ValueError("Value must be positive")
+        return v
+
+
+class SessionSummaryConfig(BaseModel):
+    """Session summary generation configuration."""
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable LLM-based session summary generation",
+    )
+    provider: str = Field(
+        default="claude",
+        description="LLM provider to use for session summary",
+    )
+    model: str = Field(
+        default="claude-haiku-4-5",
+        description="Model to use for session summary generation",
+    )
+    prompt: str = Field(
+        default="""Generate a concise session summary for handoff to another agent or future session.
+
+## Session Context
+Transcript Summary:
+{transcript_summary}
+
+Git Status:
+{git_status}
+
+File Changes:
+{file_changes}
+
+{todo_list}
+
+{session_tasks}
+
+## Instructions
+Create a summary with these sections:
+1. **What was accomplished** - Key completions in 2-3 bullet points
+2. **Current state** - What's in progress or pending
+3. **Next steps** - Clear actionable items for continuation
+
+Be concise. Focus on what the next agent needs to know to continue effectively.""",
+        description="Prompt template for session summary (use placeholders: {transcript_summary}, {git_status}, {file_changes}, {todo_list}, {session_tasks})",
+    )
+    summary_file_path: str = Field(
+        default="~/.gobby/session_summaries",
+        description="Directory path for session summary markdown files",
+    )
+
+
+class TitleSynthesisConfig(BaseModel):
+    """Title synthesis configuration."""
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable title synthesis for sessions",
+    )
+    provider: str = Field(
+        default="claude",
+        description="LLM provider to use for title synthesis",
+    )
+    model: str = Field(
+        default="claude-haiku-4-5",
+        description="Model to use for title synthesis",
+    )
+    prompt: str | None = Field(
+        default=None,
+        description="Custom prompt template for title synthesis",
+    )
+
+
+class MessageTrackingConfig(BaseModel):
+    """Configuration for session message tracking."""
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable session message tracking",
+    )
+    poll_interval: float = Field(
+        default=5.0,
+        description="Polling interval in seconds for transcript updates",
+    )
+    debounce_delay: float = Field(
+        default=1.0,
+        description="Debounce delay in seconds for message processing",
+    )
+    max_message_length: int = Field(
+        default=10000,
+        description="Maximum length of a single message content",
+    )
+    broadcast_enabled: bool = Field(
+        default=True,
+        description="Enable broadcasting message events",
+    )
+
+    @field_validator("poll_interval", "debounce_delay")
+    @classmethod
+    def validate_positive(cls, v: float) -> float:
+        """Validate value is positive."""
+        if v <= 0:
+            raise ValueError("Value must be positive")
+        return v
+
+
+class SessionLifecycleConfig(BaseModel):
+    """Configuration for session lifecycle management.
+
+    Handles:
+    - Pausing active sessions with no recent activity
+    - Expiring stale sessions (active/paused for too long)
+    - Background transcript processing for expired sessions
+    """
+
+    active_session_pause_minutes: int = Field(
+        default=30,
+        description="Minutes of inactivity before active sessions are marked paused",
+    )
+    stale_session_timeout_hours: int = Field(
+        default=24,
+        description="Hours after which inactive sessions are marked expired",
+    )
+    expire_check_interval_minutes: int = Field(
+        default=60,
+        description="How often to check for stale sessions (minutes)",
+    )
+    transcript_processing_interval_minutes: int = Field(
+        default=5,
+        description="How often to process pending transcripts (minutes)",
+    )
+    transcript_processing_batch_size: int = Field(
+        default=10,
+        description="Maximum sessions to process per batch",
+    )
+
+    @field_validator(
+        "active_session_pause_minutes",
+        "stale_session_timeout_hours",
+        "expire_check_interval_minutes",
+        "transcript_processing_interval_minutes",
+        "transcript_processing_batch_size",
+    )
+    @classmethod
+    def validate_positive(cls, v: int) -> int:
+        """Validate value is positive."""
+        if v <= 0:
+            raise ValueError("Value must be positive")
+        return v