src.ai.providers.base_provider module#

Base LLM Provider Interface.

Defines the interface that all LLM providers must implement. Separated to avoid circular imports.

This module provides the abstract base class and data structures for implementing LLM providers (OpenAI, Anthropic, etc.).

Classes#

SemanticAnalysis: Result of semantic task analysis by LLM
SemanticDependency: Semantic relationship between tasks
EffortEstimate: AI-powered effort estimation result
BaseLLMProvider: Abstract base class for LLM providers

Examples

>>> class CustomProvider(BaseLLMProvider):
...     async def analyze_task(self, task, context):
...         # Custom implementation
...         return SemanticAnalysis(...)

class src.ai.providers.base_provider.SemanticAnalysis[source]#

Bases: object

Result of semantic task analysis.

Contains LLM’s understanding of task meaning and implications.

task_intent#

LLM’s interpretation of what the task aims to achieve

Type:: str

semantic_dependencies#

Tasks that logically should complete before this one

Type:: list of str

risk_factors#

Identified risks or complexity factors

Type:: list of str

suggestions#

LLM-generated improvement suggestions

Type:: list of str

confidence#

Model’s confidence in analysis (0.0-1.0)

Type:: float

reasoning#

Explanation of the analysis logic

Type:: str

risk_assessment#

Detailed risk breakdown by category

Type:: dict

fallback_used#

Whether a fallback model was used

Type:: bool

task_intent: str#

semantic_dependencies: List[str]#

risk_factors: List[str]#

suggestions: List[str]#

confidence: float#

reasoning: str#

risk_assessment: Dict[str, Any]#

fallback_used: bool = False#

__init__(task_intent, semantic_dependencies, risk_factors, suggestions, confidence, reasoning, risk_assessment, fallback_used=False)#

Parameters:

task_intent (str)
semantic_dependencies (List[str])
risk_factors (List[str])
suggestions (List[str])
confidence (float)
reasoning (str)
risk_assessment (Dict[str, Any])
fallback_used (bool)

Return type:

None

class src.ai.providers.base_provider.SemanticDependency[source]#

Bases: object

Semantic dependency relationship between tasks.

Represents LLM-inferred dependencies based on task meaning.

dependent_task_id#

ID of task that depends on another

Type:: str

dependency_task_id#

ID of task that must complete first

Type:: str

confidence#

Confidence in this dependency (0.0-1.0)

Type:: float

reasoning#

Explanation of why dependency exists

Type:: str

dependency_type#

Type of dependency: ‘logical’, ‘technical’, or ‘temporal’

Type:: str

Examples

>>> dep = SemanticDependency(
...     dependent_task_id="deploy-api",
...     dependency_task_id="test-api",
...     confidence=0.95,
...     reasoning="Deployment requires successful tests",
...     dependency_type="logical"
... )

dependent_task_id: str#

dependency_task_id: str#

confidence: float#

reasoning: str#

dependency_type: str#

__init__(dependent_task_id, dependency_task_id, confidence, reasoning, dependency_type)#

Parameters:

dependent_task_id (str)
dependency_task_id (str)
confidence (float)
reasoning (str)
dependency_type (str)

Return type:

None

class src.ai.providers.base_provider.EffortEstimate[source]#

Bases: object

AI-powered effort estimation.

Provides intelligent time estimates based on task analysis.

estimated_hours#

Estimated hours to complete the task

Type:: float

confidence#

Confidence in the estimate (0.0-1.0)

Type:: float

factors#

Factors considered in the estimation

Type:: list of str

similar_tasks#

IDs of similar historical tasks used for reference

Type:: list of str

risk_multiplier#

Risk adjustment factor (1.0 = no risk, >1.0 = added risk)

Type:: float

Notes

The final estimate should be: estimated_hours * risk_multiplier

estimated_hours: float#

confidence: float#

factors: List[str]#

similar_tasks: List[str]#

risk_multiplier: float#

__init__(estimated_hours, confidence, factors, similar_tasks, risk_multiplier)#

Parameters:

estimated_hours (float)
confidence (float)
factors (List[str])
similar_tasks (List[str])
risk_multiplier (float)

Return type:

None

class src.ai.providers.base_provider.BaseLLMProvider[source]#

Bases: ABC

Base class for LLM providers.

Defines the interface that all LLM providers must implement to integrate with Marcus AI system.

analyze_task(task, context)[source]#

Perform semantic analysis on a task

Parameters:

task (Task)
context (Dict[str, Any])

Return type:

SemanticAnalysis

infer_dependencies(tasks)[source]#

Infer logical dependencies between tasks

Parameters:: tasks (List[Task])
Return type:: List[SemanticDependency]

generate_enhanced_description(task, context)[source]#

Create improved task descriptions

Parameters:

task (Task)
context (Dict[str, Any])

Return type:

str

estimate_effort(task, context)[source]#

Estimate task completion time

Parameters:

task (Task)
context (Dict[str, Any])

Return type:

EffortEstimate

analyze_blocker(task, blocker, context)[source]#

Analyze blockers and suggest solutions

Parameters:

task (Task)
blocker (str)
context (Dict[str, Any])

Return type:

List[str]

Notes

All methods are async to support various LLM APIs. Implementations should handle rate limiting and retries.

Examples

>>> provider = OpenAIProvider(api_key="...")
>>> analysis = await provider.analyze_task(task, context)
>>> print(f"Task intent: {analysis.task_intent}")

abstractmethod async analyze_task(task, context)[source]#

Analyze task semantics using LLM.

Parameters:

task (Task) – Task to analyze
context (Dict[str, Any]) – Project context including related tasks

Returns:

Comprehensive semantic analysis of the task

Return type:

SemanticAnalysis

abstractmethod async infer_dependencies(tasks)[source]#

Infer semantic dependencies between tasks.

Parameters:: tasks (List[Task]) – All tasks to analyze for dependencies
Returns:: Inferred dependency relationships
Return type:: List[SemanticDependency]

Notes

This supplements rule-based dependency detection with semantic understanding of task relationships.

abstractmethod async generate_enhanced_description(task, context)[source]#

Generate enhanced task description.

Parameters:

task (Task) – Task needing description enhancement
context (Dict[str, Any]) – Project context for better understanding

Returns:

Enhanced description with more clarity and detail

Return type:

str

abstractmethod async estimate_effort(task, context)[source]#

Estimate task effort using AI analysis.

Parameters:

task (Task) – Task to estimate
context (Dict[str, Any]) – Historical data and project context

Returns:

AI-powered effort estimation with confidence

Return type:

EffortEstimate

abstractmethod async analyze_blocker(task, blocker, context)[source]#

Analyze blocker and suggest solutions.

Parameters:

task (Task) – The blocked task
blocker (str) – Description of what’s blocking progress
context (Dict[str, Any]) – Additional context about the situation

Returns:

Prioritized list of solution suggestions

Return type:

List[str]