devcouncil 0.1.0

package/src/devcouncil/storage/db.py

@@ -0,0 +1,66 @@
+from contextlib import contextmanager
+
+from sqlmodel import SQLModel, create_engine, Session
+from sqlalchemy.exc import OperationalError
+from pathlib import Path
+from typing import Optional
+
+from devcouncil.storage.models import SchemaVersionModel
+
+
+SCHEMA_VERSION = 1
+
+
+class Database:
+    def __init__(self, db_path: Path):
+        self.db_path = db_path
+        self.engine = create_engine(f"sqlite:///{db_path}")
+
+    def create_db_and_tables(self):
+        self._create_tables()
+        self.ensure_schema_version()
+
+    def ensure_schema_version(self):
+        self._create_tables()
+        with Session(self.engine) as session:
+            current = session.get(SchemaVersionModel, "singleton")
+            if current is None:
+                session.add(SchemaVersionModel(id="singleton", version=SCHEMA_VERSION))
+                session.commit()
+                return
+            if current.version != SCHEMA_VERSION:
+                raise RuntimeError(
+                    f"Unsupported DevCouncil schema version {current.version}; "
+                    f"expected {SCHEMA_VERSION}."
+                )
+
+    def _create_tables(self):
+        try:
+            SQLModel.metadata.create_all(self.engine)
+        except OperationalError as exc:
+            if "already exists" not in str(exc):
+                raise
+
+    @contextmanager
+    def get_session(self):
+        """Yield a session with automatic commit/rollback/close."""
+        session = Session(self.engine)
+        try:
+            yield session
+            session.commit()
+        except Exception:
+            session.rollback()
+            raise
+        finally:
+            session.close()
+
+
+def get_db(project_root: Path = Path(".")) -> Optional[Database]:
+    dev_dir = project_root / ".devcouncil"
+    if not dev_dir.exists():
+        return None
+    
+    db_path = dev_dir / "state.sqlite"
+    db = Database(db_path)
+    db.ensure_schema_version()
+    return db

package/src/devcouncil/storage/models.py

@@ -0,0 +1,83 @@
+from sqlmodel import SQLModel, Field
+from typing import Optional
+
+
+class SchemaVersionModel(SQLModel, table=True):
+    __tablename__ = "schema_version"
+    id: str = Field(primary_key=True, default="singleton")
+    version: int
+
+class RequirementModel(SQLModel, table=True):
+    __tablename__ = "requirements"
+    id: str = Field(primary_key=True)
+    title: str
+    description: str
+    priority: str
+    source: str
+    # Store complex lists as JSON strings for simplicity in SQLite
+    acceptance_criteria_json: str = Field(default="[]")
+
+class AssumptionModel(SQLModel, table=True):
+    __tablename__ = "assumptions"
+    id: str = Field(primary_key=True)
+    statement: str
+    confidence: str
+    impact: str
+    reversible: bool
+    requires_user_confirmation: bool
+    linked_requirement_ids_json: str = Field(default="[]")
+    status: str = "open"
+
+class TaskModel(SQLModel, table=True):
+    __tablename__ = "tasks"
+    id: str = Field(primary_key=True)
+    title: str
+    description: str
+    requirement_ids_json: str = Field(default="[]")
+    acceptance_criterion_ids_json: str = Field(default="[]")
+    planned_files_json: str = Field(default="[]")
+    expected_tests_json: str = Field(default="[]")
+    allowed_commands_json: str = Field(default="[]")
+    forbidden_changes_json: str = Field(default="[]")
+    status: str = "planned"
+
+class EvidenceModel(SQLModel, table=True):
+    __tablename__ = "evidence"
+    id: Optional[int] = Field(default=None, primary_key=True)
+    type: str  # "command", "diff", "test"
+    task_id: Optional[str] = None
+    requirement_id: Optional[str] = None
+    acceptance_criterion_id: Optional[str] = None
+    data_json: str
+
+class GapModel(SQLModel, table=True):
+    __tablename__ = "gaps"
+    id: str = Field(primary_key=True)
+    severity: str
+    gap_type: str
+    requirement_id: Optional[str] = None
+    task_id: Optional[str] = None
+    description: str
+    evidence_json: str = Field(default="[]")
+    recommended_fix: str
+    blocking: bool
+
+class CritiqueFindingModel(SQLModel, table=True):
+    __tablename__ = "critique_findings"
+    id: str = Field(primary_key=True)
+    source_agent: str
+    target_plan_id: str
+    severity: str
+    finding_type: str
+    claim: str
+    linked_requirement_id: Optional[str] = None
+    suggested_requirement: Optional[str] = None
+    suggested_task: Optional[str] = None
+    falsifiable_check: str
+    status: str = "open"
+
+class ProjectStateModel(SQLModel, table=True):
+    __tablename__ = "project_state"
+    id: str = Field(primary_key=True, default="singleton")
+    current_phase: str
+    history_json: str = Field(default="[]")

