forgex-cli 0.1.0__py3-none-any.whl

forgex/schemas/__init__.py

@@ -0,0 +1,101 @@
+"""Pydantic schemas and the FORGEX error taxonomy."""
+
+from forgex.schemas.agent import (
+    AgentRole,
+    BuilderResult,
+    ExpertCoderResult,
+    ReviewFinding,
+    ReviewFindings,
+    SupervisorJudgment,
+    SupervisorReport,
+)
+from forgex.schemas.checkpoint import CheckpointRecord
+from forgex.schemas.error import (
+    AgentOutputError,
+    AuthenticationError,
+    BuildError,
+    CommandDeniedError,
+    ConfigError,
+    ErrorRecord,
+    FileSystemError,
+    ForgexError,
+    GitError,
+    PathViolationError,
+    ProjectError,
+    ProviderError,
+    RateLimitError,
+    SandboxError,
+    StorageError,
+    TaskGraphError,
+    TestError,
+    ToolError,
+    WorkflowError,
+)
+from forgex.schemas.event import Event, EventType
+from forgex.schemas.plan import (
+    AnalysisResult,
+    ArchitectResult,
+    ArchitecturePlan,
+    TaskSpec,
+    specs_to_tasks,
+)
+from forgex.schemas.project import ProjectState, RunState, RunStatus, WorkflowStatus
+from forgex.schemas.research import ResearchNote
+from forgex.schemas.result import (
+    BuildResults,
+    CommandOutcome,
+    ModelUsageRecord,
+    TestResults,
+    VerificationOutcome,
+)
+from forgex.schemas.task import Task, TaskPriority, TaskStatus
+
+__all__ = [
+    "AgentOutputError",
+    "AgentRole",
+    "AnalysisResult",
+    "ArchitectResult",
+    "ArchitecturePlan",
+    "AuthenticationError",
+    "BuildError",
+    "BuildResults",
+    "BuilderResult",
+    "CheckpointRecord",
+    "CommandDeniedError",
+    "CommandOutcome",
+    "ConfigError",
+    "ErrorRecord",
+    "Event",
+    "EventType",
+    "ExpertCoderResult",
+    "FileSystemError",
+    "ForgexError",
+    "GitError",
+    "ModelUsageRecord",
+    "PathViolationError",
+    "ProjectError",
+    "ProjectState",
+    "ProviderError",
+    "RateLimitError",
+    "ResearchNote",
+    "ReviewFinding",
+    "ReviewFindings",
+    "RunState",
+    "RunStatus",
+    "SandboxError",
+    "StorageError",
+    "SupervisorJudgment",
+    "SupervisorReport",
+    "Task",
+    "TaskGraphError",
+    "TaskPriority",
+    "TaskSpec",
+    "TaskStatus",
+    "TestError",
+    "TestResults",
+    "ToolError",
+    "VerificationOutcome",
+    "WorkflowError",
+    "WorkflowStatus",
+    "specs_to_tasks",
+]

forgex/schemas/agent.py

@@ -0,0 +1,109 @@
+"""Agent identity, roles, and agent output schemas."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from forgex.schemas.plan import ArchitectResult as ArchitectResult
+
+
+class AgentRole(str, Enum):
+    ARCHITECT = "architect"
+    BUILDER = "builder"
+    EXPERT_CODER = "expert_coder"
+    SUPERVISOR = "supervisor"
+
+    @property
+    def display_name(self) -> str:
+        return self.value.replace("_", " ").title()
+
+
+class BuilderResult(BaseModel):
+    """The Builder's structured self-report after executing one task (§9).
+
+    NOTE: 'completed' is the Builder's own claim — independent verification
+    is the Supervisor's responsibility (Phase 8) and the repair loop (Phase 9).
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    status: Literal["completed", "failed"]
+    summary: str = ""
+    changed_files: list[str] = Field(default_factory=list)
+    issues: list[str] = Field(default_factory=list)
+
+
+class ExpertCoderResult(BaseModel):
+    """The Expert Coder's structured review report (spec section 10).
+
+    Empty changed_files is a valid outcome: 'reviewed, nothing warranted
+    changes'. unfixed_issues are handed forward to the Supervisor (Phase 8).
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    status: Literal["completed", "failed"]
+    summary: str = ""
+    changed_files: list[str] = Field(default_factory=list)
+    improvements: list[str] = Field(default_factory=list)
+    issues_found: list[str] = Field(default_factory=list)
+    unfixed_issues: list[str] = Field(default_factory=list)
+
+
+class ReviewFinding(BaseModel):
+    """One issue found by an ensemble reviewer (spec section 15)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    issue: str
+    severity: Literal["critical", "major", "minor"] = "major"
+    file: str | None = None
+    suggestion: str | None = None
+
+
+class ReviewFindings(BaseModel):
+    """One reviewer's read-only verdict on a diff."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    verdict: Literal["ok", "needs_changes"]
+    summary: str = ""
+    findings: list[ReviewFinding] = Field(default_factory=list)
+
+
+class SupervisorJudgment(BaseModel):
+    """The LLM Supervisor's verdict (spec section 11 output)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    status: Literal["pass", "fail", "needs_review"]
+    summary: str = ""
+    errors: list[str] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    required_changes: list[str] = Field(default_factory=list)
+    recommended_changes: list[str] = Field(default_factory=list)
+
+
+class SupervisorReport(BaseModel):
+    """Final supervisor verdict: LLM judgment + deterministic quality gates.
+
+    Gates can only WORSEN a verdict, never improve it (spec sections 56, 58):
+    a red test suite forces 'fail' regardless of the model's opinion."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    status: Literal["pass", "fail", "needs_review"]
+    summary: str = ""
+    errors: list[str] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    required_changes: list[str] = Field(default_factory=list)
+    recommended_changes: list[str] = Field(default_factory=list)
+    tests: Any | None = None
+    build: Any | None = None
+    lint: Any | None = None
+
+
+SupervisorReport.model_rebuild()

forgex/schemas/checkpoint.py

@@ -0,0 +1,19 @@
+"""Checkpoint metadata (spec section 21)."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class CheckpointRecord(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    project_id: str
+    label: str
+    git_commit: str | None = None
+    description: str | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    run_id: str | None = None

