foodforthought-cli 0.2.8__py3-none-any.whl → 0.3.1__py3-none-any.whl

ate/memory/cloud.py

@@ -0,0 +1,244 @@
+"""
+Cloud client for FoodforThought memory API.
+
+Handles push (upload), pull (download), list, and delete of .mv2 memory files.
+"""
+
+import os
+from dataclasses import dataclass
+from typing import List
+
+import requests
+
+
+# ---------------------------------------------------------------------------
+# Result dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PushResult:
+    id: str
+    name: str
+    project: str
+    size_bytes: int
+    url: str
+    created_at: str
+
+
+@dataclass
+class PullResult:
+    path: str
+    size_bytes: int
+    name: str
+    project: str
+
+
+@dataclass
+class MemoryListItem:
+    id: str
+    name: str
+    project: str
+    size_bytes: int
+    created_at: str
+    updated_at: str
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+class CloudError(Exception):
+    """Base exception for cloud operations."""
+    pass
+
+
+class CloudAuthError(CloudError):
+    """Raised when authentication is missing or invalid."""
+    pass
+
+
+class CloudNotFoundError(CloudError):
+    """Raised when a requested resource is not found (404)."""
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Client
+# ---------------------------------------------------------------------------
+
+class CloudClient:
+    """Client for FoodforThought memory cloud API."""
+
+    def __init__(self, server_url: str = "https://kindly.fyi", token: str = None):
+        self.server_url = server_url.rstrip("/")
+        self.token = token
+
+    # -- public API --------------------------------------------------------
+
+    def push(self, local_path: str, project: str, name: str = None) -> PushResult:
+        """Upload .mv2 file to cloud.
+
+        POST /api/memory/upload (multipart/form-data)
+
+        Args:
+            local_path: Path to the local .mv2 file.
+            project: Project identifier (e.g. "kindly/memories").
+            name: Optional name override; defaults to the file's basename.
+
+        Returns:
+            PushResult with upload details.
+
+        Raises:
+            CloudAuthError: If no token is set.
+            CloudError: On server error.
+        """
+        headers = self._auth_headers()
+        resolved_name = name or os.path.basename(local_path)
+
+        url = f"{self.server_url}/api/memory/upload"
+
+        with open(local_path, "rb") as f:
+            resp = requests.post(
+                url,
+                headers=headers,
+                files={"file": (resolved_name, f)},
+                data={"project": project, "name": resolved_name},
+            )
+
+        if resp.status_code == 401:
+            raise CloudAuthError("Invalid or expired token")
+        if resp.status_code >= 400:
+            raise CloudError(f"Push failed ({resp.status_code}): {resp.text}")
+
+        body = resp.json()
+        return PushResult(
+            id=body["id"],
+            name=body["name"],
+            project=body["project"],
+            size_bytes=body["size_bytes"],
+            url=body["url"],
+            created_at=body["created_at"],
+        )
+
+    def pull(self, project: str, name: str, output_path: str) -> PullResult:
+        """Download .mv2 file from cloud.
+
+        GET /api/memory/{project}/{name}
+
+        Args:
+            project: Project identifier.
+            name: Memory file name.
+            output_path: Local path to write the downloaded file.
+
+        Returns:
+            PullResult with download details.
+
+        Raises:
+            CloudAuthError: If no token is set.
+            CloudNotFoundError: If the file is not found (404).
+            CloudError: On server error.
+        """
+        headers = self._auth_headers()
+        url = f"{self.server_url}/api/memory/{project}/{name}"
+
+        resp = requests.get(url, headers=headers)
+
+        if resp.status_code == 404:
+            raise CloudNotFoundError(f"Not found: {project}/{name}")
+        if resp.status_code == 401:
+            raise CloudAuthError("Invalid or expired token")
+        if resp.status_code >= 400:
+            raise CloudError(f"Pull failed ({resp.status_code}): {resp.text}")
+
+        # Write content to disk
+        parent = os.path.dirname(output_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+
+        with open(output_path, "wb") as f:
+            f.write(resp.content)
+
+        size = len(resp.content)
+        return PullResult(
+            path=output_path,
+            size_bytes=size,
+            name=name,
+            project=project,
+        )
+
+    def list(self, project: str) -> List[MemoryListItem]:
+        """List memory files in a project.
+
+        GET /api/memory/list?project={project}
+
+        Args:
+            project: Project identifier.
+
+        Returns:
+            List of MemoryListItem.
+
+        Raises:
+            CloudAuthError: If no token is set.
+            CloudError: On server error.
+        """
+        headers = self._auth_headers()
+        url = f"{self.server_url}/api/memory/list"
+
+        resp = requests.get(url, headers=headers, params={"project": project})
+
+        if resp.status_code == 401:
+            raise CloudAuthError("Invalid or expired token")
+        if resp.status_code >= 400:
+            raise CloudError(f"List failed ({resp.status_code}): {resp.text}")
+
+        body = resp.json()
+        return [
+            MemoryListItem(
+                id=item["id"],
+                name=item["name"],
+                project=item["project"],
+                size_bytes=item["size_bytes"],
+                created_at=item["created_at"],
+                updated_at=item["updated_at"],
+            )
+            for item in body.get("items", [])
+        ]
+
+    def delete(self, project: str, name: str) -> bool:
+        """Delete a memory file from cloud.
+
+        DELETE /api/memory/{project}/{name}
+
+        Args:
+            project: Project identifier.
+            name: Memory file name.
+
+        Returns:
+            True on success.
+
+        Raises:
+            CloudAuthError: If no token is set.
+            CloudNotFoundError: If the file is not found (404).
+            CloudError: On server error.
+        """
+        headers = self._auth_headers()
+        url = f"{self.server_url}/api/memory/{project}/{name}"
+
+        resp = requests.delete(url, headers=headers)
+
+        if resp.status_code == 404:
+            raise CloudNotFoundError(f"Not found: {project}/{name}")
+        if resp.status_code == 401:
+            raise CloudAuthError("Invalid or expired token")
+        if resp.status_code >= 400:
+            raise CloudError(f"Delete failed ({resp.status_code}): {resp.text}")
+
+        return True
+
+    # -- internal ----------------------------------------------------------
+
+    def _auth_headers(self) -> dict:
+        """Build authorization headers."""
+        if not self.token:
+            raise CloudAuthError("Not authenticated. Run: ate device-login")
+        return {"Authorization": f"Bearer {self.token}"}

ate/memory/context.py

@@ -0,0 +1,269 @@
+"""Context management for git-like memory operations.
+
+This module provides the ContextManager that tracks the active memory and train 
+of thought, similar to how git tracks the current repository and branch.
+"""
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Dict, Any
+
+from .store import MemoryStore
+
+
+@dataclass
+class MemoryContext:
+    """Tracks active memory and train of thought."""
+    active_memory: str
+    active_train: str
+    path: str
+
+
+@dataclass
+class MemoryMetadata:
+    """Metadata for a memory."""
+    name: str
+    visibility: str
+    trains: List[str]
+    default_train: str
+    description: str = ""
+    created_at: Optional[str] = None
+    remote: Optional[str] = None
+
+
+class ContextManager:
+    """Manages the active memory context (~/.ate/context.json)."""
+
+    CONFIG_DIR = os.path.expanduser("~/.ate")
+    CONTEXT_FILE = os.path.expanduser("~/.ate/context.json")
+    MEMORIES_DIR = os.path.expanduser("~/.ate/memories")
+
+    @classmethod
+    def get_context(cls) -> MemoryContext:
+        """Get current context. Auto-initializes on first use."""
+        if os.path.exists(cls.CONTEXT_FILE):
+            try:
+                with open(cls.CONTEXT_FILE, 'r') as f:
+                    data = json.load(f)
+                
+                # Provide defaults for missing fields
+                active_memory = data.get("active_memory", "default")
+                active_train = data.get("active_train", "main")
+                path = data.get("path")
+                
+                if not path:
+                    path = cls._train_to_path(active_memory, active_train)
+                
+                return MemoryContext(
+                    active_memory=active_memory,
+                    active_train=active_train,
+                    path=path
+                )
+            except (json.JSONDecodeError, KeyError):
+                pass  # Fall through to auto-init
+        
+        # Auto-initialize on first use
+        return cls._auto_initialize()
+
+    @classmethod
+    def set_context(cls, memory: str, train: str) -> MemoryContext:
+        """Set active context."""
+        # Validate memory name
+        if not cls._is_valid_memory_name(memory):
+            raise ValueError(f"Invalid memory name '{memory}'. Use lowercase alphanumeric and hyphens only.")
+        
+        # Ensure directories exist
+        os.makedirs(cls.CONFIG_DIR, exist_ok=True)
+        os.makedirs(cls.MEMORIES_DIR, exist_ok=True)
+        memory_dir = os.path.join(cls.MEMORIES_DIR, memory)
+        os.makedirs(memory_dir, exist_ok=True)
+        
+        # Create path
+        path = cls._train_to_path(memory, train)
+        
+        # Create .mv2 file if it doesn't exist (auto-create new trains)
+        if not os.path.exists(path):
+            try:
+                store = MemoryStore.create(path)
+                store.close()
+            except Exception:
+                pass
+            # Ensure file exists on disk (memvid create may not touch filesystem)
+            if not os.path.exists(path):
+                Path(path).touch()
+            
+            # Update memory.json trains list
+            safe_train = train.replace('/', '-')
+            memory_json = os.path.join(memory_dir, "memory.json")
+            if os.path.exists(memory_json):
+                try:
+                    with open(memory_json, 'r') as f:
+                        data = json.load(f)
+                    if safe_train not in data.get("trains", []):
+                        data.setdefault("trains", []).append(safe_train)
+                        with open(memory_json, 'w') as f:
+                            json.dump(data, f, indent=2)
+                except (json.JSONDecodeError, KeyError):
+                    pass
+        
+        # Create context
+        context = MemoryContext(
+            active_memory=memory,
+            active_train=train,
+            path=path
+        )
+        
+        # Write context file
+        context_data = {
+            "active_memory": memory,
+            "active_train": train,
+            "path": path
+        }
+        
+        with open(cls.CONTEXT_FILE, 'w') as f:
+            json.dump(context_data, f, indent=2)
+        
+        return context
+
+    @classmethod
+    def resolve_path(cls, memory: Optional[str] = None, train: Optional[str] = None) -> str:
+        """Resolve .mv2 path from context or explicit args."""
+        if memory is not None and train is not None:
+            return cls._train_to_path(memory, train)
+        
+        context = cls.get_context()
+        if memory is not None:
+            return cls._train_to_path(memory, context.active_train)
+        if train is not None:
+            return cls._train_to_path(context.active_memory, train)
+        
+        return context.path
+
+    @classmethod
+    def ensure_memory(cls, name: str) -> str:
+        """Create memory dir + default train if doesn't exist."""
+        if not cls._is_valid_memory_name(name):
+            raise ValueError(f"Invalid memory name '{name}'. Use lowercase alphanumeric and hyphens only.")
+        
+        # Create config and memories directories
+        os.makedirs(cls.CONFIG_DIR, exist_ok=True)
+        os.makedirs(cls.MEMORIES_DIR, exist_ok=True)
+        
+        # Create memory directory
+        memory_dir = os.path.join(cls.MEMORIES_DIR, name)
+        os.makedirs(memory_dir, exist_ok=True)
+        
+        # Create default train (main.mv2) if it doesn't exist
+        main_path = cls._train_to_path(name, "main")
+        if not os.path.exists(main_path):
+            try:
+                store = MemoryStore.create(main_path)
+                store.close()
+            except Exception:
+                pass
+            # Ensure file exists on disk
+            if not os.path.exists(main_path):
+                Path(main_path).touch()
+        
+        # Create memory.json if it doesn't exist
+        memory_json_path = os.path.join(memory_dir, "memory.json")
+        if not os.path.exists(memory_json_path):
+            metadata = {
+                "name": name,
+                "visibility": "private",
+                "trains": ["main"],
+                "default_train": "main",
+                "description": ""
+            }
+            with open(memory_json_path, 'w') as f:
+                json.dump(metadata, f, indent=2)
+        
+        return main_path
+
+    @classmethod
+    def list_memories(cls) -> List[MemoryMetadata]:
+        """List all local memories."""
+        memories = []
+        
+        if not os.path.exists(cls.MEMORIES_DIR):
+            return memories
+        
+        for item in os.listdir(cls.MEMORIES_DIR):
+            memory_dir = os.path.join(cls.MEMORIES_DIR, item)
+            if os.path.isdir(memory_dir):
+                memory_json_path = os.path.join(memory_dir, "memory.json")
+                if os.path.exists(memory_json_path):
+                    try:
+                        with open(memory_json_path, 'r') as f:
+                            data = json.load(f)
+                        
+                        metadata = MemoryMetadata(
+                            name=data["name"],
+                            visibility=data.get("visibility", "private"),
+                            trains=data.get("trains", ["main"]),
+                            default_train=data.get("default_train", "main"),
+                            description=data.get("description", ""),
+                            created_at=data.get("created_at"),
+                            remote=data.get("remote")
+                        )
+                        memories.append(metadata)
+                    except (json.JSONDecodeError, KeyError):
+                        continue  # Skip malformed memory.json files
+        
+        return memories
+
+    @classmethod
+    def list_trains(cls, memory: Optional[str] = None) -> List[str]:
+        """List trains of thought in a memory."""
+        if memory is None:
+            context = cls.get_context()
+            memory = context.active_memory
+        
+        memory_dir = os.path.join(cls.MEMORIES_DIR, memory)
+        if not os.path.exists(memory_dir):
+            raise FileNotFoundError(f"Memory '{memory}' does not exist")
+        
+        trains = set()
+        
+        # Source 1: .mv2 files on disk
+        for item in os.listdir(memory_dir):
+            if item.endswith('.mv2'):
+                train_name = item[:-4]  # Remove .mv2 extension
+                trains.add(train_name)
+        
+        # Source 2: memory.json trains list (in case files haven't been created yet)
+        memory_json = os.path.join(memory_dir, "memory.json")
+        if os.path.exists(memory_json):
+            try:
+                with open(memory_json, 'r') as f:
+                    data = json.load(f)
+                for t in data.get("trains", []):
+                    trains.add(t)
+            except (json.JSONDecodeError, KeyError):
+                pass
+        
+        return sorted(trains)
+
+    @classmethod
+    def _auto_initialize(cls) -> MemoryContext:
+        """Auto-initialize default memory on first use."""
+        # Ensure default memory exists
+        cls.ensure_memory("default")
+        
+        # Set context to default/main
+        return cls.set_context("default", "main")
+
+    @classmethod
+    def _train_to_path(cls, memory: str, train: str) -> str:
+        """Convert memory + train to .mv2 file path."""
+        # Convert train name to filename-safe format (slashes to hyphens)
+        safe_train = train.replace('/', '-')
+        return os.path.join(cls.MEMORIES_DIR, memory, f"{safe_train}.mv2")
+
+    @classmethod
+    def _is_valid_memory_name(cls, name: str) -> bool:
+        """Check if memory name is valid (alphanumeric + hyphens only)."""
+        return bool(re.match(r'^[a-z0-9-]+$', name))

ate/memory/embeddings.py

@@ -0,0 +1,184 @@
+"""Embedding configuration and management for ate memory."""
+
+import os
+import requests
+from dataclasses import dataclass
+from typing import Optional, List, Dict, Any
+
+import memvid_sdk
+
+
+@dataclass
+class EmbeddingConfig:
+    """Embedding provider configuration."""
+    provider: str = "none"
+    model: Optional[str] = None
+    api_key: Optional[str] = None
+
+    def __post_init__(self):
+        """Validate provider after initialization."""
+        valid_providers = ["openai", "cohere", "voyage", "ollama", "none"]
+        if self.provider not in valid_providers:
+            raise ValueError(f"Invalid provider: {self.provider}. Must be one of {valid_providers}")
+
+        # Set default models based on provider
+        if self.model is None:
+            if self.provider == "openai":
+                self.model = "text-embedding-3-small"
+            elif self.provider == "cohere":
+                self.model = "embed-english-v3.0"
+            elif self.provider == "voyage":
+                self.model = "voyage-2"
+            elif self.provider == "ollama":
+                self.model = "nomic-embed-text"
+
+
+class EmbeddingManager:
+    """Detects and manages embedding providers for ate memory."""
+
+    @staticmethod
+    def detect() -> EmbeddingConfig:
+        """Auto-detect best available embedding provider from env.
+        
+        Detection order: OpenAI → Cohere → Voyage → Ollama → BM25-only
+        
+        Returns:
+            EmbeddingConfig with detected provider and settings
+        """
+        # Check OpenAI first (highest priority)
+        openai_key = os.environ.get('OPENAI_API_KEY')
+        if openai_key:
+            return EmbeddingConfig(
+                provider="openai",
+                api_key=openai_key
+            )
+
+        # Check Cohere second
+        cohere_key = os.environ.get('COHERE_API_KEY')
+        if cohere_key:
+            return EmbeddingConfig(
+                provider="cohere",
+                api_key=cohere_key
+            )
+
+        # Check Voyage third
+        voyage_key = os.environ.get('VOYAGE_API_KEY')
+        if voyage_key:
+            return EmbeddingConfig(
+                provider="voyage",
+                api_key=voyage_key
+            )
+
+        # Check Ollama fourth (local service)
+        ollama_host = os.environ.get('OLLAMA_HOST', 'http://localhost:11434')
+        if EmbeddingManager._is_ollama_available(ollama_host):
+            return EmbeddingConfig(
+                provider="ollama",
+                model="nomic-embed-text"
+            )
+
+        # No providers available
+        return EmbeddingConfig(provider="none")
+
+    @staticmethod
+    def _is_ollama_available(host: str) -> bool:
+        """Check if Ollama is reachable at the given host."""
+        try:
+            response = requests.get(f'{host}/api/tags', timeout=2)
+            return response.status_code == 200
+        except:
+            return False
+
+    @staticmethod
+    def get_provider(config: EmbeddingConfig):
+        """Get a memvid_sdk EmbeddingProvider from config.
+        
+        Args:
+            config: EmbeddingConfig instance
+            
+        Returns:
+            EmbeddingProvider instance or None if provider is "none"
+        """
+        if config.provider == "none":
+            return None
+
+        return memvid_sdk.embeddings.get_embedder(
+            provider=config.provider,
+            model=config.model,
+            api_key=config.api_key
+        )
+
+    @staticmethod
+    def available_providers() -> List[Dict[str, Any]]:
+        """List all detected providers with status.
+        
+        Returns:
+            List of provider status dictionaries
+        """
+        providers = []
+
+        # Check OpenAI
+        openai_key = os.environ.get('OPENAI_API_KEY')
+        if openai_key:
+            providers.append({
+                "name": "openai",
+                "available": True,
+                "model": "text-embedding-3-small",
+                "source": "OPENAI_API_KEY"
+            })
+        else:
+            providers.append({
+                "name": "openai",
+                "available": False,
+                "reason": "OPENAI_API_KEY not set"
+            })
+
+        # Check Cohere
+        cohere_key = os.environ.get('COHERE_API_KEY')
+        if cohere_key:
+            providers.append({
+                "name": "cohere",
+                "available": True,
+                "model": "embed-english-v3.0",
+                "source": "COHERE_API_KEY"
+            })
+        else:
+            providers.append({
+                "name": "cohere",
+                "available": False,
+                "reason": "COHERE_API_KEY not set"
+            })
+
+        # Check Voyage
+        voyage_key = os.environ.get('VOYAGE_API_KEY')
+        if voyage_key:
+            providers.append({
+                "name": "voyage",
+                "available": True,
+                "model": "voyage-2",
+                "source": "VOYAGE_API_KEY"
+            })
+        else:
+            providers.append({
+                "name": "voyage",
+                "available": False,
+                "reason": "VOYAGE_API_KEY not set"
+            })
+
+        # Check Ollama
+        ollama_host = os.environ.get('OLLAMA_HOST', 'http://localhost:11434')
+        if EmbeddingManager._is_ollama_available(ollama_host):
+            providers.append({
+                "name": "ollama",
+                "available": True,
+                "model": "nomic-embed-text",
+                "source": ollama_host
+            })
+        else:
+            providers.append({
+                "name": "ollama",
+                "available": False,
+                "reason": "OLLAMA_HOST not set, localhost:11434 not reachable"
+            })
+
+        return providers