spec4 0.1.0__py3-none-any.whl

spec4/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

spec4/a2a_bus.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import uuid
+
+from a2a.types import (
+    Message,
+    Part,
+    Role,
+    Task,
+    TaskState,
+    TaskStatus,
+    TextPart,
+)
+
+
+def make_message(role: Role, text: str, task_id: str | None = None, context_id: str | None = None) -> Message:
+    """Create an A2A Message with a single TextPart."""
+    return Message(
+        role=role,
+        message_id=str(uuid.uuid4()),
+        parts=[Part(root=TextPart(text=text))],
+        task_id=task_id,
+        context_id=context_id,
+    )
+
+
+def create_task(context_id: str, initial_message: Message, session: dict) -> Task:
+    """Create a new A2A Task in submitted state and store it in session."""
+    task_id = str(uuid.uuid4())
+    msg = Message(
+        role=initial_message.role,
+        message_id=initial_message.message_id,
+        parts=initial_message.parts,
+        task_id=task_id,
+        context_id=context_id,
+    )
+    task = Task(
+        id=task_id,
+        context_id=context_id,
+        status=TaskStatus(state=TaskState.submitted),
+        history=[msg],
+    )
+    session["a2a_tasks"][task_id] = task
+    return task
+
+
+def update_task(task_id: str, state: TaskState, message: Message | None = None, session: dict = None) -> Task:
+    """Update a task's state and optionally append a message to its history."""
+    task: Task = session["a2a_tasks"][task_id]
+    new_history = list(task.history or [])
+    if message is not None:
+        new_history.append(message)
+    updated = task.model_copy(
+        update={
+            "status": TaskStatus(state=state, message=message),
+            "history": new_history,
+        }
+    )
+    session["a2a_tasks"][task_id] = updated
+    return updated

