src.ai.types module#

Shared types and data classes for Marcus AI.

This module contains data structures used across multiple AI components to avoid circular imports. These types define the contracts between different parts of the AI system.

Classes#

AnalysisContext: Context data for AI analysis operations
AIInsights: AI-generated insights about tasks and decisions
HybridAnalysis: Combined result of rule-based and AI analysis
RuleBasedResult: Result from deterministic rule-based analysis
AIOptimizationResult: AI-powered optimization suggestions
AssignmentDecision: Final decision on task assignment
AssignmentContext: Full context for assignment decisions

Notes

All dataclasses are frozen where appropriate to ensure immutability of analysis results. Timestamps are automatically added to decisions for audit trails.

class src.ai.types.AnalysisContext[source]#

Bases: object

Context for AI analysis operations.

Provides all necessary information for making intelligent task assignment decisions.

task#

The task being analyzed for assignment

Type:: Task

project_context#

Current project state including available and assigned tasks

Type:: dict

historical_data#

Historical performance and assignment data

Type:: list of dict

team_context#

Team composition and skill information

Type:: dict, optional

constraints#

Project constraints (deadlines, resources, etc.)

Type:: dict, optional

Examples

>>> context = AnalysisContext(
...     task=task_to_assign,
...     project_context={"available_tasks": tasks},
...     historical_data=performance_history
... )

task: Task#

project_context: Dict[str, Any]#

historical_data: List[Dict[str, Any]]#

team_context: Dict[str, Any] | None = None#

constraints: Dict[str, Any] | None = None#

__init__(task, project_context, historical_data, team_context=None, constraints=None)#

Parameters:

task (Task)
project_context (Dict[str, Any])
historical_data (List[Dict[str, Any]])
team_context (Dict[str, Any] | None)
constraints (Dict[str, Any] | None)

Return type:

None

class src.ai.types.AIInsights[source]#

Bases: object

AI-generated insights about a task or decision.

Contains semantic understanding and risk analysis from AI models.

task_intent#

AI’s understanding of what the task aims to achieve

Type:: str

semantic_dependencies#

Inferred dependencies based on task meaning

Type:: list of str

risk_factors#

Identified risks or potential issues

Type:: list of str

suggestions#

AI-generated improvement suggestions

Type:: list of str

confidence#

AI model’s confidence in its analysis (0.0-1.0)

Type:: float

reasoning#

Explanation of AI’s analysis process

Type:: str

risk_assessment#

Detailed risk breakdown by category

Type:: dict

Notes

These insights supplement but never override rule-based decisions.

task_intent: str#

semantic_dependencies: List[str]#

risk_factors: List[str]#

suggestions: List[str]#

confidence: float#

reasoning: str#

risk_assessment: Dict[str, Any]#

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

Parameters:

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

Return type:

None

class src.ai.types.HybridAnalysis[source]#

Bases: object

Result of hybrid rule-based + AI analysis.

Combines deterministic rules with AI enhancement for optimal decisions.

allow_assignment#

Final decision on whether to allow task assignment

Type:: bool

confidence#

Combined confidence score (0.0-1.0)

Type:: float

reason#

Human-readable explanation of the decision

Type:: str

safety_critical#

Whether safety rules were involved in decision

Type:: bool

ai_confidence#

AI model’s confidence if AI was used

Type:: float, optional

ai_insights#

Detailed AI analysis if available

Type:: AIInsights, optional

fallback_mode#

Whether system fell back to rules-only mode

Type:: bool

confidence_breakdown#

Component confidence scores and weights

Type:: dict, optional

optimization_score#

AI’s optimization score for this assignment

Type:: float, optional

Examples

>>> result = HybridAnalysis(
...     allow_assignment=True,
...     confidence=0.85,
...     reason="All checks passed with high confidence"
... )

allow_assignment: bool#

confidence: float#

reason: str#

safety_critical: bool = False#

ai_confidence: float | None = None#

ai_insights: AIInsights | None = None#

fallback_mode: bool = False#

confidence_breakdown: Dict[str, float] | None = None#

optimization_score: float | None = None#

__init__(allow_assignment, confidence, reason, safety_critical=False, ai_confidence=None, ai_insights=None, fallback_mode=False, confidence_breakdown=None, optimization_score=None)#

Parameters:

allow_assignment (bool)
confidence (float)
reason (str)
safety_critical (bool)
ai_confidence (float | None)
ai_insights (AIInsights | None)
fallback_mode (bool)
confidence_breakdown (Dict[str, float] | None)
optimization_score (float | None)

Return type:

None

class src.ai.types.RuleBasedResult[source]#

Bases: object

Result from rule-based analysis.

Represents deterministic validation results that provide safety guarantees.

is_valid#

Whether the assignment passes all rules

Type:: bool

confidence#

