friday-framework-core 0.1.0a0__py3-none-any.whl

friday_core/__init__.py

@@ -0,0 +1,129 @@
+"""
+Friday Core Package
+Foundation interfaces and shared utilities.
+
+This package provides the foundational "glue" for the Friday Framework:
+- Configuration management (FridayBaseSettings)
+- Exception hierarchy (FridayError and subclasses)
+- Logging utilities (get_logger, LoggerProtocol)
+- Telemetry interfaces (TelemetryInterface, DebugTelemetryRecorder)
+- Storage adapter protocols (EpisodicStoreAdapter, VectorStoreAdapter, GraphStoreAdapter)
+- Context engineering protocol (ContextEngineeringInterface)
+
+Ref: Batch 0 Specification
+"""  # noqa: E501
+
+# Configuration
+# Security
+from friday_core import security
+from friday_core.config import FridayBaseSettings
+
+# Exceptions
+from friday_core.exceptions import (
+    ContextOverflowError,
+    FridayError,
+    MemoryError,
+    ProviderAPIError,
+)
+
+# Interfaces
+from friday_core.interfaces import (
+    AgentInterface,
+    ArbitrationDecision,
+    ArbitrationInterface,
+    ChatCompletionResponse,
+    ContextEngineeringInterface,
+    EmbeddingModel,
+    EpisodicStoreAdapter,
+    GraphStoreAdapter,
+    LabHarnessInterface,
+    LLMClient,
+    MemoryPromotionProposal,
+    MultiAgentMemoryInterface,
+    NamespacePolicyInterface,
+    RegistryInterface,
+    SchemaFormat,
+    SharedWriteCapability,
+    SystemRuntime,
+    ToolAdapter,
+    ToolCall,
+    ToolDefinition,
+    ToolRegistry,
+    TranscriptBackedEpisodicStore,
+    TranscriptStoreProtocol,
+    VectorStoreAdapter,
+)
+
+# Logging
+from friday_core.logging import LoggerProtocol, get_logger
+
+# Memory Profiles
+from friday_core.profiles import (
+    MemoryProfile,
+    create_graph_store,
+    create_vector_store,
+)
+
+# Telemetry
+from friday_core.telemetry import (
+    DebugTelemetryRecorder,
+    EventRecord,
+    SpanRecord,
+    TelemetryInterface,
+)
+
+__all__ = [
+    # Configuration
+    "FridayBaseSettings",
+    # Exceptions
+    "FridayError",
+    "MemoryError",
+    "ContextOverflowError",
+    "ProviderAPIError",
+    # Logging
+    "LoggerProtocol",
+    "get_logger",
+    # Telemetry
+    "TelemetryInterface",
+    "DebugTelemetryRecorder",
+    "SpanRecord",
+    "EventRecord",
+    # Storage Adapters
+    "EpisodicStoreAdapter",
+    "VectorStoreAdapter",
+    "GraphStoreAdapter",
+    "NamespacePolicyInterface",
+    "MultiAgentMemoryInterface",
+    "ArbitrationInterface",
+    "ArbitrationDecision",
+    "SharedWriteCapability",
+    "MemoryPromotionProposal",
+    # Context Engineering
+    "ContextEngineeringInterface",
+    # LLM Interfaces
+    "LLMClient",
+    "EmbeddingModel",
+    "ChatCompletionResponse",
+    "ToolCall",
+    # Tool Management
+    "SchemaFormat",
+    "ToolDefinition",
+    "ToolAdapter",
+    "ToolRegistry",
+    # Runtime Interfaces
+    "SystemRuntime",
+    "AgentInterface",
+    "RegistryInterface",
+    "LabHarnessInterface",
+    # Memory Profiles
+    "MemoryProfile",
+    "create_vector_store",
+    "create_graph_store",
+    # Transcript Integration
+    "TranscriptBackedEpisodicStore",
+    "TranscriptStoreProtocol",
+    # Security
+    "security",
+]
+
+__version__ = "0.1.0"

friday_core/config.py

@@ -0,0 +1,39 @@
+"""
+Global configuration management using Pydantic Settings.
+Handles environment variable loading and validation.
+
+Ref: Batch 0 Specification, Section 3.1
+"""
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class FridayBaseSettings(BaseSettings):
+    """
+    Global settings inherited by all packages.
+
+    Configuration is loaded from environment variables and .env files.
+    Inner components MUST NOT instantiate this directly - configuration
+    should be injected via constructor parameters.
+
+    Example:
+        # In application layer (friday-cli):
+        settings = FridayBaseSettings()
+        engine = ContextEngine(
+            model_name=settings.DEFAULT_MODEL,
+            api_key=settings.OPENAI_API_KEY
+        )
+    """
+
+    APP_ENV: str = "development"  # development | production | testing
+    LOG_LEVEL: str = "INFO"
+
+    # LLM Settings (needed by Memory components)
+    DEFAULT_MODEL: str = "gpt-4-turbo"
+    OPENAI_API_KEY: str | None = None
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )

