adforge 0.1.0__py3-none-any.whl

adforge/__init__.py

@@ -0,0 +1,3 @@
+"""Solution Architect MCP Server package."""
+
+__version__ = "0.1.0"

adforge/models/__init__.py

@@ -0,0 +1,24 @@
+"""Core Pydantic models for solution architecture data."""
+
+from adforge.models.common import Complexity, Status
+from adforge.models.cost import CostLineItem, CostSummary
+from adforge.models.dag import EdgeType, NodeType, SolutionEdge, SolutionNode
+from adforge.models.problem import Problem
+from adforge.models.solution import Comment, Review, Solution
+from adforge.models.sub_problem import SubProblem
+
+__all__ = [
+    "Status",
+    "Complexity",
+    "Problem",
+    "Solution",
+    "Comment",
+    "Review",
+    "SubProblem",
+    "SolutionNode",
+    "SolutionEdge",
+    "NodeType",
+    "EdgeType",
+    "CostLineItem",
+    "CostSummary",
+]

adforge/models/common.py

@@ -0,0 +1,23 @@
+"""Shared enumerations and primitives."""
+
+from enum import IntEnum, StrEnum
+
+
+class Status(StrEnum):
+    """Generic lifecycle status."""
+
+    DRAFT = "draft"
+    OPEN = "open"
+    IN_PROGRESS = "in_progress"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    CLOSED = "closed"
+
+
+class Complexity(IntEnum):
+    """Rough complexity scoring for sub-problems."""
+
+    LOW = 1
+    MEDIUM = 3
+    HIGH = 5
+    EXTREME = 8

adforge/models/cost.py

@@ -0,0 +1,42 @@
+"""Cost/price line items and summaries."""
+
+from datetime import UTC, datetime
+from decimal import Decimal
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+class CostLineItem(BaseModel):
+    """A single priced component of a solution."""
+
+    id: str = Field(default_factory=lambda: uuid4().hex)
+    solution_id: str
+    sub_problem_id: str | None = None
+    provider: str
+    service: str
+    region: str = ""
+    parameters: dict[str, Any] = Field(default_factory=dict)
+    unit_price: Decimal
+    quantity: Decimal = Decimal("1")
+    unit: str = ""
+    source_url: str = ""
+    source_fetched_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    @property
+    def total(self) -> Decimal:
+        """Total cost for this line item."""
+        return self.unit_price * self.quantity
+
+
+class CostSummary(BaseModel):
+    """Aggregated cost view attached to a solution document."""
+
+    currency: str = "USD"
+    total_monthly: Decimal = Decimal("0")
+    total_hourly: Decimal | None = None
+    line_item_count: int = 0
+    providers: list[str] = Field(default_factory=list)
+    note: str = ""

adforge/models/dag.py

@@ -0,0 +1,48 @@
+"""DAG representation of a solution approach."""
+
+from enum import StrEnum
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+class NodeType(StrEnum):
+    """Kind of node in a solution DAG."""
+
+    SUB_PROBLEM = "sub_problem"
+    DECISION = "decision"
+    DELIVERABLE = "deliverable"
+    RISK = "risk"
+
+
+class EdgeType(StrEnum):
+    """Kind of edge in a solution DAG."""
+
+    DEPENDS_ON = "depends_on"
+    ALTERNATIVE_TO = "alternative_to"
+    PRODUCES = "produces"
+    BLOCKS = "blocks"
+
+
+class SolutionNode(BaseModel):
+    """A node in a solution approach DAG."""
+
+    id: str = Field(default_factory=lambda: uuid4().hex)
+    solution_id: str
+    sub_problem_id: str | None = None
+    node_type: NodeType = NodeType.SUB_PROBLEM
+    title: str = ""
+    description: str = ""
+    data: dict[str, Any] = Field(default_factory=dict)
+
+
+class SolutionEdge(BaseModel):
+    """A directed edge between two nodes in a solution approach DAG."""
+
+    id: str = Field(default_factory=lambda: uuid4().hex)
+    solution_id: str
+    from_node_id: str
+    to_node_id: str
+    edge_type: EdgeType = EdgeType.DEPENDS_ON
+    data: dict[str, Any] = Field(default_factory=dict)