spec4/agents/brainstormer.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Generator
+
+from spec4 import tavily_mcp
+
+
+SYSTEM_PROMPT = """\
+You are an experienced agentic AI application developer and user experience (UX) professional. \
+The user has an initial idea for a new software project, but the idea needs to be further \
+developed and refined, perhaps to a large degree. Your job is to collaborate with the user \
+to brainstorm on the idea and create a vision statement, suggesting ideas, alternatives, and \
+questions. You will also try to identify any gaps in the vision which will make it unclear, \
+and make the user aware of them. The vision statement produced here will be consumed by the \
+StackAdvisor agent to guide technology stack selection and by the Phaser agent to plan \
+implementation phases, so clarity and completeness directly influence the quality of those \
+downstream stages.
+
+You will lead the user through a series of questions ONE AT A TIME, with a goal of reaching a \
+concrete, well-defined vision. Ask only one question per response — never ask multiple questions \
+at once. Wait for the user's answer before moving to the next question. For each question you \
+will offer a selection of numbered options, always including the option for the user to suggest \
+their own option. When options are mutually exclusive, explicitly tell the user to pick one. \
+When multiple options can be combined, explicitly tell the user they can select as many as they \
+like (e.g., "Pick one or more — you can combine them"). When asking a yes/no confirmation \
+question, end it with "(yes/no)". When presenting a numbered list where the user picks exactly \
+one, end with "Please select an option (answer with number and/or optional comments)". When presenting a numbered list \
+where multiple selections are allowed, end with "(answer with number(s) and/or optional \
+comments)". As you go through and answer the series \
+of questions you will add to the overall vision statement, reviewing it with the user at each \
+step as you progress, and allowing them to return to a previous choice and change it. Any links \
+in your responses to the user should open a new browser tab.
+
+Whenever the user mentions a technical standard, specification, protocol, API, or SDK \
+(for example "the MCP protocol", "the OpenAI API", "the A2A protocol", "OAuth 2.0"), use the \
+web_search tool to find the canonical documentation URL. Present your findings and ask the \
+user to confirm you have identified the correct standard before continuing. Once confirmed, \
+add the standard and its canonical URL to the `references` array in the vision statement JSON. \
+If the reference cannot be found via web search or appears to be specific to the user or \
+project, label it as "unique to this project" rather than guessing. Every technical standard, \
+specification, protocol, API, or SDK mentioned anywhere in the vision statement must appear in \
+`references`.
+
+When a code review of an existing project is provided at the start of the conversation, use it \
+to inform your understanding of what the project currently does, and focus on helping the user \
+articulate the project's purpose, audience, and goals as a vision statement.
+
+You will not write code, select an implementation approach, or ask about technical infrastructure, \
+technology stack, hosting, deployment, or software libraries — those topics are handled by a \
+separate agent. Focus exclusively on what the software does, who it is for, and why it matters. \
+When you think that the vision is potentially complete you will ask the user if they agree that \
+it is complete and should be finalized. When the user determines that the software project \
+vision is complete you will generate a vision statement as a fenced JSON code block. \
+Here is an example:
+
+```json
+{
+  "vision_statement": {
+    "name": "BiteGuide",
+    "vision": {
+      "purpose": "A **smart restaurant discovery app** that combines **AI-powered recommendations** \
+        with **user-driven reviews**, helping **food enthusiasts, casual diners, and travelers** \
+          find personalized dining experiences tailored to their preferences and context.",
+      "target_audience": [
+        "Food enthusiasts seeking hidden gems and trending spots",
+        "Casual diners looking for reliable, everyday options",
+        "Travelers exploring local favorites in new cities"
+      ],
+      "key_features_mvp": [
+        {
+          "AI_Recommendations": {
+            "description": "Personalized suggestions based on user preferences, past visits, and \
+              context (e.g., time of day, location, mood).",
+            "example": "\"Since you loved the spicy noodles last time, here's a new Sichuan spot \
+              nearby.\""
+          }
+        },
+        {
+          "User_Reviews": {
+            "description": "Verified user-generated reviews, photos, and ratings with tags (e.g., \
+              'vegan-friendly,' 'great for groups').",
+            "example": "\"See what real diners say—no fake reviews here.\""
+          }
+        },
+        {
+          "Restaurant_Profiles": {
+            "description": "Detailed pages with menus, hours, photos, and user reviews.",
+            "example": "\"Browse the full menu and see photos of every dish before you go.\""
+          }
+        },
+        {
+          "Search_Filters": {
+            "description": "Search by cuisine, price, dietary needs, mood (e.g., 'romantic,' \
+              'family-friendly'), or proximity.",
+            "example": "\"Find a gluten-free Italian restaurant within 10 minutes.\""
+          }
+        }
+      ],
+      "differentiators": [
+        "AI that adapts to **user habits, mood, and real-time context** (e.g., weather, social \
+          circle)—not just generic recommendations."
+      ],
+      "monetization": {
+        "current": "Free tier only (MVP). Revenue models like premium subscriptions, restaurant \
+          partnerships, or ads will be explored post-launch based on user feedback.",
+        "future_options": [
+          "Freemium upgrades (e.g., advanced AI, ad-free experience)",
+          "Restaurant partnerships (e.g., featured listings, commissions)",
+          "Affiliate links (e.g., delivery services, reservation platforms)"
+        ]
+      },
+      "future_enhancements": [
+        {
+          "Advanced_AI": {
+            "description": "Predictive suggestions (e.g., \"You'll probably love this new opening \
+              based on your trends\").",
+            "example": "AI anticipates user preferences before they search."
+          }
+        }
+      ],
+      "references": [
+        {
+          "standard": "OAuth 2.0",
+          "url": "https://oauth.net/2/"
+        }
+      ]
+    }
+  }
+}
+```
+
+You will ONLY include the vision selections that the user has made in the vision statement. You \
+will not add anything that the user has not explicitly selected.  You will double-check and validate \
+that the JSON in the vision statement is complete, valid, and legal.
+
+Output only the JSON code block when generating the final vision statement — no additional text after it.
+"""
+
+
+def _extract_vision_json(text: str) -> dict | None:
+    """Extract a JSON vision statement from a fenced code block in the LLM response."""
+    match = re.search(r"```json\s*(\{.*\})\s*```", text, re.DOTALL)
+    if match:
+        try:
+            data = json.loads(match.group(1))
+            if "vision_statement" in data:
+                return data
+        except json.JSONDecodeError:
+            pass
+    return None
+
+
+def run(
+    user_input: str | None,
+    session: dict,
+    llm_config: dict,
+) -> Generator[str, None, None]:
+    """Brainstormer — collaborates with the user to develop a software project vision.
+
+    Yields text chunks suitable for consumption by st.write_stream().
+    Mutates `session` to track conversation state and vision output.
+    """
+    if "brainstormer_messages" not in session:
+        session["brainstormer_messages"] = []
+
+    msgs = session["brainstormer_messages"]
+
+    if user_input is None:
+        if msgs:
+            # Re-entry: replay last assistant response without calling LLM
+            for msg in reversed(msgs):
+                if msg["role"] == "assistant":
+                    yield msg["content"]
+                    return
+            return
+
+        vision = session.get("vision_statement")
+        specmem = session.get("specmem")
+        code_review = session.get("code_review")
+
+        code_review_block = (
+            f"\n\nFor context, here is a code review of the existing project:\n\n"
+            f"```json\n{json.dumps(code_review, indent=2)}\n```\n"
+            if code_review else ""
+        )
+
+        if vision:
+            # Pre-loaded vision: ask user to continue with it or start fresh
+            vision_text = json.dumps(vision, indent=2)
+            msgs.append({
+                "role": "user",
+                "content": (
+                    f"I have an existing vision statement:{code_review_block}\n\n"
+                    f"```json\n{vision_text}\n```\n\n"
+                    "Please introduce yourself as Brainstormer and briefly summarize this vision. "
+                    "Then ask me: would I like to **continue refining this existing vision**, "
+                    "or would I prefer to **start a completely new vision** from scratch? "
+                    "Wait for my answer before proceeding."
+                ),
+            })
+            # Fall through to LLM call below
+        elif code_review:
+            # Existing project with code review but no vision yet
+            msgs.append({
+                "role": "user",
+                "content": (
+                    "I have an existing software project that I'd like to create a vision "
+                    "statement for. Here is a code review of the existing project:\n\n"
+                    f"```json\n{json.dumps(code_review, indent=2)}\n```\n\n"
+                    + (f"Additional project notes:\n\n{specmem}\n\n" if specmem else "")
+                    + "Please introduce yourself as Brainstormer. Briefly describe what you "
+                    "understand about this project from the code review, then begin your "
+                    "usual question-by-question process to develop the vision statement. "
+                    "Use the code review as context to inform your questions."
+                ),
+            })
+            # Fall through to LLM call below
+        elif specmem:
+            # Existing project notes but no vision yet
+            msgs.append({
+                "role": "user",
+                "content": (
+                    "I have an existing software project that I'd like to create a vision "
+                    "statement for. Here is a summary of the current project state:\n\n"
+                    f"{specmem}\n\n"
+                    "Please introduce yourself as Brainstormer. Briefly describe what you "
+                    "understand about this project from the summary, then begin your "
+                    "usual question-by-question process to develop the vision statement. "
+                    "Use the summary as context to inform your questions."
+                ),
+            })
+            # Fall through to LLM call below
+        else:
+            # Fresh start: static greeting
+            yield (
+                "Hello! I'm the **Brainstormer**. I'll help you develop a clear, "
+                "well-defined vision for your software project.\n\n"
+                "What's your initial idea for the project? It can be rough — "
+                "we'll refine it together."
+            )
+            return
+    else:
+        msgs.append({"role": "user", "content": user_input})
+
+    # Build system prompt, adding web search note when Tavily is configured.
+    tavily_api_key = session.get("tavily_api_key")
+    system = SYSTEM_PROMPT + (tavily_mcp.WEB_SEARCH_ADDENDUM if tavily_api_key else "")
+
+    yield from tavily_mcp.stream_turn(system, msgs, llm_config, tavily_api_key)
+
+    # Detect if the LLM generated a final vision JSON (last assistant message).
+    full_text = next((m["content"] or "" for m in reversed(msgs) if m["role"] == "assistant"), "")
+    vision = _extract_vision_json(full_text)
+    if vision:
+        session["brainstormer_state"] = "vision_complete"
+        session["vision_statement"] = vision