Rule engine confidence (typically high: 0.8-1.0)

Type:: float

reason#

Explanation of the validation result

Type:: str

safety_critical#

Whether this involves safety-critical rules

Type:: bool

mandatory#

Whether this rule cannot be overridden

Type:: bool

Notes

When mandatory=True, the decision cannot be changed by AI.

is_valid: bool#

confidence: float#

reason: str#

safety_critical: bool = False#

mandatory: bool = False#

__init__(is_valid, confidence, reason, safety_critical=False, mandatory=False)#

Parameters:

is_valid (bool)
confidence (float)
reason (str)
safety_critical (bool)
mandatory (bool)

Return type:

None

class src.ai.types.AIOptimizationResult[source]#

Bases: object

Result of AI optimization analysis.

Contains AI-powered suggestions for optimizing task execution.

confidence#

AI’s confidence in optimization suggestions (0.0-1.0)

Type:: float

optimization_score#

Score indicating assignment quality (0.0-1.0)

Type:: float

improvements#

Suggested improvements for task execution

Type:: list of str

semantic_confidence#

Confidence in semantic understanding

Type:: float, optional

risk_mitigation#

Strategies to mitigate identified risks

Type:: list of str, optional

estimated_completion_time#

AI estimate of task duration in hours

Type:: float, optional

confidence: float#

optimization_score: float#

improvements: List[str]#

semantic_confidence: float | None = None#

risk_mitigation: List[str] | None = None#

estimated_completion_time: float | None = None#

__init__(confidence, optimization_score, improvements, semantic_confidence=None, risk_mitigation=None, estimated_completion_time=None)#

Parameters:

confidence (float)
optimization_score (float)
improvements (List[str])
semantic_confidence (float | None)
risk_mitigation (List[str] | None)
estimated_completion_time (float | None)

Return type:

None

class src.ai.types.AssignmentDecision[source]#

Bases: object

Final decision on task assignment.

Represents the complete decision including rule validation, AI enhancement, and audit information.

allow#

Whether to allow the assignment

Type:: bool

confidence#

Overall confidence in decision (0.0-1.0)

Type:: float

reason#

Primary reason for the decision

Type:: str

ai_suggestions#

AI optimization suggestions if rules passed

Type:: AIOptimizationResult, optional

optimization_score#

AI’s score for assignment quality

Type:: float, optional

confidence_breakdown#

Detailed confidence components

Type:: dict, optional

safety_critical#

Whether safety rules were involved

Type:: bool

mandatory_rule_applied#

Whether mandatory rules were applied

Type:: bool

timestamp#

When the decision was made (auto-set)

Type:: datetime

__post_init__()[source]#

Automatically sets timestamp if not provided

Return type:: None

Examples

>>> decision = AssignmentDecision(
...     allow=True,
...     confidence=0.92,
...     reason="All validations passed"
... )
>>> print(f"Decision at {decision.timestamp}: {decision.allow}")

allow: bool#

confidence: float#

reason: str#

ai_suggestions: AIOptimizationResult | None = None#

optimization_score: float | None = None#

confidence_breakdown: Dict[str, float] | None = None#

safety_critical: bool = False#

mandatory_rule_applied: bool = False#

timestamp: datetime | None = None#

__post_init__()[source]#

Set timestamp if not provided.

Return type:: None

__init__(allow, confidence, reason, ai_suggestions=None, optimization_score=None, confidence_breakdown=None, safety_critical=False, mandatory_rule_applied=False, timestamp=None)#

Parameters:

allow (bool)
confidence (float)
reason (str)
ai_suggestions (AIOptimizationResult | None)
optimization_score (float | None)
confidence_breakdown (Dict[str, float] | None)
safety_critical (bool)
mandatory_rule_applied (bool)
timestamp (datetime | None)

Return type:

None

class src.ai.types.AssignmentContext[source]#

Bases: object

Context for assignment decision.

Complete context needed to make informed assignment decisions.

task#

Task being considered for assignment

Type:: Task

agent_id#

ID of agent to potentially assign to

Type:: str

agent_status#

Current status and workload of the agent

Type:: dict

available_tasks#

All unassigned tasks in the project

Type:: list of Task

project_context#

Project metadata and configuration

Type:: dict

team_status#

Status of all team members and assignments

Type:: dict

Notes

This context is passed through the entire decision pipeline to ensure all components have necessary information.

task: Task#

agent_id: str#

agent_status: Dict[str, Any]#

available_tasks: List[Task]#

project_context: Dict[str, Any]#

team_status: Dict[str, Any]#

__init__(task, agent_id, agent_status, available_tasks, project_context, team_status)#

Parameters:

task (Task)
agent_id (str)
agent_status (Dict[str, Any])
available_tasks (List[Task])
project_context (Dict[str, Any])
team_status (Dict[str, Any])

Return type:

None