adforge/models/problem.py

@@ -0,0 +1,21 @@
+"""Problem statement model."""
+
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+class Problem(BaseModel):
+    """A problem to be solved by one or more solution approaches."""
+
+    id: str = Field(default_factory=lambda: uuid4().hex)
+    title: str
+    description: str = ""
+    tags: list[str] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    def touch(self) -> None:
+        """Update the updated_at timestamp."""
+        self.updated_at = datetime.now(UTC)

adforge/models/solution.py

@@ -0,0 +1,49 @@
+"""Solution document model, shaped like a GitHub PR/issue."""
+
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+from adforge.models.common import Status
+from adforge.models.cost import CostSummary
+
+
+class Comment(BaseModel):
+    """A comment on a solution, like a GitHub issue comment."""
+
+    id: str = Field(default_factory=lambda: uuid4().hex)
+    author: str = ""
+    body: str = ""
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class Review(BaseModel):
+    """A review/approval record on a solution, like a GitHub PR review."""
+
+    id: str = Field(default_factory=lambda: uuid4().hex)
+    author: str = ""
+    state: str = "commented"  # commented, approved, changes_requested
+    body: str = ""
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class Solution(BaseModel):
+    """A solution approach for a problem, persisted as a PR/issue-shaped document."""
+
+    id: str = Field(default_factory=lambda: uuid4().hex)
+    problem_id: str
+    title: str
+    status: Status = Status.DRAFT
+    body: str = ""
+    comments: list[Comment] = Field(default_factory=list)
+    reviews: list[Review] = Field(default_factory=list)
+    labels: list[str] = Field(default_factory=list)
+    assignees: list[str] = Field(default_factory=list)
+    cost_summary: CostSummary | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    def touch(self) -> None:
+        """Update the updated_at timestamp."""
+        self.updated_at = datetime.now(UTC)

adforge/models/sub_problem.py

@@ -0,0 +1,28 @@
+"""Sub-problem model for divide-and-conquer decomposition."""
+
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+from adforge.models.common import Complexity, Status
+
+
+class SubProblem(BaseModel):
+    """A sub-problem belonging to a problem and optionally a solution."""
+
+    id: str = Field(default_factory=lambda: uuid4().hex)
+    problem_id: str
+    solution_id: str | None = None
+    parent_id: str | None = None
+    title: str
+    description: str = ""
+    tags: list[str] = Field(default_factory=list)
+    complexity: Complexity = Complexity.MEDIUM
+    status: Status = Status.DRAFT
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    def touch(self) -> None:
+        """Update the updated_at timestamp."""
+        self.updated_at = datetime.now(UTC)

adforge/persistence/__init__.py

@@ -0,0 +1,20 @@
+"""Persistence layer: SQLite-backed storage for problems, solutions, and costs."""
+
+from adforge.persistence.db import get_connection, migrate
+from adforge.persistence.repositories.cost_repository import CostRepository
+from adforge.persistence.repositories.dag_repository import DagRepository
+from adforge.persistence.repositories.problem_repository import ProblemRepository
+from adforge.persistence.repositories.solution_repository import SolutionRepository
+from adforge.persistence.repositories.sub_problem_repository import (
+    SubProblemRepository,
+)
+
+__all__ = [
+    "get_connection",
+    "migrate",
+    "ProblemRepository",
+    "SolutionRepository",
+    "SubProblemRepository",
+    "DagRepository",
+    "CostRepository",
+]

adforge/persistence/db.py