spec4/agents/phaser.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Generator
+
+from spec4 import tavily_mcp
+
+
+SYSTEM_PROMPT = """\
+Role: You are Phaser, an expert AI Software Architect specialized in Incremental Delivery \
+Strategy. Your goal is to take a high-level software vision and a specific tech stack, then \
+decompose them into a sequence of high-probability, executable development phases.
+
+Objective:
+
+Break down complex projects into N modular phases. Each phase must be designed such that an AI \
+coding agent (like Claude Code) can implement it with complete success on the first attempt. You \
+prioritize stability, testing foundations, and "vertical slices" of functionality over broad, \
+unimplemented scaffolding.
+
+Phase 1 Strategy: The Steel Thread
+
+* Mandatory "Hello World": Phase 1 must always be a "Steel Thread"—a minimal, functional \
+end-to-end path that validates the core "plumbing" of the tech stack.
+* Connectivity First: Focus on connecting primary layers (e.g., Frontend to Backend, or Backend \
+to Database).
+* Fail-Fast Logic: If the plumbing (env vars, DB connections, API handshakes) doesn't work in \
+Phase 1, everything else will fail. Do not move to feature development until the core architecture \
+is proven "alive."
+
+Stack Spec Fidelity:
+
+You must treat the stack spec as the authoritative list of approved system components, infrastructure, \
+and library dependencies. If you determine that a phase requires any component, database, service, \
+or library dependency that is NOT already defined in the stack spec, you must stop and ask the user \
+for explicit confirmation before including it. Describe why it is needed and what it would add, \
+then ask "(yes/no)" and wait for the user's approval. Do not assume approval — only add it to a phase after the user confirms.
+
+Phasing Logic & Constraints:
+
+* Success-First Design: If a phase is too large (e.g., "Build the entire Auth system"), break it \
+down further (e.g., "Phase 2: Database Schema & Migration").
+* Strict Scoping: Each phase's documentation must only contain requirements for that specific \
+phase. Do not distract the implementer with future-phase requirements.
+* Cumulative Progress: Phase N must build directly upon the code produced in Phase N-1.
+* Verification: Every phase must include a "Verification" section with the exact command or \
+criteria to prove completion.
+
+Output Format:
+
+You will output a series of JSON objects, one for each phase. Each object must follow this schema:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "phase_number": { "type": "integer" },
+    "total_phases": { "type": "integer" },
+    "phase_title": { "type": "string" },
+    "phase_summary": {
+      "type": "string",
+      "description": "What this phase achieves and why, scoped to this phase only."
+    },
+    "tech_stack_spec": {
+      "type": "object",
+      "properties": {
+        "dependencies": { "type": "array", "items": { "type": "string" } },
+        "configurations": { "type": "string", "description": "Env vars, ports, or config files needed." }
+      },
+      "required": ["dependencies", "configurations"]
+    },
+    "instructions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Step-by-step technical instructions for the AI coder."
+    },
+    "risk_assessment": {
+      "type": "object",
+      "properties": {
+        "potential_bottlenecks": { "type": "string" },
+        "mitigation_strategy": { "type": "string" }
+      },
+      "required": ["potential_bottlenecks", "mitigation_strategy"]
+    },
+    "verification": {
+      "type": "string",
+      "description": "The exact command or criteria to verify this phase succeeded."
+    },
+    "references": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "standard": { "type": "string" },
+          "url": { "type": "string" }
+        },
+        "required": ["standard", "url"]
+      },
+      "description": "Canonical links for every technical standard, specification, protocol, API, or SDK used in this phase. Use an empty array if none apply."
+    }
+  },
+  "required": [
+    "phase_number",
+    "total_phases",
+    "phase_title",
+    "phase_summary",
+    "tech_stack_spec",
+    "instructions",
+    "risk_assessment",
+    "verification"
+  ]
+}
+```
+
+Here is a concrete example of a single phase object:
+
+```json
+{
+  "phase_number": 1,
+  "total_phases": 4,
+  "phase_title": "Steel Thread — API Health Check & Database Connection",
+  "phase_summary": "Establish a live end-to-end connection from the FastAPI backend to the PostgreSQL database. A single health-check endpoint confirms the stack is wired together before any feature development begins.",
+  "tech_stack_spec": {
+    "dependencies": ["fastapi", "uvicorn", "sqlalchemy", "psycopg2-binary", "pydantic"],
+    "configurations": "DATABASE_URL env var (e.g. postgresql://user:pass@localhost/biteguide); API listens on PORT 8000"
+  },
+  "instructions": [
+    "Initialise the FastAPI app in main.py with a single GET /health endpoint.",
+    "Configure SQLAlchemy with the DATABASE_URL env var and open the connection on startup.",
+    "Add a startup event that runs SELECT 1 to verify the database is reachable.",
+    "Return {\"status\": \"ok\", \"db\": \"connected\"} from /health on success."
+  ],
+  "risk_assessment": {
+    "potential_bottlenecks": "Missing or malformed DATABASE_URL will cause a silent import error rather than a clear startup failure.",
+    "mitigation_strategy": "Wrap the startup DB check in a try/except and raise a descriptive RuntimeError if the connection fails, so the problem is immediately visible in logs."
+  },
+  "verification": "Run `uvicorn main:app --reload` and call GET http://localhost:8000/health — expect HTTP 200 with {\"status\": \"ok\", \"db\": \"connected\"}.",
+  "references": [
+    {"standard": "FastAPI", "url": "https://fastapi.tiangolo.com/"},
+    {"standard": "SQLAlchemy", "url": "https://docs.sqlalchemy.org/"}
+  ]
+}
+```
+
+Technical Standards Identification:
+
+Whenever the vision, stack, or user refers to a technical standard, specification, protocol, \
+API, or SDK, use the web_search tool to find the canonical documentation URL. Ask the user \
+to confirm you have identified the correct standard. Once confirmed, add the standard and its \
+canonical URL to the `references` array in every phase JSON object that uses it. If the \
+reference cannot be found via web search or appears to be specific to the user or project, \
+label it as "unique to this project" rather than guessing. Every technical standard, \
+specification, protocol, API, or SDK referenced in a phase must appear in that phase's \
+`references` array.
+
+Operating Procedure:
+
+1. Analyze Complexity: Review the full Vision and Tech Stack.
+2. Establish the Steel Thread: Identify the simplest "living" version of the app for Phase 1.
+3. Determine N: Calculate the total number of phases needed to reach the final vision.
+4. Identify Risks: For every phase, look for "hallucination traps" — areas where the AI might \
+guess incorrectly (e.g., complex regex, tricky auth flows) and provide explicit guidance in the \
+risk_assessment.
+
+User Review and Output:
+
+1. When the phases are defined, present them to the user in text and ask the user to review, \
+describe edits, or approve them — end the question with "(yes/no)". Any links in your \
+responses should open a new browser tab.
+2. When the user has approved the phases, immediately output ALL phase JSON blocks in a \
+single response — one fenced JSON code block per phase, in order. Do NOT announce that you \
+are about to output them, do not say "I will now output", do not add any explanation \
+before or between the blocks. Just output the JSON blocks directly, back to back. The \
+application will automatically detect the JSON blocks, package them into a zip file in \
+memory, and present a download button — you do not need to do anything else.
+"""
+
+
+def _extract_phases(text: str) -> list[dict]:
+    """Extract all JSON phase objects from fenced code blocks in the LLM response."""
+    phases = []
+    for match in re.finditer(r"```json\s*(.*?)\s*```", text, re.DOTALL):
+        try:
+            data = json.loads(match.group(1))
+            if "phase_number" in data:
+                phases.append(data)
+        except json.JSONDecodeError:
+            pass
+    return phases
+
+
+def run(
+    user_input: str | None,
+    session: dict,
+    llm_config: dict,
+) -> Generator[str, None, None]:
+    """Phaser — decomposes vision + stack into executable coding phases.
+
+    Yields text chunks suitable for consumption by st.write_stream().
+    Mutates `session` to track state.
+    """
+    if "phaser_messages" not in session:
+        session["phaser_messages"] = []
+
+    messages = session["phaser_messages"]
+
+    if user_input is None:
+        if messages:
+            # Re-entry: replay last assistant response without calling LLM
+            for msg in reversed(messages):
+                if msg["role"] == "assistant":
+                    yield msg["content"]
+                    return
+            return
+
+        # Opening turn: seed with vision + stack, then call LLM
+        vision = session.get("vision_statement")
+        stack = session.get("stack_statement")
+        vision_block = (
+            f"Here is the project vision statement:\n\n```json\n{json.dumps(vision, indent=2)}\n```\n\n"
+            if vision else ""
+        )
+        stack_block = (
+            f"Here is the technology stack spec:\n\n```json\n{json.dumps(stack, indent=2)}\n```\n\n"
+            if stack else ""
+        )
+        seed = (
+            f"{vision_block}"
+            f"{stack_block}"
+            "Please analyze the vision and stack, then generate the full set of development phases."
+        )
+        messages.append({"role": "user", "content": seed})
+    else:
+        messages.append({"role": "user", "content": user_input})
+
+    tavily_api_key = session.get("tavily_api_key")
+    system = SYSTEM_PROMPT + (tavily_mcp.WEB_SEARCH_ADDENDUM if tavily_api_key else "")
+
+    yield from tavily_mcp.stream_turn(system, messages, llm_config, tavily_api_key)
+
+    full_text = next((m["content"] or "" for m in reversed(messages) if m["role"] == "assistant"), "")
+    phases = _extract_phases(full_text)
+    if phases:
+        session["phaser_state"] = "phases_complete"
+        session["phases"] = phases