package/src/devcouncil/storage/repositories.py

@@ -0,0 +1,346 @@
+from sqlmodel import Session, select, delete
+from typing import List, Optional, Any
+import json
+from devcouncil.storage.models import (
+    RequirementModel,
+    AssumptionModel,
+    TaskModel,
+    GapModel,
+    EvidenceModel,
+    CritiqueFindingModel,
+    ProjectStateModel,
+)
+from devcouncil.domain.requirement import Requirement, AcceptanceCriterion
+from devcouncil.domain.assumption import Assumption
+from devcouncil.domain.task import Task, PlannedFile
+from devcouncil.domain.gap import Gap
+from devcouncil.domain.evidence import CommandResult, DiffEvidence, TestEvidence
+from devcouncil.domain.critique import CritiqueFinding
+from devcouncil.artifacts.graph import ArtifactGraph
+
+class RequirementRepository:
+    def __init__(self, session: Session):
+        self.session = session
+
+    def get_all(self) -> List[Requirement]:
+        statement = select(RequirementModel)
+        models = self.session.exec(statement).all()
+        results = []
+        for m in models:
+            ac_list = [AcceptanceCriterion.model_validate(ac) for ac in json.loads(m.acceptance_criteria_json)]
+            results.append(Requirement(
+                id=m.id,
+                title=m.title,
+                description=m.description,
+                priority=m.priority,
+                source=m.source,
+                acceptance_criteria=ac_list
+            ))
+        return results
+
+    def save(self, req: Requirement):
+        model = RequirementModel(
+            id=req.id,
+            title=req.title,
+            description=req.description,
+            priority=req.priority,
+            source=req.source,
+            acceptance_criteria_json=json.dumps([ac.model_dump() for ac in req.acceptance_criteria])
+        )
+        self.session.merge(model)
+        self.session.commit()
+
+
+class AssumptionRepository:
+    def __init__(self, session: Session):
+        self.session = session
+
+    def get_all(self) -> List[Assumption]:
+        statement = select(AssumptionModel)
+        models = self.session.exec(statement).all()
+        return [
+            Assumption(
+                id=m.id,
+                statement=m.statement,
+                confidence=m.confidence,
+                impact=m.impact,
+                reversible=m.reversible,
+                requires_user_confirmation=m.requires_user_confirmation,
+                linked_requirement_ids=json.loads(m.linked_requirement_ids_json),
+                status=m.status,
+            )
+            for m in models
+        ]
+
+    def save(self, assumption: Assumption):
+        model = AssumptionModel(
+            id=assumption.id,
+            statement=assumption.statement,
+            confidence=assumption.confidence,
+            impact=assumption.impact,
+            reversible=assumption.reversible,
+            requires_user_confirmation=assumption.requires_user_confirmation,
+            linked_requirement_ids_json=json.dumps(assumption.linked_requirement_ids),
+            status=assumption.status,
+        )
+        self.session.merge(model)
+        self.session.commit()
+
+class TaskRepository:
+    def __init__(self, session: Session):
+        self.session = session
+
+    def get_by_id(self, task_id: str) -> Optional[Task]:
+        statement = select(TaskModel).where(TaskModel.id == task_id)
+        m = self.session.exec(statement).first()
+        if not m:
+            return None
+        
+        pf_list = [PlannedFile.model_validate(pf) for pf in json.loads(m.planned_files_json)]
+        return Task(
+            id=m.id,
+            title=m.title,
+            description=m.description,
+            requirement_ids=json.loads(m.requirement_ids_json),
+            acceptance_criterion_ids=json.loads(m.acceptance_criterion_ids_json),
+            planned_files=pf_list,
+            expected_tests=json.loads(m.expected_tests_json),
+            allowed_commands=json.loads(m.allowed_commands_json),
+            forbidden_changes=json.loads(m.forbidden_changes_json),
+            status=m.status
+        )
+
+    def get_all(self) -> List[Task]:
+        statement = select(TaskModel)
+        models = self.session.exec(statement).all()
+        results = []
+        for m in models:
+            pf_list = [PlannedFile.model_validate(pf) for pf in json.loads(m.planned_files_json)]
+            results.append(Task(
+                id=m.id,
+                title=m.title,
+                description=m.description,
+                requirement_ids=json.loads(m.requirement_ids_json),
+                acceptance_criterion_ids=json.loads(m.acceptance_criterion_ids_json),
+                planned_files=pf_list,
+                expected_tests=json.loads(m.expected_tests_json),
+                allowed_commands=json.loads(m.allowed_commands_json),
+                forbidden_changes=json.loads(m.forbidden_changes_json),
+                status=m.status
+            ))
+        return results
+
+    def save(self, task: Task):
+        model = TaskModel(
+            id=task.id,
+            title=task.title,
+            description=task.description,
+            requirement_ids_json=json.dumps(task.requirement_ids),
+            acceptance_criterion_ids_json=json.dumps(task.acceptance_criterion_ids),
+            planned_files_json=json.dumps([pf.model_dump() for pf in task.planned_files]),
+            expected_tests_json=json.dumps(task.expected_tests),
+            allowed_commands_json=json.dumps(task.allowed_commands),
+            forbidden_changes_json=json.dumps(task.forbidden_changes),
+            status=task.status
+        )
+        self.session.merge(model)
+        self.session.commit()
+
+class GapRepository:
+    def __init__(self, session: Session):
+        self.session = session
+
+    def get_all(self) -> List[Gap]:
+        statement = select(GapModel)
+        models = self.session.exec(statement).all()
+        results = []
+        for m in models:
+            results.append(Gap(
+                id=m.id,
+                severity=m.severity,
+                gap_type=m.gap_type,
+                requirement_id=m.requirement_id,
+                task_id=m.task_id,
+                description=m.description,
+                evidence=json.loads(m.evidence_json),
+                recommended_fix=m.recommended_fix,
+                blocking=m.blocking
+            ))
+        return results
+
+    def save(self, gap: Gap):
+        model = GapModel(
+            id=gap.id,
+            severity=gap.severity,
+            gap_type=gap.gap_type,
+            requirement_id=gap.requirement_id,
+            task_id=gap.task_id,
+            description=gap.description,
+            evidence_json=json.dumps(gap.evidence),
+            recommended_fix=gap.recommended_fix,
+            blocking=gap.blocking
+        )
+        self.session.merge(model)
+        self.session.commit()
+
+    def delete_for_task(self, task_id: str):
+        self.session.exec(delete(GapModel).where(GapModel.task_id == task_id))
+        self.session.commit()
+
+    def delete_plan_gaps(self):
+        self.session.exec(delete(GapModel).where(GapModel.id.like("GAP-PLAN-%")))
+        self.session.commit()
+
+class EvidenceRepository:
+    def __init__(self, session: Session):
+        self.session = session
+
+    def save_command_result(self, task_id: str, result: CommandResult):
+        model = EvidenceModel(
+            type="command",
+            task_id=task_id,
+            data_json=result.model_dump_json()
+        )
+        self.session.add(model)
+        self.session.commit()
+
+    def save_diff_evidence(self, ev: DiffEvidence):
+        model = EvidenceModel(
+            type="diff",
+            task_id=ev.task_id,
+            data_json=ev.model_dump_json()
+        )
+        self.session.add(model)
+        self.session.commit()
+
+    def save_test_evidence(self, ev: TestEvidence, task_id: Optional[str] = None):
+        model = EvidenceModel(
+            type="test",
+            task_id=task_id,
+            requirement_id=ev.requirement_id,
+            acceptance_criterion_id=ev.acceptance_criterion_id,
+            data_json=ev.model_dump_json()
+        )
+        self.session.add(model)
+        self.session.commit()
+
+    def get_all(self) -> List[Any]:
+        statement = select(EvidenceModel)
+        models = self.session.exec(statement).all()
+        results = []
+        for m in models:
+            data = json.loads(m.data_json)
+            if m.type == "command":
+                results.append(CommandResult.model_validate(data))
+            elif m.type == "diff":
+                results.append(DiffEvidence.model_validate(data))
+            elif m.type == "test":
+                results.append(TestEvidence.model_validate(data))
+        return results
+
+    def delete_for_task(self, task_id: str):
+        self.session.exec(delete(EvidenceModel).where(EvidenceModel.task_id == task_id))
+        self.session.commit()
+
+
+class CritiqueFindingRepository:
+    def __init__(self, session: Session):
+        self.session = session
+
+    def get_all(self) -> List[CritiqueFinding]:
+        statement = select(CritiqueFindingModel)
+        models = self.session.exec(statement).all()
+        return [
+            CritiqueFinding(
+                id=m.id,
+                source_agent=m.source_agent,
+                target_plan_id=m.target_plan_id,
+                severity=m.severity,
+                finding_type=m.finding_type,
+                claim=m.claim,
+                linked_requirement_id=m.linked_requirement_id,
+                suggested_requirement=m.suggested_requirement,
+                suggested_task=m.suggested_task,
+                falsifiable_check=m.falsifiable_check,
+                status=m.status,
+            )
+            for m in models
+        ]
+
+    def save(self, finding: CritiqueFinding):
+        model = CritiqueFindingModel(
+            id=finding.id,
+            source_agent=finding.source_agent,
+            target_plan_id=finding.target_plan_id,
+            severity=finding.severity,
+            finding_type=finding.finding_type,
+            claim=finding.claim,
+            linked_requirement_id=finding.linked_requirement_id,
+            suggested_requirement=finding.suggested_requirement,
+            suggested_task=finding.suggested_task,
+            falsifiable_check=finding.falsifiable_check,
+            status=finding.status,
+        )
+        self.session.merge(model)
+        self.session.commit()
+
+class ArtifactGraphRepository:
+    def __init__(self, session: Session):
+        self.session = session
+        self.req_repo = RequirementRepository(session)
+        self.assumption_repo = AssumptionRepository(session)
+        self.task_repo = TaskRepository(session)
+        self.gap_repo = GapRepository(session)
+        self.evidence_repo = EvidenceRepository(session)
+        self.finding_repo = CritiqueFindingRepository(session)
+
+    def load_graph(self) -> ArtifactGraph:
+        graph = ArtifactGraph()
+        for req in self.req_repo.get_all():
+            graph.add_requirement(req)
+        for assumption in self.assumption_repo.get_all():
+            graph.add_assumption(assumption)
+        for task in self.task_repo.get_all():
+            graph.add_task(task)
+        for finding in self.finding_repo.get_all():
+            graph.add_finding(finding)
+        for gap in self.gap_repo.get_all():
+            graph.add_gap(gap)
+        for ev in self.evidence_repo.get_all():
+            if isinstance(ev, CommandResult):
+                graph.add_command_result(ev)
+            elif isinstance(ev, DiffEvidence):
+                graph.add_diff_evidence(ev)
+            elif isinstance(ev, TestEvidence):
+                graph.add_test_evidence(ev)
+        return graph
+
+
+class StateRepository:
+    def __init__(self, session: Session):
+        self.session = session
+
+    def get_state(self) -> Optional[ProjectStateModel]:
+        statement = select(ProjectStateModel).where(ProjectStateModel.id == "singleton")
+        return self.session.exec(statement).first()
+
+    def save_state(self, state: ProjectStateModel | str, history: Optional[List[str]] = None):
+        if isinstance(state, ProjectStateModel):
+            state.id = "singleton"
+        else:
+            state = ProjectStateModel(
+                id="singleton",
+                current_phase=state,
+                history_json=json.dumps(history or []),
+            )
+        self.session.merge(state)
+        self.session.commit()
+
+    def record_phase(self, phase: str):
+        current = self.get_state()
+        history = []
+        if current:
+            history = json.loads(current.history_json)
+        if not history or history[-1] != phase:
+            history.append(phase)
+        self.save_state(phase, history)