forgex/schemas/error.py

@@ -0,0 +1,125 @@
+"""FORGEX error taxonomy and the persisted error record (spec sections 5, 25, 28).
+
+All controlled failures derive from :class:`ForgexError` so the CLI can
+render friendly messages and keep raw stack traces behind ``--debug``.
+Exit codes are stable per error class.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from typer._click import ClickException
+
+
+class ForgexError(ClickException):
+    """Base class for all controlled FORGEX errors."""
+
+    exit_code: int = 1
+
+    def __init__(self, message: str = "") -> None:
+        super().__init__(message)
+
+
+class ConfigError(ForgexError):
+    exit_code = 2
+
+
+class FileSystemError(ForgexError):
+    exit_code = 3
+
+
+class ProjectError(ForgexError):
+    exit_code = 4
+
+
+class ProviderError(ForgexError):
+    """Provider-level failure. `retryable` drives the retry policy (§29);
+    `attempts` records how many attempts were made (§40)."""
+
+    exit_code = 5
+    default_retryable: bool = False
+    attempts: int = 1
+
+    def __init__(self, message: str, *, retryable: bool | None = None, attempts: int = 1) -> None:
+        super().__init__(message)
+        self.retryable = self.default_retryable if retryable is None else retryable
+        self.attempts = attempts
+
+
+class AuthenticationError(ProviderError):
+    exit_code = 6
+    default_retryable = False
+
+
+class RateLimitError(ProviderError):
+    exit_code = 7
+    default_retryable = True
+
+
+class ToolError(ForgexError):
+    exit_code = 8
+
+
+class PermissionDeniedError(ToolError):
+    """An agent attempted an action outside its permission set."""
+    exit_code = 8
+
+
+class SandboxError(ForgexError):
+    exit_code = 9
+
+
+class CommandDeniedError(SandboxError):
+    """A command was blocked by policy or not approved (spec sections 19, 33)."""
+    exit_code = 9
+
+
+class GitError(ForgexError):
+    exit_code = 10
+
+
+class BuildError(ForgexError):
+    exit_code = 11
+
+
+class TestError(ForgexError):
+    exit_code = 12
+
+
+class WorkflowError(ForgexError):
+    exit_code = 14
+
+
+class TaskGraphError(ForgexError):
+    exit_code = 15
+
+
+class StorageError(ForgexError):
+    exit_code = 16
+
+
+class AgentOutputError(ForgexError):
+    """An agent could not produce valid structured output (spec sections 7, 28)."""
+    exit_code = 17
+
+
+class PathViolationError(FileSystemError):
+    """A path attempted to escape the authorized workspace."""
+    exit_code = 3
+
+
+class ErrorRecord(BaseModel):
+    """Persisted error record for state and history."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    ts: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    source: str
+    kind: str
+    message: str
+    run_id: str | None = None
+    detail: dict[str, Any] | None = None

forgex/schemas/event.py