friday_core/exceptions.py

@@ -0,0 +1,50 @@
+"""
+Base exception hierarchy for the Friday Framework.
+Defines FridayError, MemoryError, ContextOverflowError, etc.
+
+Ref: Batch 0 Specification, Section 4.2
+"""
+
+
+class FridayError(Exception):
+    """
+    Root exception for the Friday Framework.
+
+    All framework-specific exceptions inherit from this class,
+    allowing consumers to catch all Friday errors with a single handler.
+    """
+
+    pass
+
+
+class MemoryError(FridayError):
+    """
+    Base exception for database/storage failures.
+
+    Raised when operations on Vector, Graph, or Episodic stores fail.
+    """
+
+    pass
+
+
+class ContextOverflowError(FridayError):
+    """
+    Raised when the Context Budget is impossible to satisfy.
+
+    This occurs when the minimum required context (system prompt,
+    immediate history, critical user data) exceeds the available
+    token budget.
+    """
+
+    pass
+
+
+class ProviderAPIError(FridayError):
+    """
+    Raised when LLM provider API calls fail.
+
+    Wraps errors from LiteLLM, OpenAI, or other provider SDKs
+    to provide a consistent error interface.
+    """
+
+    pass

friday_core/interfaces/__init__.py

@@ -0,0 +1,98 @@
+"""
+Shared Protocol Definitions.
+
+This module exports all abstract base classes (protocols) that define
+the contracts for swappable components in the Friday Framework.
+
+Storage Adapters (Batch 1):
+- EpisodicStoreAdapter: Short-term conversation history
+- VectorStoreAdapter: Semantic search storage
+- GraphStoreAdapter: Relationship graph storage
+
+Context Engineering (Batch 2a):
+- ContextEngineeringInterface: Context strategy lifecycle
+
+LLM Interfaces (Batch 3):
+- LLMClient: Chat completion protocol
+- EmbeddingModel: Text embedding protocol
+- ChatCompletionResponse: Structured LLM response
+- ToolCall: Tool call representation
+
+Tool Management (Batch 3):
+- ToolRegistry: Tool registration and resolution
+
+Runtime Interfaces (Phase 1):
+- SystemRuntime: Headless runtime kernel contract
+- AgentInterface: Agent execution contract
+- RegistryInterface: Agent registry contract
+- LabHarnessInterface: Integration test harness contract
+
+Transcript Integration:
+- TranscriptBackedEpisodicStore: Bridge adapter for persistent transcripts
+"""
+
+from friday_core.interfaces.agent import AgentInterface
+from friday_core.interfaces.context import ContextEngineeringInterface
+from friday_core.interfaces.lab import LabHarnessInterface
+from friday_core.interfaces.llm import (
+    ChatCompletionResponse,
+    EmbeddingModel,
+    LLMClient,
+    ToolCall,
+)
+from friday_core.interfaces.memory import (
+    ArbitrationDecision,
+    ArbitrationInterface,
+    EpisodicStoreAdapter,
+    GraphStoreAdapter,
+    MemoryPromotionProposal,
+    MultiAgentMemoryInterface,
+    NamespacePolicyInterface,
+    SharedWriteCapability,
+    VectorStoreAdapter,
+)
+from friday_core.interfaces.registry import RegistryInterface
+from friday_core.interfaces.runtime import SystemRuntime
+from friday_core.interfaces.tools import (
+    SchemaFormat,
+    ToolAdapter,
+    ToolDefinition,
+    ToolRegistry,
+)
+from friday_core.interfaces.transcript import (
+    TranscriptBackedEpisodicStore,
+    TranscriptStoreProtocol,
+)
+
+__all__ = [
+    # Storage Adapters
+    "EpisodicStoreAdapter",
+    "VectorStoreAdapter",
+    "GraphStoreAdapter",
+    "NamespacePolicyInterface",
+    "MultiAgentMemoryInterface",
+    "ArbitrationInterface",
+    "ArbitrationDecision",
+    "SharedWriteCapability",
+    "MemoryPromotionProposal",
+    # Context Engineering
+    "ContextEngineeringInterface",
+    # LLM Interfaces
+    "LLMClient",
+    "EmbeddingModel",
+    "ChatCompletionResponse",
+    "ToolCall",
+    # Tool Management
+    "SchemaFormat",
+    "ToolDefinition",
+    "ToolAdapter",
+    "ToolRegistry",
+    # Runtime Interfaces
+    "SystemRuntime",
+    "AgentInterface",
+    "RegistryInterface",
+    "LabHarnessInterface",
+    # Transcript Integration
+    "TranscriptBackedEpisodicStore",
+    "TranscriptStoreProtocol",
+]