package/src/devcouncil/telemetry/cost.py

@@ -0,0 +1,34 @@
+import logging
+from typing import Dict
+
+logger = logging.getLogger(__name__)
+
+class CostEstimator:
+    """Estimates LLM usage cost based on provider pricing."""
+    
+    # Rough estimates, update for production
+    PRICING = {
+        "anthropic/claude-3.5-sonnet": {"input": 0.000003, "output": 0.000015},
+        "anthropic/claude-3-opus": {"input": 0.000015, "output": 0.000075},
+        "anthropic/claude-sonnet-4": {"input": 0.000003, "output": 0.000015},
+        "google/gemini-pro-1.5": {"input": 0.00000125, "output": 0.000005},
+        "google/gemini-2.5-pro": {"input": 0.00000125, "output": 0.00001},
+        "openai/gpt-4o": {"input": 0.000005, "output": 0.000015},
+        "openai/o3-mini": {"input": 0.0000011, "output": 0.0000044},
+    }
+
+    # Conservative default for unknown models
+    DEFAULT_PRICING = {"input": 0.000005, "output": 0.000015}
+
+    @classmethod
+    def estimate_cost(cls, model: str, usage: Dict[str, int]) -> float:
+        prices = cls.PRICING.get(model)
+        if not prices:
+            logger.debug("Unknown model for cost estimation: %s — using default pricing", model)
+            prices = cls.DEFAULT_PRICING
+            
+        prompt_tokens = usage.get("prompt_tokens", 0)
+        completion_tokens = usage.get("completion_tokens", 0)
+        
+        cost = (prompt_tokens * prices["input"]) + (completion_tokens * prices["output"])
+        return cost

