Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

8.1 KB
Raw Blame
"""File-based report storage implementation."""

import os
from pathlib import Path
from typing import Dict, Any, List, Optional
from loguru import logger

from .base import ReportStorage
from ..config.paths import (
    get_research_outputs_directory,
    restrict_directory_to_owner,
)


class FileReportStorage(ReportStorage):
    """Store reports as files on disk."""

    def __init__(self, base_dir: Optional[Path] = None):
        """Initialize file storage.

        Args:
            base_dir: Base directory for storing reports.
                     If None, uses default research outputs directory.

        Raises:
            DirectoryNotPrivateError: On POSIX, another OS account owns the
                directory or its filesystem did not keep mode 0700.
            OSError: The directory could not be created or restricted.
            DirectoryCreationSecurityError: The path contains a null byte or
                a ``..`` segment.
        """
        # Lazy import: mirrors the other lazy security imports in this
        # module (e.g. file_write_verifier) and avoids pulling security
        # into this module's top-level import graph.
        from ..security.directory_creation import create_directory

        self.base_dir = create_directory(
            base_dir or get_research_outputs_directory(),
            context="file report storage base directory",
            mode=0o700,
        )
        # The directory may already exist at 0755 from an older install.
        # Protect legacy backups, and refuse the directory unless it is
        # private, before any new write.
        restrict_directory_to_owner(self.base_dir)

    def _contained_path(self, research_id: str, filename: str) -> Path:
        """Return ``base_dir / filename`` resolved, or raise ValueError.

        Both sides are resolved with resolve_allow_missing(), never a bare
        non-strict resolve(), which can leave part of the path unresolved
        (a symlink chain whose resolved form outgrows PATH_MAX) and so hide
        an escape.
        """
        from ..security.path_validator import resolve_allow_missing

        try:
            candidate = resolve_allow_missing(self.base_dir / filename)
            base = resolve_allow_missing(self.base_dir)
        except OSError:
            raise ValueError(
                f"Unresolvable report path for research_id: {research_id!r}"
            )
        if not candidate.is_relative_to(base):
            raise ValueError(
                f"Path traversal attempt with research_id: {research_id!r}"
            )
        return candidate

    def _get_report_path(self, research_id: str) -> Path:
        """Get the file path for a report."""
        return self._contained_path(research_id, f"{research_id}.md")

    def _get_metadata_path(self, research_id: str) -> Path:
        """Get the file path for report metadata."""
        return self._contained_path(research_id, f"{research_id}_metadata.json")

    def save_report(
        self,
        research_id: str,
        content: str,
        metadata: Optional[Dict[str, Any]] = None,
        username: Optional[str] = None,
    ) -> bool:
        """Save report to file."""
        try:
            from ..security.file_write_verifier import (
                write_file_verified,
                write_json_verified,
            )

            report_path = self._get_report_path(research_id)

            # Save content
            write_file_verified(
                report_path,
                content,
                "report.enable_file_backup",
                context="file storage backup",
                permissions=0o600 if os.name == "posix" else None,
            )

            # Save metadata if provided
            if metadata:
                metadata_path = self._get_metadata_path(research_id)
                write_json_verified(
                    metadata_path,
                    metadata,
                    "report.enable_file_backup",
                    context="file storage metadata",
                    permissions=0o600 if os.name == "posix" else None,
                )

            logger.info(
                f"Saved report for research {research_id} to {report_path}"
            )
            return True

        except Exception:
            logger.exception("Error saving report to file")
            return False

    def get_report(
        self, research_id: str, username: Optional[str] = None
    ) -> Optional[str]:
        """Get report from file."""
        try:
            report_path = self._get_report_path(research_id)

            if not report_path.exists():
                return None

            with open(report_path, "r", encoding="utf-8") as f:
                return f.read()

        except Exception:
            logger.exception("Error reading report from file")
            return None

    def get_report_with_metadata(
        self, research_id: str, username: Optional[str] = None
    ) -> Optional[Dict[str, Any]]:
        """Get report with metadata from files."""
        try:
            content = self.get_report(research_id)
            if not content:
                return None

            result = {"content": content, "metadata": {}}

            # Try to load metadata
            metadata_path = self._get_metadata_path(research_id)
            if metadata_path.exists():
                import json

                with open(metadata_path, "r", encoding="utf-8") as f:
                    result["metadata"] = json.load(f)

            return result

        except Exception:
            logger.exception("Error getting report with metadata")
            return None

    def list_reports(
        self, username: Optional[str] = None
    ) -> List[Dict[str, Any]]:
        """List reports from file system."""
        try:
            from datetime import datetime, timezone

            reports = []
            for report_path in self.base_dir.glob("*.md"):
                research_id = report_path.stem
                metadata = self._load_metadata(research_id)
                reports.append(
                    {
                        "id": research_id,
                        "query": metadata.get("query") if metadata else None,
                        "mode": metadata.get("mode", "unknown")
                        if metadata
                        else "unknown",
                        "created_at": datetime.fromtimestamp(
                            report_path.stat().st_mtime, tz=timezone.utc
                        ).isoformat(),
                        "completed_at": metadata.get("completed_at")
                        if metadata
                        else None,
                    }
                )
            return reports
        except Exception:
            logger.exception("Error listing reports from file system")
            return []

    def _load_metadata(self, research_id: str) -> Optional[Dict[str, Any]]:
        """Load metadata JSON for a report if it exists."""
        try:
            metadata_path = self._get_metadata_path(research_id)
            if metadata_path.exists():
                import json

                with open(metadata_path, "r", encoding="utf-8") as f:
                    return json.load(f)
        except Exception:
            logger.debug(f"Failed to load metadata for {research_id}")
        return None

    def delete_report(
        self, research_id: str, username: Optional[str] = None
    ) -> bool:
        """Delete report files."""
        try:
            report_path = self._get_report_path(research_id)
            metadata_path = self._get_metadata_path(research_id)

            deleted = False

            if report_path.exists():
                report_path.unlink()
                deleted = True

            if metadata_path.exists():
                metadata_path.unlink()

            return deleted

        except Exception:
            logger.exception("Error deleting report files")
            return False

    def report_exists(
        self, research_id: str, username: Optional[str] = None
    ) -> bool:
        """Check if report file exists."""
        return self._get_report_path(research_id).exists()