friday_core/interfaces/agent.py

@@ -0,0 +1,71 @@
+"""
+Agent Interface.
+
+Defines the AgentInterface contract that all agent implementations
+must satisfy. The interface matches the existing AgentBase signatures
+to ensure backward compatibility.
+
+Ref: Phase 1 Build Plan, Section 2 - Interface Compliance Matrix
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class AgentInterface(ABC):
+    """
+    Abstract interface for all Friday agents.
+
+    Defines the minimal contract for agent lifecycle management
+    and execution. The signatures intentionally match AgentBase
+    to ensure existing implementations comply without modification.
+    """
+
+    @abstractmethod
+    async def run(self, input_signal: str) -> str:
+        """
+        Execute the agent's core logic on the given input.
+
+        Args:
+            input_signal: User or orchestrator input to process.
+
+        Returns:
+            Agent response string.
+        """
+        ...
+
+    @abstractmethod
+    async def initialize_session(
+        self,
+        session_id: str | None = None,
+        user_id: str = "default",
+    ) -> Any:
+        """
+        Initialize or resume a session for this agent.
+
+        Args:
+            session_id: Existing session ID to resume, or None
+                to create a new session.
+            user_id: User identifier for the session.
+
+        Returns:
+            SessionState instance for the initialized session.
+
+        Note:
+            This signature matches AgentBase.initialize_session(),
+            not the original spec's (session_id: str, user_id: str) -> None.
+        """
+        ...
+
+    @abstractmethod
+    def emit_telemetry(self, event_type: str, data: dict[str, Any]) -> None:
+        """
+        Emit a telemetry event.
+
+        Args:
+            event_type: Type of event to emit.
+            data: Event payload data.
+        """
+        ...

friday_core/interfaces/context.py

@@ -0,0 +1,187 @@
+"""
+Context Engineering Interface Protocol.
+Defines the standard lifecycle for context engineering strategies.
+
+Ref: Batch 2a Specification, Section 1.1
+
+Note: Type references like 'SessionState', 'ConsolidationReport', 'ContextPayload',
+and 'Interaction' are forward references to models that will be defined in
+friday-memory/models/. This allows the protocol to be defined without circular imports.
+"""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    # Forward references to types defined in friday-memory/models/
+    # These are only used for type checking, not at runtime
+    from typing import TypeAlias
+
+    SessionState: TypeAlias = Any  # Will be friday_memory.models.SessionState
+    ConsolidationReport: TypeAlias = (
+        Any  # Will be friday_memory.models.ConsolidationReport
+    )
+    ContextPayload: TypeAlias = Any  # Will be friday_memory.models.ContextPayload
+    Interaction: TypeAlias = Any  # Will be friday_memory.models.Interaction
+
+
+class ContextEngineeringInterface(ABC):
+    """
+    The Master Protocol for Context Engineering.
+
+    Defines the standard lifecycle methods that any context strategy must
+    implement. This abstraction ensures the underlying Memory Architecture
+    is decoupled from the strategy used to process it.
+
+    Lifecycle:
+    1. initialize_session() - Start or resume a session
+    2. extract_context() - Harvest facts from new interactions
+    3. consolidate_memory() - Merge short-term into long-term memory
+    4. assemble_context() - Build the context payload for inference
+    5. format_prompt() - Structure the final prompt for the LLM
+
+    Implementations:
+    - ContextAssembler (default for Friday Copilot)
+    - Custom strategies can be "snapped in" via this interface
+    """
+
+    # --- Session Management ---
+
+    @abstractmethod
+    async def initialize_session(self, session_id: str, user_id: str) -> "SessionState":
+        """
+        Loads or creates the session context, establishing the 'Thread'.
+
+        Args:
+            session_id: Unique identifier for the session
+            user_id: Unique identifier for the user
+
+        Returns:
+            SessionState containing session metadata and scoped variables
+        """
+        pass
+
+    @abstractmethod
+    async def restore_checkpoint(self, session_id: str, turn_id: str) -> "SessionState":
+        """
+        Reverts the session state to a previous turn.
+
+        Used for error recovery - allows "time travel" to undo mistakes.
+
+        Algorithm:
+        1. Triggers MemoryController.rollback_session()
+        2. Reloads the SessionState effective at that time
+
+        Args:
+            session_id: Unique identifier for the session
+            turn_id: The turn ID to restore to
+
+        Returns:
+            SessionState as it was at the target turn
+        """
+        pass
+
+    # --- The Ingestion Cycle (Extraction) ---
+
+    @abstractmethod
+    async def extract_context(
+        self, interaction_turn: "Interaction", async_execution: bool = True
+    ) -> None:
+        """
+        Analyzes the last turn to identify 'Hot' facts or memories.
+
+        Triggers 'Memory Generation' (Extraction) tasks to harvest
+        entities, preferences, and other structured data from the
+        raw conversation.
+
+        Args:
+            interaction_turn: The completed interaction to analyze
+            async_execution: If True, run extraction in background (default)
+                           If False, block until extraction completes
+        """
+        pass
+
+    # --- The Maintenance Cycle (Consolidation) ---
+
+    @abstractmethod
+    async def consolidate_memory(self, session_id: str) -> "ConsolidationReport":
+        """
+        Merges fragmented short-term memories into solidified long-term blocks.
+
+        Performs:
+        - Deduplication of similar facts
+        - Summarization of verbose interaction sequences
+        - Conflict resolution when facts contradict
+        - Entity resolution (merging 'Bob' and 'Robert')
+
+        Args:
+            session_id: The session to consolidate
+
+        Returns:
+            ConsolidationReport with statistics on the consolidation
+        """
+        pass
+
+    # --- The Retrieval Cycle (Construction) ---
+
+    @abstractmethod
+    async def assemble_context(
+        self,
+        query: str,
+        state: "SessionState",
+        budget_limit: int,
+        context_strategy: str = "standard",
+    ) -> "ContextPayload":
+        """
+        The core 'Recall' step - selects, ranks, and compresses data.
+
+        Supports both Passive and Active retrieval:
+        - Passive: query is the user's message (broad search)
+        - Active: query is agent-generated for specific lookup
+
+        Uses the Knapsack algorithm to fit content within token budget,
+        prioritizing by the defined hierarchy (immediate context > recent
+        history > weak matches > deep history).
+
+        Args:
+            query: The search string (user message or agent query)
+            state: Current SessionState with scoped variables
+            budget_limit: Maximum tokens for dynamic content
+            context_strategy: Retrieval strategy name. `minimal` may bypass
+                semantic recall, while `standard` and `extended` use the full
+                semantic memory pipeline.
+
+        Returns:
+            ContextPayload with history, passages, entities, facts
+        """
+        pass
+
+    # --- The Formatting Cycle (Architecture) ---
+
+    @abstractmethod
+    async def format_prompt(
+        self, system_prompt: str, payload: "ContextPayload"
+    ) -> list[dict[str, Any]]:
+        """
+        Physically arranges the messages for optimal model attention.
+
+        Structures the prompt to combat "Lost in the Middle" by placing
+        critical information at start and end of context.
+
+        Layout order:
+        1. System Block (identity & guardrails)
+        2. Transparency Block (recent auto-archived memories)
+        3. Procedural Memory (few-shot examples)
+        4. Semantic Memory (vector passages)
+        5. Episodic Memory (conversation history)
+        6. State Memory (scoped variables)
+        7. User Trigger (the query)
+
+        Args:
+            system_prompt: The system instructions
+            payload: The assembled ContextPayload
+
+        Returns:
+            List of message dicts ready for LLM API (role, content format)
+        """
+        pass

friday_core/interfaces/lab.py

@@ -0,0 +1,65 @@
+"""
+Lab Harness Interface.
+
+Defines the LabHarnessInterface for integration testing the
+agent framework in a controlled, deterministic environment.
+
+Ref: Phase 1 Build Plan, Section 7
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class LabHarnessInterface(ABC):
+    """
+    Integration environment for stress-testing the agent hive.
+
+    Provides deterministic test execution by replacing LLM agents
+    with mock implementations and enabling controlled conflict
+    injection and session replay.
+    """
+
+    @abstractmethod
+    def mock_agent(self, name: str, fixed_responses: list[str]) -> None:
+        """
+        Replace a real LLM agent with a deterministic mock.
+
+        The mock agent returns responses from `fixed_responses` in
+        order, cycling back to the start if exhausted.
+
+        Args:
+            name: Agent name to mock.
+            fixed_responses: Ordered list of responses the mock
+                will return.
+        """
+        ...
+
+    @abstractmethod
+    async def inject_conflict(self, fact_a: Any, fact_b: Any) -> None:
+        """
+        Simulate a race condition or semantic conflict.
+
+        Args:
+            fact_a: First conflicting memory proposal.
+            fact_b: Second conflicting memory proposal.
+
+        Raises:
+            NotImplementedError: In Phase 1 (requires Arbitrator).
+        """
+        ...
+
+    @abstractmethod
+    async def replay_session(self, session_log_path: str) -> None:
+        """
+        Deterministically replay a recorded session.
+
+        Args:
+            session_log_path: Path to session transcript log.
+
+        Raises:
+            NotImplementedError: In Phase 1 (requires transcript tooling).
+        """
+        ...