raise-cli 2.2.1__py3-none-any.whl

raise_cli/memory/migration.py

@@ -0,0 +1,241 @@
+"""Migration module for multi-developer memory architecture.
+
+Migrates session, telemetry, and calibration data from project directory
+to personal directory for proper data separation.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class MigrationResult:
+    """Result of a migration operation.
+
+    Attributes:
+        success: Whether migration completed without errors.
+        sessions_migrated: Number of session entries migrated.
+        telemetry_migrated: Number of telemetry entries migrated.
+        calibration_migrated: Number of calibration entries migrated.
+        message: Status message describing the migration.
+        dry_run: Whether this was a dry run (no actual changes).
+    """
+
+    success: bool
+    sessions_migrated: int = 0
+    telemetry_migrated: int = 0
+    calibration_migrated: int = 0
+    message: str = ""
+    dry_run: bool = False
+    skipped_items: list[str] = field(default_factory=lambda: [])
+
+    def summary(self) -> str:
+        """Generate human-readable summary of migration."""
+        prefix = "Would migrate" if self.dry_run else "Migrated"
+
+        parts: list[str] = []
+        if self.sessions_migrated > 0:
+            parts.append(f"{self.sessions_migrated} sessions")
+        if self.telemetry_migrated > 0:
+            parts.append(f"{self.telemetry_migrated} telemetry")
+        if self.calibration_migrated > 0:
+            parts.append(f"{self.calibration_migrated} calibration")
+
+        if not parts:
+            return "Nothing to migrate"
+
+        summary = f"{prefix}: {', '.join(parts)}"
+        if self.dry_run:
+            summary += " (dry run)"
+        return summary
+
+
+def _count_jsonl_entries(file_path: Path) -> int:
+    """Count the number of valid JSON entries in a JSONL file."""
+    if not file_path.exists():
+        return 0
+
+    count = 0
+    with file_path.open("r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    json.loads(line)
+                    count += 1
+                except json.JSONDecodeError:
+                    pass
+    return count
+
+
+def _has_content(file_path: Path) -> bool:
+    """Check if a JSONL file has any valid entries."""
+    return _count_jsonl_entries(file_path) > 0
+
+
+def needs_migration(
+    memory_dir: Path,
+    personal_dir: Path | None = None,
+    rai_dir: Path | None = None,
+) -> bool:
+    """Check if migration from project to personal is needed.
+
+    Migration is needed when:
+    - Project has sessions in memory/sessions/ AND personal doesn't have sessions
+    - Project has telemetry in rai/telemetry/ AND personal doesn't have telemetry
+    - Project has calibration in memory/calibration.jsonl AND personal doesn't
+
+    Args:
+        memory_dir: Path to .raise/rai/memory/ directory.
+        personal_dir: Path to .raise/rai/personal/ directory.
+            If None, derived from memory_dir.
+        rai_dir: Path to .raise/rai/ directory (for telemetry).
+            If None, derived from memory_dir.
+
+    Returns:
+        True if migration is needed, False otherwise.
+    """
+    if personal_dir is None:
+        personal_dir = memory_dir.parent / "personal"
+
+    if rai_dir is None:
+        rai_dir = memory_dir.parent
+
+    # Check for sessions
+    project_sessions = memory_dir / "sessions" / "index.jsonl"
+    personal_sessions = personal_dir / "sessions" / "index.jsonl"
+    if _has_content(project_sessions) and not _has_content(personal_sessions):
+        return True
+
+    # Check for telemetry
+    project_telemetry = rai_dir / "telemetry" / "signals.jsonl"
+    personal_telemetry = personal_dir / "telemetry" / "signals.jsonl"
+    if _has_content(project_telemetry) and not _has_content(personal_telemetry):
+        return True
+
+    # Check for calibration
+    project_calibration = memory_dir / "calibration.jsonl"
+    personal_calibration = personal_dir / "calibration.jsonl"
+    return _has_content(project_calibration) and not _has_content(personal_calibration)
+
+
+def _migrate_file(
+    source: Path,
+    dest: Path,
+    dry_run: bool = False,
+) -> int:
+    """Migrate a single file from source to destination.
+
+    Args:
+        source: Source file path.
+        dest: Destination file path.
+        dry_run: If True, don't actually move files.
+
+    Returns:
+        Number of entries migrated.
+    """
+    if not source.exists():
+        return 0
+
+    count = _count_jsonl_entries(source)
+    if count == 0:
+        return 0
+
+    if dry_run:
+        return count
+
+    # Create destination directory
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    # Copy file to destination
+    shutil.copy2(source, dest)
+
+    # Rename source to backup
+    backup_path = source.with_suffix(source.suffix + ".backup")
+    source.rename(backup_path)
+
+    return count
+
+
+def migrate_to_personal(
+    memory_dir: Path,
+    personal_dir: Path,
+    rai_dir: Path | None = None,
+    dry_run: bool = False,
+) -> MigrationResult:
+    """Migrate session, telemetry, and calibration data to personal directory.
+
+    Copies data from project locations to personal directory, then renames
+    originals to .backup files. Does not overwrite existing personal data.
+
+    Args:
+        memory_dir: Path to .raise/rai/memory/ directory.
+        personal_dir: Path to .raise/rai/personal/ directory.
+        rai_dir: Path to .raise/rai/ directory (for telemetry).
+            If None, derived from memory_dir.
+        dry_run: If True, report what would be migrated without making changes.
+
+    Returns:
+        MigrationResult with counts and status.
+    """
+    if rai_dir is None:
+        rai_dir = memory_dir.parent
+
+    result = MigrationResult(success=True, dry_run=dry_run)
+    skipped: list[str] = []
+
+    # Migrate sessions
+    project_sessions = memory_dir / "sessions" / "index.jsonl"
+    personal_sessions = personal_dir / "sessions" / "index.jsonl"
+    if _has_content(personal_sessions):
+        if _has_content(project_sessions):
+            skipped.append("sessions (personal already exists)")
+    else:
+        result.sessions_migrated = _migrate_file(
+            project_sessions, personal_sessions, dry_run
+        )
+
+    # Migrate telemetry
+    project_telemetry = rai_dir / "telemetry" / "signals.jsonl"
+    personal_telemetry = personal_dir / "telemetry" / "signals.jsonl"
+    if _has_content(personal_telemetry):
+        if _has_content(project_telemetry):
+            skipped.append("telemetry (personal already exists)")
+    else:
+        result.telemetry_migrated = _migrate_file(
+            project_telemetry, personal_telemetry, dry_run
+        )
+
+    # Migrate calibration
+    project_calibration = memory_dir / "calibration.jsonl"
+    personal_calibration = personal_dir / "calibration.jsonl"
+    if _has_content(personal_calibration):
+        if _has_content(project_calibration):
+            skipped.append("calibration (personal already exists)")
+    else:
+        result.calibration_migrated = _migrate_file(
+            project_calibration, personal_calibration, dry_run
+        )
+
+    # Build message
+    total = (
+        result.sessions_migrated
+        + result.telemetry_migrated
+        + result.calibration_migrated
+    )
+
+    if total == 0 and not skipped:
+        result.message = "Nothing to migrate"
+    elif total == 0 and skipped:
+        result.message = f"Skipped: {', '.join(skipped)}"
+    else:
+        result.message = result.summary()
+        if skipped:
+            result.message += f" (skipped: {', '.join(skipped)})"
+
+    result.skipped_items = skipped
+    return result

raise_cli/memory/models.py

@@ -0,0 +1,169 @@
+"""Pydantic models for memory concepts.
+
+This module defines the core data structures for representing Rai's
+memories loaded from JSONL files.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class MemoryScope(StrEnum):
+    """Scope/tier for memory data.
+
+    Determines where memory data is stored and its visibility:
+    - GLOBAL: ~/.rai/ - Cross-repo, universal patterns
+    - PROJECT: .raise/rai/memory/ - Shared, committed to repo
+    - PERSONAL: .raise/rai/personal/ - Developer-specific, gitignored
+
+    Precedence for same-ID concepts: PERSONAL > PROJECT > GLOBAL
+    """
+
+    GLOBAL = "global"
+    PROJECT = "project"
+    PERSONAL = "personal"
+
+    def __str__(self) -> str:
+        """Return value for string interpolation."""
+        return self.value
+
+
+class MemoryConceptType(StrEnum):
+    """Types of memory concepts.
+
+    Attributes:
+        PATTERN: Learned patterns (from patterns.jsonl).
+        CALIBRATION: Velocity/estimation data (from calibration.jsonl).
+        SESSION: Session records (from sessions/index.jsonl).
+    """
+
+    PATTERN = "pattern"
+    CALIBRATION = "calibration"
+    SESSION = "session"
+
+
+class PatternSubType(StrEnum):
+    """Sub-types for pattern concepts.
+
+    Attributes:
+        CODEBASE: Code-level patterns.
+        PROCESS: Process/workflow patterns.
+        ARCHITECTURE: Architectural patterns.
+        TECHNICAL: Technical discoveries.
+    """
+
+    CODEBASE = "codebase"
+    PROCESS = "process"
+    ARCHITECTURE = "architecture"
+    TECHNICAL = "technical"
+
+
+class MemoryRelationshipType(StrEnum):
+    """Types of relationships between memory concepts.
+
+    Attributes:
+        LEARNED_FROM: Pattern/calibration was learned from a session.
+        RELATED_TO: Concepts share context keywords.
+        VALIDATES: Calibration data validates a pattern.
+        APPLIES_TO: Pattern applies to a context domain.
+    """
+
+    LEARNED_FROM = "learned_from"
+    RELATED_TO = "related_to"
+    VALIDATES = "validates"
+    APPLIES_TO = "applies_to"
+
+
+class MemoryConcept(BaseModel):
+    """A memory concept extracted from JSONL files.
+
+    Represents a single unit of Rai's memory (pattern, calibration record,
+    or session record) with its metadata.
+
+    Attributes:
+        id: Unique identifier (e.g., 'PAT-001', 'CAL-001', 'SES-001').
+        type: Type of memory concept.
+        content: Main content or summary.
+        context: Context keywords for retrieval.
+        created: Date when memory was created.
+        metadata: Type-specific metadata.
+
+    Examples:
+        >>> concept = MemoryConcept(
+        ...     id="PAT-001",
+        ...     type=MemoryConceptType.PATTERN,
+        ...     content="Singleton with get/set/configure",
+        ...     context=["testing", "module-design"],
+        ...     created=date(2026, 1, 31),
+        ...     metadata={"sub_type": "codebase", "learned_from": "F1.4"}
+        ... )
+        >>> concept.id
+        'PAT-001'
+    """
+
+    id: str = Field(..., description="Unique identifier (e.g., 'PAT-001')")
+    type: MemoryConceptType = Field(..., description="Memory concept type")
+    content: str = Field(..., description="Main content or summary")
+    context: list[str] = Field(default_factory=list, description="Context keywords")
+    created: date = Field(..., description="Date when memory was created")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Type-specific metadata"
+    )
+
+    @property
+    def token_estimate(self) -> int:
+        """Estimate tokens for this concept.
+
+        Returns:
+            Estimated token count (content length // 4).
+        """
+        return len(self.content) // 4
+
+
+class MemoryRelationship(BaseModel):
+    """A relationship between two memory concepts.
+
+    Attributes:
+        source: Source concept ID.
+        target: Target concept ID.
+        type: Relationship type.
+        metadata: Additional relationship metadata.
+
+    Examples:
+        >>> rel = MemoryRelationship(
+        ...     source="PAT-001",
+        ...     target="SES-001",
+        ...     type=MemoryRelationshipType.LEARNED_FROM,
+        ...     metadata={"confidence": 1.0}
+        ... )
+        >>> rel.type
+        <MemoryRelationshipType.LEARNED_FROM: 'learned_from'>
+    """
+
+    source: str = Field(..., description="Source concept ID")
+    target: str = Field(..., description="Target concept ID")
+    type: MemoryRelationshipType = Field(..., description="Relationship type")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Additional metadata"
+    )
+
+
+class MemoryLoadResult(BaseModel):
+    """Result of loading memory from JSONL files.
+
+    Attributes:
+        concepts: List of loaded memory concepts.
+        total: Total number of concepts loaded.
+        files_processed: Number of files successfully processed.
+        errors: List of error messages.
+    """
+
+    concepts: list[MemoryConcept] = Field(default_factory=lambda: list[MemoryConcept]())
+    total: int = Field(default=0, description="Total concepts loaded")
+    files_processed: int = Field(default=0, description="Files processed")
+    errors: list[str] = Field(default_factory=lambda: list[str]())