@@ -0,0 +1,76 @@
+"""Event schema (spec section 24).
+
+On-disk format (.forgex/events.jsonl), one JSON object per line:
+
+    {"ts": "<iso-8601 utc>", "type": "<EventType>", "run_id": null, "data": {...}}
+
+Introduced in Phase 1; ``run_id`` added in Phase 2 (readers tolerate its
+absence). This format is FROZEN — treat it as a public contract.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class EventType(str, Enum):
+    PROJECT_INITIALIZED = "ProjectInitialized"
+    RUN_STARTED = "RunStarted"
+    RUN_COMPLETED = "RunCompleted"
+    RUN_FAILED = "RunFailed"
+    AGENT_STARTED = "AgentStarted"
+    AGENT_THINKING = "AgentThinking"
+    AGENT_COMPLETED = "AgentCompleted"
+    TOOL_STARTED = "ToolStarted"
+    TOOL_COMPLETED = "ToolCompleted"
+    FILE_CHANGED = "FileChanged"
+    TASK_STARTED = "TaskStarted"
+    TASK_COMPLETED = "TaskCompleted"
+    TEST_STARTED = "TestStarted"
+    TEST_COMPLETED = "TestCompleted"
+    SUPERVISOR_STARTED = "SupervisorStarted"
+    REPAIR_STARTED = "RepairStarted"
+    RESEARCH_COMPLETED = "ResearchCompleted"
+    PLAN_CREATED = "PlanCreated"
+    CHECKPOINT_CREATED = "CheckpointCreated"
+    CHECKPOINT_ROLLED_BACK = "CheckpointRolledBack"
+    ENSEMBLE_COMPLETED = "EnsembleCompleted"
+    INTERRUPTED = "Interrupted"
+
+
+class Event(BaseModel):
+    """One immutable event in the FORGEX observability stream."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    ts: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    type: EventType
+    data: dict[str, Any] = Field(default_factory=dict)
+    run_id: str | None = None
+
+    def to_jsonl(self) -> str:
+        return json.dumps(
+            {
+                "ts": self.ts.isoformat(),
+                "type": self.type.value,
+                "run_id": self.run_id,
+                "data": self.data,
+            },
+            default=str,
+        )
+
+    @classmethod
+    def from_jsonl(cls, line: str) -> Event:
+        """Parse one JSONL line. Raises ValueError/KeyError on malformed input."""
+        raw = json.loads(line)
+        return cls(
+            ts=datetime.fromisoformat(raw["ts"]),
+            type=EventType(raw["type"]),
+            run_id=raw.get("run_id"),
+            data=raw.get("data") or {},
+        )

forgex/schemas/plan.py

@@ -0,0 +1,84 @@
+"""Planning schemas (spec sections 7, 8, 54).
+
+The Architect's structured outputs. `AnalysisResult` is the early
+understanding pass; `ArchitecturePlan` is the final plan persisted to
+state.json. `TaskSpec` is the plan-side task; `specs_to_tasks()` converts
+specs into runtime Task objects for the task store.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from forgex.schemas.research import ResearchNote
+from forgex.schemas.task import Task, TaskPriority
+
+
+class TaskSpec(BaseModel):
+    """A task as planned by the Architect (no runtime state)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    description: str
+    priority: TaskPriority = TaskPriority.MEDIUM
+    depends_on: list[str] = Field(default_factory=list)
+    files: list[str] = Field(default_factory=list)
+    acceptance_criteria: list[str] = Field(default_factory=list)
+
+
+class AnalysisResult(BaseModel):
+    """Stage 1: the Architect's understanding before research."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    goal: str
+    requirements: list[str] = Field(default_factory=list)
+    candidate_libraries: list[str] = Field(default_factory=list)
+    research_topics: list[str] = Field(default_factory=list)
+
+
+class ArchitecturePlan(BaseModel):
+    """Stage 2: the final implementation plan (spec section 7)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    goal: str
+    requirements: list[str] = Field(default_factory=list)
+    tasks: list[TaskSpec] = Field(default_factory=list)
+    dependencies: list[str] = Field(default_factory=list)  # external systems/services
+    libraries: list[str] = Field(default_factory=list)  # language packages
+    architecture: dict[str, Any] = Field(default_factory=dict)
+    risks: list[str] = Field(default_factory=list)
+    acceptance_criteria: list[str] = Field(default_factory=list)
+    test_strategy: list[str] = Field(default_factory=list)
+
+
+class ArchitectResult(BaseModel):
+    """Everything the Architect produces in one planning run."""
+
+    plan: ArchitecturePlan
+    research: list[ResearchNote] = Field(default_factory=list)
+    analysis: AnalysisResult | None = None
+    prompt_version: str = "architect:v1"
+
+
+def specs_to_tasks(specs: list[TaskSpec]) -> list[Task]:
+    """Convert planned task specs into runtime Task objects (pending, attempt 0)."""
+    now = datetime.now(UTC)
+    return [
+        Task(
+            id=spec.id,
+            description=spec.description,
+            priority=spec.priority,
+            depends_on=list(spec.depends_on),
+            files=list(spec.files),
+            acceptance_criteria=list(spec.acceptance_criteria),
+            created_at=now,
+            updated_at=now,
+        )
+        for spec in specs
+    ]

