ocerebro 0.1.0

package/src/consolidation/scorer.py

@@ -0,0 +1,191 @@
+"""Scorer RFM para memórias do Cerebro"""
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict
+import math
+
+
+@dataclass
+class ScoringConfig:
+    """Configuração de pesos do scoring RFM"""
+    recency_weight: float = 0.3
+    frequency_weight: float = 0.2
+    importance_weight: float = 0.3
+    links_weight: float = 0.2
+
+
+class Scorer:
+    """
+    Calcula scores RFM (Recency, Frequency, Importance) para memórias.
+
+    O score total é uma combinação ponderada de:
+    - Recência: quão recente foi o último acesso
+    - Frequência: quantas vezes foi acessada
+    - Importância: baseada em severity/impact
+    - Links: quantas conexões com outras memórias
+    """
+
+    def __init__(self, config: ScoringConfig):
+        """
+        Inicializa o Scorer.
+
+        Args:
+            config: Configuração de pesos
+        """
+        self.config = config
+
+    def calculate(self, memory: Dict[str, Any]) -> float:
+        """
+        Calcula score total RFM.
+
+        Args:
+            memory: Dados da memória
+
+        Returns:
+            Score entre 0.0 e 1.0
+        """
+        r = self._recency_score(memory.get("last_accessed"))
+        f = self._frequency_score(memory.get("access_count", 0))
+        i = self._importance_score(memory)
+        l = self._links_score(memory.get("related_to", []))
+
+        total = (
+            self.config.recency_weight * r +
+            self.config.frequency_weight * f +
+            self.config.importance_weight * i +
+            self.config.links_weight * l
+        )
+
+        return min(1.0, max(0.0, total))
+
+    def _recency_score(self, last_accessed: datetime) -> float:
+        """
+        Score de recência (0-1).
+
+        Usa decaimento exponencial baseado em dias desde último acesso.
+
+        Args:
+            last_accessed: Data do último acesso
+
+        Returns:
+            Score de recência
+        """
+        if not last_accessed:
+            return 0.0
+
+        # BUG-01 FIX: Usa timezone-aware datetime
+        now = datetime.now(timezone.utc)
+        # Normaliza para timezone-aware se last_accessed for naive (fallback de segurança)
+        if last_accessed.tzinfo is None:
+            last_accessed = last_accessed.replace(tzinfo=timezone.utc)
+        days_ago = (now - last_accessed).days
+        return math.exp(-0.05 * days_ago)
+
+    def _frequency_score(self, access_count: int) -> float:
+        """
+        Score de frequência (0-1).
+
+        Args:
+            access_count: Número de acessos
+
+        Returns:
+            Score de frequência
+        """
+        return 1.0 - math.exp(-0.1 * access_count)
+
+    def _importance_score(self, memory: Dict[str, Any]) -> float:
+        """
+        Score de importância baseado em severity/impact.
+
+        WARN-03 FIX: Considera tanto errors (severity) quanto decisions (status)
+
+        Args:
+            memory: Dados da memória
+
+        Returns:
+            Score de importância
+        """
+        # WARN-03 FIX: Erros usam severity, decisions usam status
+        mem_type = memory.get("type", "")
+
+        if mem_type == "error":
+            severity_map = {"critical": 1.0, "high": 0.8, "medium": 0.5, "low": 0.2}
+            return severity_map.get(memory.get("severity", "low"), 0.2)
+
+        if mem_type == "decision":
+            # Decisões approved têm alta importância
+            status_map = {
+                "approved": 0.8,
+                "superseded": 0.4,
+                "deprecated": 0.1,
+                "draft": 0.3
+            }
+            return status_map.get(memory.get("status", "draft"), 0.3)
+
+        return 0.2
+
+    def _links_score(self, related_to: list) -> float:
+        """
+        Score de links (0-1).
+
+        Args:
+            related_to: Lista de IDs relacionados
+
+        Returns:
+            Score de links
+        """
+        if not related_to:
+            return 0.0
+        return min(1.0, len(related_to) * 0.25)
+
+    def apply_decay(self, score: float, days: int, decay_rate: float) -> float:
+        """
+        Aplica decay temporal ao score.
+
+        Args:
+            score: Score base
+            days: Dias de decaimento
+            decay_rate: Taxa de decaimento
+
+        Returns:
+            Score com decay aplicado
+        """
+        return score * math.exp(-decay_rate * days)
+
+    def calculate_all_scores(self, memory: Dict[str, Any]) -> Dict[str, float]:
+        """
+        Calcula todos os scores individuais e total.
+
+        Args:
+            memory: Dados da memória
+
+        Returns:
+            Dicionário com todos os scores
+        """
+        # BUG-01 FIX: Usa timezone-aware datetime
+        now = datetime.now(timezone.utc)
+        last_accessed = memory.get("last_accessed")
+        # Normaliza se for naive
+        if last_accessed and isinstance(last_accessed, datetime) and last_accessed.tzinfo is None:
+            last_accessed = last_accessed.replace(tzinfo=timezone.utc)
+
+        r = self._recency_score(last_accessed)
+        f = self._frequency_score(memory.get("access_count", 0))
+        i = self._importance_score(memory)
+        l = self._links_score(memory.get("related_to", []))
+
+        total = (
+            self.config.recency_weight * r +
+            self.config.frequency_weight * f +
+            self.config.importance_weight * i +
+            self.config.links_weight * l
+        )
+
+        return {
+            "recency_score": min(1.0, max(0.0, r)),
+            "frequency_score": min(1.0, max(0.0, f)),
+            "importance_score": min(1.0, max(0.0, i)),
+            "links_score": min(1.0, max(0.0, l)),
+            "total_score": min(1.0, max(0.0, total))
+        }