@@ -0,0 +1,84 @@
+"""SQLite connection and migration utilities."""
+
+import json
+import os
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from adforge.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+DEFAULT_DB_NAME = "adforge.db"
+
+
+def _db_path() -> Path:
+    """Resolve the SQLite database path from env or project root."""
+    env_path = os.environ.get("ADFORGE_DB_PATH")
+    if env_path:
+        return Path(env_path)
+
+    # Fall back to project root, discovered from this file's location.
+    project_root = Path(__file__).resolve().parents[4]
+    return project_root / DEFAULT_DB_NAME
+
+
+def get_connection() -> sqlite3.Connection:
+    """Return a SQLite connection with JSON-friendly row factory."""
+    path = _db_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(path)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    return conn
+
+
+def _load_migrations() -> list[tuple[int, str]]:
+    """Load migration SQL files in order."""
+    migrations_dir = Path(__file__).with_name("migrations")
+    files = sorted(migrations_dir.glob("*.sql"))
+    migrations = []
+    for file in files:
+        try:
+            number = int(file.stem.split("_", 1)[0])
+        except ValueError:
+            logger.warning("Skipping migration file without numeric prefix", file=file.name)
+            continue
+        migrations.append((number, file.read_text()))
+    migrations.sort(key=lambda x: x[0])
+    return migrations
+
+
+def migrate() -> None:
+    """Run pending migrations."""
+    with get_connection() as conn:
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS migrations (
+                version INTEGER PRIMARY KEY
+            )
+            """
+        )
+        cur = conn.execute("SELECT version FROM migrations")
+        applied = {row["version"] for row in cur.fetchall()}
+
+        for version, sql in _load_migrations():
+            if version in applied:
+                continue
+            logger.info("Applying migration", version=version)
+            conn.executescript(sql)
+            conn.execute("INSERT INTO migrations (version) VALUES (?)", (version,))
+            conn.commit()
+
+
+def to_json_blob(value: Any) -> str:
+    """Serialize a value to a JSON string for SQLite storage."""
+    return json.dumps(value, default=str)
+
+
+def from_json_blob(text: str | None) -> Any:
+    """Deserialize a JSON string from SQLite storage."""
+    if text is None:
+        return None
+    return json.loads(text)

adforge/persistence/migrations/001_initial.sql

@@ -0,0 +1,103 @@
+-- Initial schema for solution-architect-spl
+
+CREATE TABLE IF NOT EXISTS problems (
+    id TEXT PRIMARY KEY,
+    title TEXT NOT NULL,
+    description TEXT NOT NULL DEFAULT '',
+    tags TEXT NOT NULL DEFAULT '[]',
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS solutions (
+    id TEXT PRIMARY KEY,
+    problem_id TEXT NOT NULL,
+    title TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'draft',
+    body TEXT NOT NULL DEFAULT '',
+    comments TEXT NOT NULL DEFAULT '[]',
+    reviews TEXT NOT NULL DEFAULT '[]',
+    labels TEXT NOT NULL DEFAULT '[]',
+    assignees TEXT NOT NULL DEFAULT '[]',
+    cost_summary TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    FOREIGN KEY (problem_id) REFERENCES problems(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_solutions_problem_id ON solutions(problem_id);
+
+CREATE TABLE IF NOT EXISTS sub_problems (
+    id TEXT PRIMARY KEY,
+    problem_id TEXT NOT NULL,
+    solution_id TEXT,
+    parent_id TEXT,
+    title TEXT NOT NULL,
+    description TEXT NOT NULL DEFAULT '',
+    tags TEXT NOT NULL DEFAULT '[]',
+    complexity INTEGER NOT NULL DEFAULT 3,
+    status TEXT NOT NULL DEFAULT 'draft',
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    FOREIGN KEY (problem_id) REFERENCES problems(id) ON DELETE CASCADE,
+    FOREIGN KEY (solution_id) REFERENCES solutions(id) ON DELETE SET NULL,
+    FOREIGN KEY (parent_id) REFERENCES sub_problems(id) ON DELETE SET NULL
+);
+CREATE INDEX IF NOT EXISTS idx_sub_problems_problem_id ON sub_problems(problem_id);
+CREATE INDEX IF NOT EXISTS idx_sub_problems_solution_id ON sub_problems(solution_id);
+
+CREATE TABLE IF NOT EXISTS solution_nodes (
+    id TEXT PRIMARY KEY,
+    solution_id TEXT NOT NULL,
+    sub_problem_id TEXT,
+    node_type TEXT NOT NULL DEFAULT 'sub_problem',
+    title TEXT NOT NULL DEFAULT '',
+    description TEXT NOT NULL DEFAULT '',
+    data TEXT NOT NULL DEFAULT '{}',
+    FOREIGN KEY (solution_id) REFERENCES solutions(id) ON DELETE CASCADE,
+    FOREIGN KEY (sub_problem_id) REFERENCES sub_problems(id) ON DELETE SET NULL
+);
+CREATE INDEX IF NOT EXISTS idx_solution_nodes_solution_id ON solution_nodes(solution_id);
+
+CREATE TABLE IF NOT EXISTS solution_edges (
+    id TEXT PRIMARY KEY,
+    solution_id TEXT NOT NULL,
+    from_node_id TEXT NOT NULL,
+    to_node_id TEXT NOT NULL,
+    edge_type TEXT NOT NULL DEFAULT 'depends_on',
+    data TEXT NOT NULL DEFAULT '{}',
+    FOREIGN KEY (solution_id) REFERENCES solutions(id) ON DELETE CASCADE,
+    FOREIGN KEY (from_node_id) REFERENCES solution_nodes(id) ON DELETE CASCADE,
+    FOREIGN KEY (to_node_id) REFERENCES solution_nodes(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_solution_edges_solution_id ON solution_edges(solution_id);
+
+CREATE TABLE IF NOT EXISTS cost_line_items (
+    id TEXT PRIMARY KEY,
+    solution_id TEXT NOT NULL,
+    sub_problem_id TEXT,
+    provider TEXT NOT NULL,
+    service TEXT NOT NULL,
+    region TEXT NOT NULL DEFAULT '',
+    parameters TEXT NOT NULL DEFAULT '{}',
+    unit_price TEXT NOT NULL,
+    quantity TEXT NOT NULL DEFAULT '1',
+    unit TEXT NOT NULL DEFAULT '',
+    source_url TEXT NOT NULL DEFAULT '',
+    source_fetched_at TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    FOREIGN KEY (solution_id) REFERENCES solutions(id) ON DELETE CASCADE,
+    FOREIGN KEY (sub_problem_id) REFERENCES sub_problems(id) ON DELETE SET NULL
+);
+CREATE INDEX IF NOT EXISTS idx_cost_line_items_solution_id ON cost_line_items(solution_id);
+
+CREATE TABLE IF NOT EXISTS pricing_cache (
+    key TEXT PRIMARY KEY,
+    provider TEXT NOT NULL,
+    service TEXT NOT NULL,
+    region TEXT NOT NULL DEFAULT '',
+    parameters_hash TEXT NOT NULL DEFAULT '',
+    response TEXT NOT NULL,
+    fetched_at TEXT NOT NULL,
+    expires_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_pricing_cache_expires ON pricing_cache(expires_at);

adforge/persistence/repositories/__init__.py

@@ -0,0 +1 @@
+"""SQLite repositories for domain models."""

adforge/persistence/repositories/cost_repository.py

@@ -0,0 +1,172 @@
+"""Cost line item repository and pricing cache."""
+
+import hashlib
+import json
+import sqlite3
+from datetime import UTC, datetime, timedelta
+from decimal import Decimal
+from typing import Any
+
+from adforge.models import CostLineItem
+from adforge.persistence.db import from_json_blob, get_connection, to_json_blob
+
+
+class CostRepository:
+    """CRUD for cost line items."""
+
+    def __init__(self, conn: sqlite3.Connection | None = None) -> None:
+        self._conn = conn or get_connection()
+        self._own_conn = conn is None
+
+    def save(self, item: CostLineItem) -> CostLineItem:
+        self._conn.execute(
+            """
+            INSERT INTO cost_line_items (
+                id, solution_id, sub_problem_id, provider, service, region,
+                parameters, unit_price, quantity, unit, source_url, source_fetched_at, created_at
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(id) DO UPDATE SET
+                solution_id = excluded.solution_id,
+                sub_problem_id = excluded.sub_problem_id,
+                provider = excluded.provider,
+                service = excluded.service,
+                region = excluded.region,
+                parameters = excluded.parameters,
+                unit_price = excluded.unit_price,
+                quantity = excluded.quantity,
+                unit = excluded.unit,
+                source_url = excluded.source_url,
+                source_fetched_at = excluded.source_fetched_at
+            """,
+            (
+                item.id,
+                item.solution_id,
+                item.sub_problem_id,
+                item.provider,
+                item.service,
+                item.region,
+                to_json_blob(item.parameters),
+                str(item.unit_price),
+                str(item.quantity),
+                item.unit,
+                item.source_url,
+                item.source_fetched_at.isoformat(),
+                item.created_at.isoformat(),
+            ),
+        )
+        self._conn.commit()
+        return item
+
+    def list_for_solution(self, solution_id: str) -> list[CostLineItem]:
+        rows = self._conn.execute(
+            "SELECT * FROM cost_line_items WHERE solution_id = ? ORDER BY created_at",
+            (solution_id,),
+        ).fetchall()
+        return [self._row_to_item(row) for row in rows]
+
+    def delete(self, item_id: str) -> bool:
+        cur = self._conn.execute("DELETE FROM cost_line_items WHERE id = ?", (item_id,))
+        self._conn.commit()
+        return cur.rowcount > 0
+
+    @staticmethod
+    def _row_to_item(row: sqlite3.Row) -> CostLineItem:
+        return CostLineItem(
+            id=row["id"],
+            solution_id=row["solution_id"],
+            sub_problem_id=row["sub_problem_id"],
+            provider=row["provider"],
+            service=row["service"],
+            region=row["region"],
+            parameters=from_json_blob(row["parameters"]) or {},
+            unit_price=Decimal(row["unit_price"]),
+            quantity=Decimal(row["quantity"]),
+            unit=row["unit"],
+            source_url=row["source_url"],
+            source_fetched_at=datetime.fromisoformat(row["source_fetched_at"]),
+            created_at=datetime.fromisoformat(row["created_at"]),
+        )
+
+    def __del__(self) -> None:
+        if self._own_conn:
+            self._conn.close()
+
+
+class PricingCache:
+    """SQLite-backed TTL cache for provider pricing responses."""
+
+    def __init__(self, conn: sqlite3.Connection | None = None, ttl_seconds: int = 86400) -> None:
+        self._conn = conn or get_connection()
+        self._own_conn = conn is None
+        self._ttl_seconds = ttl_seconds
+
+    def _make_key(
+        self, provider: str, service: str, region: str, parameters: dict[str, Any]
+    ) -> str:
+        payload = json.dumps(
+            {"provider": provider, "service": service, "region": region, "params": parameters},
+            sort_keys=True,
+        )
+        return hashlib.sha256(payload.encode()).hexdigest()
+
+    def get(
+        self, provider: str, service: str, region: str, parameters: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        key = self._make_key(provider, service, region, parameters)
+        now = datetime.now(UTC).isoformat()
+        row = self._conn.execute(
+            "SELECT response FROM pricing_cache WHERE key = ? AND expires_at > ?",
+            (key, now),
+        ).fetchone()
+        if row is None:
+            return None
+        response = from_json_blob(row["response"])
+        if response is None:
+            return None
+        return response  # type: ignore[no-any-return]
+
+    def set(
+        self,
+        provider: str,
+        service: str,
+        region: str,
+        parameters: dict[str, Any],
+        response: dict[str, Any],
+    ) -> None:
+        key = self._make_key(provider, service, region, parameters)
+        now = datetime.now(UTC)
+        expires = now + timedelta(seconds=self._ttl_seconds)
+        params_hash = key[:16]
+        self._conn.execute(
+            """
+            INSERT INTO pricing_cache (
+                key, provider, service, region, parameters_hash, response, fetched_at, expires_at
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(key) DO UPDATE SET
+                response = excluded.response,
+                fetched_at = excluded.fetched_at,
+                expires_at = excluded.expires_at
+            """,
+            (
+                key,
+                provider,
+                service,
+                region,
+                params_hash,
+                to_json_blob(response),
+                now.isoformat(),
+                expires.isoformat(),
+            ),
+        )
+        self._conn.commit()
+
+    def clear_expired(self) -> None:
+        now = datetime.now(UTC).isoformat()
+        self._conn.execute("DELETE FROM pricing_cache WHERE expires_at <= ?", (now,))
+        self._conn.commit()
+
+    def __del__(self) -> None:
+        if self._own_conn:
+            self._conn.close()