package/src/devcouncil/telemetry/traces.py

@@ -0,0 +1,91 @@
+import json
+import logging
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Iterable, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+logger = logging.getLogger(__name__)
+
+TRACE_SCHEMA_VERSION = "devcouncil.trace.v1"
+
+
+class TraceEvent(BaseModel):
+    """Stable JSONL event shape for DevCouncil and external visualizers."""
+
+    model_config = ConfigDict(populate_by_name=True, serialize_by_alias=True)
+
+    schema_version: str = Field(TRACE_SCHEMA_VERSION, alias="schema")
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    runtime: str = "devcouncil"
+    type: str
+    run_id: Optional[str] = None
+    task_id: Optional[str] = None
+    summary: str = ""
+    details: Dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def from_legacy(cls, raw: Dict[str, Any]) -> "TraceEvent":
+        if raw.get("schema") == TRACE_SCHEMA_VERSION:
+            return cls.model_validate(raw)
+        details = raw.get("details") if isinstance(raw.get("details"), dict) else {}
+        task_id = details.get("task_id") if isinstance(details.get("task_id"), str) else None
+        summary = details.get("summary") if isinstance(details.get("summary"), str) else ""
+        return cls(
+            type=str(raw.get("type", "legacy_event")),
+            run_id=raw.get("run_id"),
+            task_id=task_id,
+            summary=summary,
+            details=details,
+        )
+
+
+class TraceLogger:
+    """Manages appending execution traces to a local log file."""
+
+    def __init__(self, project_root: Path):
+        self.log_dir = project_root / ".devcouncil" / "logs"
+        self.trace_file = self.log_dir / "traces.jsonl"
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+
+    def log_event(
+        self,
+        event_type: str,
+        details: Dict[str, Any],
+        run_id: Optional[str] = None,
+        task_id: Optional[str] = None,
+        summary: str = "",
+    ) -> TraceEvent:
+        """Append an orchestration event trace."""
+        trace = TraceEvent(
+            type=event_type,
+            details=details,
+            run_id=run_id,
+            task_id=task_id,
+            summary=summary,
+        )
+        try:
+            with open(self.trace_file, "a", encoding="utf-8") as f:
+                f.write(trace.model_dump_json() + "\n")
+        except Exception as e:
+            logger.debug("Failed to write trace event %s: %s", event_type, e)
+        return trace
+
+
+def read_trace_events(project_root: Path) -> Iterable[TraceEvent]:
+    trace_file = project_root / ".devcouncil" / "logs" / "traces.jsonl"
+    if not trace_file.exists():
+        return []
+
+    events: list[TraceEvent] = []
+    for line in trace_file.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        try:
+            events.append(TraceEvent.from_legacy(json.loads(line)))
+        except Exception as exc:
+            logger.debug("Skipping invalid trace line: %s", exc)
+    return events