package/src/core/__init__.py

@@ -0,0 +1,6 @@
+"""Core do Cerebro: schema, storage bruto, session manager"""
+from .event_schema import Event, EventType, EventOrigin
+from .jsonl_storage import JSONLStorage
+from .session_manager import SessionManager
+
+__all__ = ["Event", "EventType", "EventOrigin", "JSONLStorage", "SessionManager"]

package/src/core/event_schema.py

@@ -0,0 +1,55 @@
+import uuid
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, Optional
+from pydantic import BaseModel, Field, field_validator
+
+
+class EventType(str, Enum):
+    TOOL_CALL = "tool_call"
+    GIT_EVENT = "git_event"
+    TEST_RESULT = "test_result"
+    ERROR = "error"
+    CHECKPOINT_CREATED = "checkpoint.created"
+    PROMOTION_PERFORMED = "promotion.performed"
+    MEMORY_GC = "memory.gc"
+
+
+class EventOrigin(str, Enum):
+    CLAUDE_CODE = "claude-code"
+    USER = "user"
+    CI = "ci"
+    HOOK = "hook"
+
+
+class Event(BaseModel):
+    """Evento bruto do Cerebro"""
+
+    project: str = Field(..., min_length=1)
+    origin: EventOrigin
+    event_type: EventType
+    subtype: str = Field(default="")
+    payload: Dict[str, Any] = Field(default_factory=dict)
+    tags: list[str] = Field(default_factory=list)
+
+    # Campos gerados automaticamente
+    event_id: str = Field(default_factory=lambda: f"evt_{uuid.uuid4().hex[:8]}")
+    session_id: str = Field(default_factory=lambda: f"sess_{uuid.uuid4().hex[:8]}")
+    ts: str = Field(default_factory=lambda: datetime.utcnow().isoformat() + "Z")
+
+    @field_validator("tags")
+    @classmethod
+    def validate_tags(cls, v):
+        return [tag.lower().replace(" ", "-") for tag in v]
+
+    def to_json_line(self) -> str:
+        """Serializa para JSON line"""
+        import json
+        return self.model_dump_json()
+
+    @classmethod
+    def from_json_line(cls, line: str) -> "Event":
+        """Deserializa de JSON line"""
+        import json
+        data = json.loads(line)
+        return cls(**data)

package/src/core/jsonl_storage.py

