Component: Code Agent Data Models (7 models)
Module: gaia.agents.code.models
Import: from gaia.agents.code.models import CodeSymbol, ParsedCode, ProjectPlan, ValidationResult, ExecutionResult, ProjectStructure, WorkflowPlan
Overview
Complete data model definitions for the Code Agent system. These dataclasses provide type-safe interfaces for code analysis, project planning, validation, execution, and workflow management.
API Specification
1. CodeSymbol
@dataclass
class CodeSymbol:
"""Represents a code symbol (function, class, variable)."""
name: str
type: str # 'function', 'class', 'variable', 'import'
line: int
docstring: Optional[str] = None
signature: Optional[str] = None
2. ParsedCode
@dataclass
class ParsedCode:
"""Result of parsing Python code."""
ast_tree: Optional[ast.Module] = None
symbols: List[CodeSymbol] = field(default_factory=list)
imports: List[str] = field(default_factory=list)
errors: List[str] = field(default_factory=list)
is_valid: bool = False
3. ProjectPlan
@dataclass
class ModuleSpec:
"""Specification for a module in a project."""
name: str
purpose: str
classes: List[Dict[str, Any]] = field(default_factory=list)
functions: List[Dict[str, Any]] = field(default_factory=list)
@dataclass
class TestSpec:
"""Specification for a test module."""
name: str
coverage: str
test_cases: List[str] = field(default_factory=list)
@dataclass
class ProjectPlan:
"""Complete project plan with architecture and modules."""
name: str
architecture: Dict[str, Any]
modules: List[ModuleSpec]
tests: List[TestSpec]
description: str = ""
project_type: str = "application"
4. ValidationResult
@dataclass
class ValidationResult:
"""Result of code validation."""
is_valid: bool
errors: List[str] = field(default_factory=list)
warnings: List[str] = field(default_factory=list)
fixes_applied: List[str] = field(default_factory=list)
file_modified: bool = False
5. ExecutionResult
@dataclass
class ExecutionResult:
"""Result of executing Python code."""
stdout: str
stderr: str
return_code: int
has_errors: bool
duration_seconds: float
timed_out: bool = False
file_path: Optional[str] = None
command: Optional[str] = None
6. ProjectStructure
@dataclass
class ProjectStructure:
"""Represents a complete project structure."""
name: str
files: Dict[str, str] # filename -> content
structure: Dict[str, Any] # nested directory structure
plan: Optional[ProjectPlan] = None
7. WorkflowPlan
@dataclass
class WorkflowPlan:
"""Plan for executing a coding workflow."""
query: str
steps: List[Dict[str, Any]]
current_step: int = 0
completed_steps: List[int] = field(default_factory=list)
status: str = "pending" # pending, in_progress, completed, failed
Usage Examples
from gaia.agents.code.models import CodeSymbol, ParsedCode
# Parse Python code
code = '''
def calculate(x: int, y: int) -> int:
"""Add two numbers."""
return x + y
class Calculator:
"""Simple calculator."""
pass
'''
# Create parsed result
parsed = ParsedCode(
is_valid=True,
symbols=[
CodeSymbol(
name="calculate",
type="function",
line=1,
docstring="Add two numbers.",
signature="calculate(x: int, y: int) -> int"
),
CodeSymbol(
name="Calculator",
type="class",
line=5,
docstring="Simple calculator."
)
],
imports=[]
)
print(f"Found {len(parsed.symbols)} symbols")
Example 2: Validation Workflow
from gaia.agents.code.models import ValidationResult
# Validate generated code
result = ValidationResult(
is_valid=False,
errors=["SyntaxError: invalid syntax at line 10"],
warnings=["Missing docstring in function 'helper'"],
fixes_applied=["Added missing import statement"],
file_modified=True
)
if not result.is_valid:
print(f"Validation failed: {result.errors}")
if result.file_modified:
print("Code was automatically fixed")
Example 3: Project Creation
from gaia.agents.code.models import ProjectPlan, ModuleSpec, TestSpec
# Create project plan
plan = ProjectPlan(
name="todo-app",
description="Simple TODO application",
project_type="web",
architecture={
"pattern": "MVC",
"database": "SQLite",
"frontend": "HTML/CSS"
},
modules=[
ModuleSpec(
name="models",
purpose="Data models",
classes=[{"name": "Todo", "fields": ["title", "done"]}]
)
],
tests=[
TestSpec(
name="test_models",
coverage="models",
test_cases=["test_create_todo", "test_mark_done"]
)
]
)
Testing Requirements
def test_code_symbol_creation():
"""Test CodeSymbol dataclass."""
symbol = CodeSymbol(
name="test_func",
type="function",
line=1,
docstring="Test function"
)
assert symbol.name == "test_func"
assert symbol.type == "function"
def test_validation_result():
"""Test ValidationResult dataclass."""
result = ValidationResult(
is_valid=True,
errors=[],
warnings=["Style warning"]
)
assert result.is_valid
assert len(result.warnings) == 1
def test_execution_result():
"""Test ExecutionResult dataclass."""
result = ExecutionResult(
stdout="Hello World",
stderr="",
return_code=0,
has_errors=False,
duration_seconds=0.5
)
assert result.return_code == 0
assert not result.has_errors
Dependencies
[project]
dependencies = [
"dataclasses", # Python 3.7+
"typing",
]
Acceptance Criteria
Code Agent Models Technical Specification