package/src/devcouncil/telemetry/tracker.py

@@ -0,0 +1,49 @@
+import json
+from pathlib import Path
+from typing import Dict, Any
+
+COST_PER_1K_TOKENS = {
+    "anthropic/claude-3-opus": {"prompt": 0.015, "completion": 0.075},
+    "anthropic/claude-3.5-sonnet": {"prompt": 0.003, "completion": 0.015},
+    "openai/gpt-4o": {"prompt": 0.005, "completion": 0.015},
+    "google/gemini-pro-1.5": {"prompt": 0.00125, "completion": 0.00375},
+}
+
+class TelemetryTracker:
+    def __init__(self, project_root: Path):
+        self.log_file = project_root / ".devcouncil" / "logs" / "telemetry.json"
+        self.stats = self._load()
+
+    def _load(self) -> Dict[str, Any]:
+        if self.log_file.exists():
+            try:
+                with open(self.log_file, "r") as f:
+                    return json.load(f)
+            except Exception:
+                pass
+        return {"total_cost": 0.0, "total_prompt_tokens": 0, "total_completion_tokens": 0, "models": {}}
+
+    def _save(self):
+        self.log_file.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.log_file, "w") as f:
+            json.dump(self.stats, f, indent=2)
+
+    def log_usage(self, model: str, usage: Dict[str, int]):
+        prompt_tokens = usage.get("prompt_tokens", 0)
+        completion_tokens = usage.get("completion_tokens", 0)
+
+        rates = COST_PER_1K_TOKENS.get(model, {"prompt": 0.0, "completion": 0.0})
+        cost = (prompt_tokens / 1000.0) * rates["prompt"] + (completion_tokens / 1000.0) * rates["completion"]
+
+        self.stats["total_cost"] += cost
+        self.stats["total_prompt_tokens"] += prompt_tokens
+        self.stats["total_completion_tokens"] += completion_tokens
+
+        if model not in self.stats["models"]:
+            self.stats["models"][model] = {"cost": 0.0, "prompt_tokens": 0, "completion_tokens": 0}
+
+        self.stats["models"][model]["cost"] += cost
+        self.stats["models"][model]["prompt_tokens"] += prompt_tokens
+        self.stats["models"][model]["completion_tokens"] += completion_tokens
+
+        self._save()

package/src/devcouncil/utils/__init__.py

@@ -0,0 +1 @@
+"""Utilities package: redaction, paths, hashing, subprocess helpers."""