@@ -0,0 +1,238 @@
+"""Armazenamento JSONL append-only com rotação mensal"""
+
+import json
+from pathlib import Path
+from typing import List, Optional
+from src.core.event_schema import Event
+
+
+class JSONLStorage:
+    """
+    Armazenamento append-only de eventos em formato JSONL.
+
+    Arquivos são organizados por projeto e mês:
+    raw/{project}/events-YYYY-MM.jsonl
+
+    Rotação automática por mês - cada arquivo contém eventos de um mês específico.
+    """
+
+    def __init__(self, base_dir: Path):
+        """
+        Inicializa o armazenamento JSONL.
+
+        Args:
+            base_dir: Diretório base para a pasta raw/
+        """
+        self.base_dir = Path(base_dir)
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+
+    def _get_project_dir(self, project: str) -> Path:
+        """Retorna diretório do projeto"""
+        return self.base_dir / project
+
+    def _get_current_file(self, project: str) -> Path:
+        """
+        Retorna o arquivo JSONL atual para um projeto.
+
+        O arquivo é nomeado com o mês atual: events-YYYY-MM.jsonl
+
+        WINDOWS FIX: Usa datetime.now(timezone.utc) ao invés de utcnow() deprecated
+        """
+        project_dir = self._get_project_dir(project)
+        project_dir.mkdir(parents=True, exist_ok=True)
+
+        # WINDOWS FIX: datetime.now(timezone.utc) ao invés de datetime.utcnow()
+        from datetime import datetime, timezone
+        month_str = datetime.now(timezone.utc).strftime("%Y-%m")
+        return project_dir / f"events-{month_str}.jsonl"
+
+    def append(self, event: Event) -> None:
+        """
+        Anexa um evento ao arquivo JSONL do projeto.
+
+        Args:
+            event: Evento a ser anexado
+        """
+        jsonl_file = self._get_current_file(event.project)
+
+        with open(jsonl_file, "a", encoding="utf-8") as f:
+            f.write(event.model_dump_json() + "\n")
+
+    def read(self, project: str) -> List[Event]:
+        """
+        Lê todos os eventos de um projeto.
+
+        Args:
+            project: Nome do projeto
+
+        Returns:
+            Lista de eventos ordenados por timestamp
+        """
+        project_dir = self._get_project_dir(project)
+        if not project_dir.exists():
+            return []
+
+        events = []
+        for jsonl_file in sorted(project_dir.glob("events-*.jsonl")):
+            with open(jsonl_file, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if line:
+                        events.append(Event.model_validate_json(line))
+
+        return events
+
+    def read_iter(self, project: str):
+        """
+        Gerador — não carrega tudo em memória.
+
+        PERFORMANCE FIX: Permite iterar sobre eventos sem carregar todos em memória
+
+        Args:
+            project: Nome do projeto
+
+        Yields:
+            Eventos um por um
+        """
+        project_dir = self._get_project_dir(project)
+        if not project_dir.exists():
+            return
+
+        for jsonl_file in sorted(project_dir.glob("events-*.jsonl")):
+            with open(jsonl_file, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if line:
+                        yield Event.model_validate_json(line)
+
+    def read_last_n(self, project: str, n: int = 1000) -> List[Event]:
+        """
+        Lê apenas os N eventos mais recentes.
+
+        PERFORMANCE FIX: Usa deque com maxlen para memória constante O(n)
+
+        Args:
+            project: Nome do projeto
+            n: Número máximo de eventos (padrão: 1000)
+
+        Returns:
+            Lista dos N eventos mais recentes
+        """
+        from collections import deque
+        return list(deque(self.read_iter(project), maxlen=n))
+
+    def read_since(self, project: str, since: str) -> List[Event]:
+        """
+        Lê eventos desde uma data específica.
+
+        WARN-05 FIX: Filtra por data durante a leitura para evitar carregar tudo em memória
+
+        Args:
+            project: Nome do projeto
+            since: Data mínima (ISO format, ex: "2026-03-01T00:00:00Z")
+
+        Returns:
+            Lista de eventos após a data especificada
+        """
+        from datetime import datetime, timezone
+
+        project_dir = self._get_project_dir(project)
+        if not project_dir.exists():
+            return []
+
+        # Parse da data de início
+        try:
+            since_dt = datetime.fromisoformat(since.replace("Z", "+00:00"))
+        except ValueError:
+            # Fallback: lê tudo
+            return self.read(project)
+
+        events = []
+        for jsonl_file in sorted(project_dir.glob("events-*.jsonl")):
+            with open(jsonl_file, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+
+                    try:
+                        event = Event.model_validate_json(line)
+                        # Parse do timestamp do evento
+                        event_ts = event.ts.replace("Z", "+00:00")
+                        event_dt = datetime.fromisoformat(event_ts)
+
+                        if event_dt >= since_dt:
+                            events.append(event)
+                    except Exception:
+                        # Ignora eventos com timestamp inválido
+                        continue
+
+        return events
+
+    def read_range(self, project: str, start_id: str, end_id: str) -> List[Event]:
+        """
+        Lê eventos em um intervalo de IDs.
+
+        HIGH FIX: Valida existência dos IDs antes de filtrar
+
+        Args:
+            project: Nome do projeto
+            start_id: ID inicial (inclusive)
+            end_id: ID final (inclusive)
+
+        Returns:
+            Lista de eventos no intervalo especificado
+
+        Raises:
+            ValueError: Se start_id ou end_id não existirem
+        """
+        if not start_id or not end_id:
+            raise ValueError("start_id e end_id são obrigatórios")
+
+        all_events = self.read(project)
+        ids = {e.event_id for e in all_events}
+
+        if start_id not in ids:
+            raise ValueError(f"start_id não encontrado: {start_id}")
+        if end_id not in ids:
+            raise ValueError(f"end_id não encontrado: {end_id}")
+
+        in_range = False
+        result = []
+
+        for event in all_events:
+            if event.event_id == start_id:
+                in_range = True
+
+            if in_range:
+                result.append(event)
+
+            if event.event_id == end_id:
+                break
+
+        return result
+
+    def get_file_stats(self, project: str) -> dict:
+        """
+        Retorna estatísticas dos arquivos de um projeto.
+
+        Args:
+            project: Nome do projeto
+
+        Returns:
+            Dicionário com estatísticas por arquivo
+        """
+        project_dir = self._get_project_dir(project)
+        if not project_dir.exists():
+            return {}
+
+        stats = {}
+        for jsonl_file in sorted(project_dir.glob("events-*.jsonl")):
+            size_bytes = jsonl_file.stat().st_size
+            line_count = sum(1 for _ in open(jsonl_file, "r", encoding="utf-8"))
+            stats[jsonl_file.name] = {
+                "size_bytes": size_bytes,
+                "event_count": line_count
+            }
+
+        return stats