feat(context): Phase 1 - Foundation: Types, Config & Exceptions #79

New Issue

cardosofelipe · 2026-01-04T00:51:15Z

cardosofelipe commented

2026-01-04 00:51:15 +00:00

Overview

Define the foundational types, configuration, and exceptions for the Context Management Engine.

Parent Issue

#61: Context Management Engine

Implementation Tasks

1. Create `config.py`

Create ContextSettings Pydantic settings class
Define budget allocation defaults (system: 5%, task: 10%, knowledge: 40%, etc.)
Define compression settings
Define caching settings (TTL, prefix)
Define performance settings (max assembly time)

class ContextSettings(BaseSettings):
    model_config = SettingsConfigDict(env_prefix="CONTEXT_")

    # Budget defaults
    default_budget_system: float = 0.05
    default_budget_task: float = 0.10
    default_budget_knowledge: float = 0.40
    default_budget_conversation: float = 0.20
    default_budget_tools: float = 0.05
    default_budget_response: float = 0.15
    default_budget_buffer: float = 0.05

    # Compression
    compression_threshold: float = 0.8
    summary_model_group: str = "fast"

    # Caching
    cache_enabled: bool = True
    cache_ttl_seconds: int = 3600
    cache_prefix: str = "ctx"

    # Performance
    max_assembly_time_ms: int = 100
    parallel_scoring: bool = True

2. Create `exceptions.py`

Create ContextError base exception
Create BudgetExceededError
Create TokenCountError
Create CompressionError
Create AssemblyTimeoutError

3. Create `types/base.py`

Create ContextType enum (SYSTEM, KNOWLEDGE, CONVERSATION, TASK, TOOL)
Create BaseContext abstract dataclass
Implement to_dict() serialization
Implement from_dict() deserialization

class ContextType(str, Enum):
    SYSTEM = "system"
    KNOWLEDGE = "knowledge"
    CONVERSATION = "conversation"
    TASK = "task"
    TOOL = "tool"

@dataclass
class BaseContext(ABC):
    content: str
    source: str
    priority: int = 0
    timestamp: datetime = field(default_factory=datetime.utcnow)
    token_count: int | None = None

    @abstractmethod
    def get_type(self) -> ContextType: ...

4. Create Context Type Classes

types/system.py - SystemContext
types/knowledge.py - KnowledgeContext (with score field)
types/conversation.py - ConversationContext (with role field)
types/task.py - TaskContext
types/tool.py - ToolContext (with tool_name field)

5. Create `init.py`

Export public API
Define __all__

Files to Create

backend/app/services/context/
├── __init__.py
├── config.py
├── exceptions.py
└── types/
    ├── __init__.py
    ├── base.py
    ├── system.py
    ├── knowledge.py
    ├── conversation.py
    ├── task.py
    └── tool.py

Acceptance Criteria

All context types defined with proper inheritance
Configuration loads from environment variables
Exceptions have proper error messages
Unit tests for serialization/deserialization
Type hints on all public functions

Dependencies

None (first phase)

Labels

phase-2, context, backend

## Overview Define the foundational types, configuration, and exceptions for the Context Management Engine. ## Parent Issue - #61: Context Management Engine --- ## Implementation Tasks ### 1. Create `config.py` - [ ] Create `ContextSettings` Pydantic settings class - [ ] Define budget allocation defaults (system: 5%, task: 10%, knowledge: 40%, etc.) - [ ] Define compression settings - [ ] Define caching settings (TTL, prefix) - [ ] Define performance settings (max assembly time) ```python class ContextSettings(BaseSettings): model_config = SettingsConfigDict(env_prefix="CONTEXT_") # Budget defaults default_budget_system: float = 0.05 default_budget_task: float = 0.10 default_budget_knowledge: float = 0.40 default_budget_conversation: float = 0.20 default_budget_tools: float = 0.05 default_budget_response: float = 0.15 default_budget_buffer: float = 0.05 # Compression compression_threshold: float = 0.8 summary_model_group: str = "fast" # Caching cache_enabled: bool = True cache_ttl_seconds: int = 3600 cache_prefix: str = "ctx" # Performance max_assembly_time_ms: int = 100 parallel_scoring: bool = True ``` ### 2. Create `exceptions.py` - [ ] Create `ContextError` base exception - [ ] Create `BudgetExceededError` - [ ] Create `TokenCountError` - [ ] Create `CompressionError` - [ ] Create `AssemblyTimeoutError` ### 3. Create `types/base.py` - [ ] Create `ContextType` enum (SYSTEM, KNOWLEDGE, CONVERSATION, TASK, TOOL) - [ ] Create `BaseContext` abstract dataclass - [ ] Implement `to_dict()` serialization - [ ] Implement `from_dict()` deserialization ```python class ContextType(str, Enum): SYSTEM = "system" KNOWLEDGE = "knowledge" CONVERSATION = "conversation" TASK = "task" TOOL = "tool" @dataclass class BaseContext(ABC): content: str source: str priority: int = 0 timestamp: datetime = field(default_factory=datetime.utcnow) token_count: int | None = None @abstractmethod def get_type(self) -> ContextType: ... ``` ### 4. Create Context Type Classes - [ ] `types/system.py` - SystemContext - [ ] `types/knowledge.py` - KnowledgeContext (with score field) - [ ] `types/conversation.py` - ConversationContext (with role field) - [ ] `types/task.py` - TaskContext - [ ] `types/tool.py` - ToolContext (with tool_name field) ### 5. Create `__init__.py` - [ ] Export public API - [ ] Define `__all__` --- ## Files to Create ``` backend/app/services/context/ ├── __init__.py ├── config.py ├── exceptions.py └── types/ ├── __init__.py ├── base.py ├── system.py ├── knowledge.py ├── conversation.py ├── task.py └── tool.py ``` --- ## Acceptance Criteria - [ ] All context types defined with proper inheritance - [ ] Configuration loads from environment variables - [ ] Exceptions have proper error messages - [ ] Unit tests for serialization/deserialization - [ ] Type hints on all public functions --- ## Dependencies - None (first phase) ## Labels `phase-2`, `context`, `backend`

cardosofelipe referenced this issue

2026-01-04 00:52:20 +00:00

feat(context): Phase 5 - Model Adapters (Claude, OpenAI) #83

cardosofelipe referenced this issue

2026-01-04 00:52:21 +00:00

feat(context): Phase 6 - Caching Layer #84

cardosofelipe referenced this issue

2026-01-04 00:52:21 +00:00

feat(context): Phase 7 - Main Engine & Integration #85

cardosofelipe referenced this issue

2026-01-04 00:54:11 +00:00

feat(mcp): Context Management Engine #61