forgex/schemas/project.py

@@ -0,0 +1,92 @@
+"""Project and run state (spec sections 5, 53).
+
+ProjectState is THE central shared object: agents read and write
+structured state instead of giant conversations (spec section 2.7).
+WorkflowStatus is the phase machine from spec section 53; the transition
+RULES live in forgex.orchestration.workflow.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from forgex.schemas.agent import AgentRole
+from forgex.schemas.error import ErrorRecord
+from forgex.schemas.plan import ArchitecturePlan
+from forgex.schemas.research import ResearchNote
+from forgex.schemas.result import BuildResults, TestResults
+
+
+class WorkflowStatus(str, Enum):
+    INITIALIZING = "initializing"
+    ANALYZING = "analyzing"
+    RESEARCHING = "researching"
+    PLANNING = "planning"
+    BUILDING = "building"
+    REVIEWING = "reviewing"
+    TESTING = "testing"
+    SUPERVISING = "supervising"
+    REPAIRING = "repairing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class RunStatus(str, Enum):
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class RunState(BaseModel):
+    """Execution run record persisted to database."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    run_id: str
+    project_id: str
+    request: str
+    status: RunStatus = RunStatus.RUNNING
+    phase: WorkflowStatus = WorkflowStatus.INITIALIZING
+    iteration: int = 0
+    started_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    finished_at: datetime | None = None
+    summary: str | None = None
+    error: str | None = None
+
+
+class ProjectState(BaseModel):
+    """Durable project state, persisted to .forgex/state.json (spec section 5)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: int = 1
+    project_id: str
+    project_path: str
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    user_request: str | None = None
+    status: WorkflowStatus = WorkflowStatus.INITIALIZING
+    iteration: int = 0
+    current_run_id: str | None = None
+    current_agent: AgentRole | None = None
+    current_task: str | None = None
+    git_commit: str | None = None
+
+    architecture_plan: ArchitecturePlan | None = None
+    research: list[ResearchNote] = Field(default_factory=list)
+    changed_files: list[str] = Field(default_factory=list)
+    tasks: list[str] = Field(default_factory=list)
+    completed_tasks: list[str] = Field(default_factory=list)
+    failed_tasks: list[str] = Field(default_factory=list)
+    errors: list[ErrorRecord] = Field(default_factory=list)
+
+    test_results: TestResults | None = None
+    build_results: BuildResults | None = None
+    last_supervisor_status: Literal["pass", "fail", "needs_review"] | None = None

forgex/schemas/research.py

@@ -0,0 +1,25 @@
+"""Research metadata (spec section 8).
+
+Research never invents facts: every note records where it came from and
+when it was checked — or is explicitly marked unavailable.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ResearchNote(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    topic: str
+    source: str  # "pypi" | "npm" | "crates" | "go" | "none"
+    summary: str
+    version: str | None = None
+    checked_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    confidence: Literal["high", "medium", "low"] = "medium"
+    available: bool = True
+    detail: str | None = None  # registry URL, or the unavailability reason

forgex/schemas/result.py

@@ -0,0 +1,68 @@
+"""Result schemas — model usage records and command verification outcomes (spec sections 40, 41, 56).
+
+Token counts are stored exactly as reported by the provider. When usage
+is not reported, values stay None — never fabricated (spec section 41).
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelUsageRecord(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    ts: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    run_id: str | None = None
+    agent: str
+    provider: str
+    model: str
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    total_tokens: int | None = None
+    latency_ms: float | None = None
+    attempts: int = 1
+    success: bool = True
+    error: str | None = None
+
+
+class CommandOutcome(BaseModel):
+    """One executed command's outcome (tests/build/lint). `output_tail` is the
+    last few KB — not the full stream (spec section 16)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    command: list[str] = Field(default_factory=list)
+    exit_code: int | None = None  # None = never ran (denied by policy)
+    timed_out: bool = False
+    duration_ms: float | None = None
+    output_tail: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0 and not self.timed_out
+
+
+class TestResults(CommandOutcome):
+    """Test suite outcome. Counts are parsed when the runner reports them;
+    None = unknown — never fabricated (spec section 41)."""
+
+    __test__ = False
+
+    passed: int | None = None
+    failed: int | None = None
+    errors: int | None = None
+
+
+class BuildResults(CommandOutcome):
+    """Build outcome (compile/packaging step, where applicable)."""
+
+
+class VerificationOutcome(BaseModel):
+    """Deterministic verification results (spec sections 11, 56)."""
+
+    tests: TestResults | None = None
+    build: BuildResults | None = None
+    lint: CommandOutcome | None = None