spec4 0.1.0__tar.gz

spec4-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.3
+Name: spec4
+Version: 0.1.0
+Summary: AI-assisted software project planning — from idea to executable coding phases
+Author: Robert Crowe
+Author-email: Robert Crowe <crowe3555@gmail.com>
+License: Apache-2.0
+Requires-Dist: a2a-sdk>=0.3.24
+Requires-Dist: dash>=2.17.0
+Requires-Dist: dash-iconify>=0.1.2
+Requires-Dist: dash-mantine-components>=0.14.0
+Requires-Dist: litellm>=1.82.0
+Requires-Dist: mcp>=1.26.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Spec4 AI
+
+> AI-assisted software project planning — from idea to executable coding phases.
+
+Spec4 is a Dash app (using Dash Mantine Components) that guides you through three stages of project planning using a pipeline of specialised LLM agents. Start with a rough idea and finish with a set of structured, ordered development phases ready to hand to an AI coding agent like Claude Code.
+
+---
+
+## Installation
+
+**Option 1 — Install from PyPI (recommended for most users):**
+
+```bash
+uv tool install spec4
+spec4
+```
+
+**Option 2 — Run from source (for contributors and developers):**
+
+```bash
+git clone https://github.com/robertcrowe/spec4
+cd spec4
+make spec4
+```
+
+The app will be available at [http://localhost:8050](http://localhost:8050) in both cases.
+
+---
+
+## Features
+
+- **Four-stage planning pipeline** — Reviewer (optional) → Brainstormer → StackAdvisor → Phaser
+- **Any LLM provider** — works with OpenAI, Anthropic, Google Gemini, Cohere, and Mistral via LiteLLM
+- **Web search grounding** — all agents can search the web via Tavily to find canonical documentation
+- **Saved credentials** — optionally remember your provider, model, and API keys in the browser (localStorage via `dcc.Store` — never sent to or stored on the server)
+- **Incremental output** — each agent produces a downloadable JSON or ZIP file you can reuse in a later session
+- **Jump-in anywhere** — start at StackAdvisor or Phaser by uploading previously saved output
+- **Project persistence** — artifacts saved to a `.spec4/` folder inside your chosen project directory
+
+---
+
+## Agents
+
+### 🔍 Reviewer *(optional)*
+Analyzes an existing project directory to understand its architecture, technology stack, and coding style. Results inform Brainstormer and StackAdvisor when working on brownfield projects. Produces `code_review.json`.
+
+### 🧠 Brainstormer
+Develops a clear project vision through focused, one-at-a-time questions. Identifies technical standards via web search and embeds canonical documentation links in the output. Produces `vision.json`.
+
+### ⚙️ StackAdvisor
+Recommends languages, frameworks, hosting, and infrastructure based on the vision. Compares options, explains trade-offs, and uses web search to ground every recommendation. Produces `stack.json`.
+
+### 📋 Phaser
+Decomposes the vision and stack into an ordered sequence of development phases:
+
+- **Phase 1 is always a steel thread** — a minimal end-to-end path that validates the core architecture
+- **Each phase builds on the previous one**
+- **Stack spec fidelity** — confirms before adding any dependency not in the stack spec
+- **Verification criteria** — every phase includes the exact command needed to confirm it succeeded
+
+Produces `phases.zip` with one JSON file per phase.
+
+---
+
+## Requirements
+
+- Python 3.12+
+- **[uv](https://docs.astral.sh/uv/) package manager**
+- An API key for at least one supported LLM provider
+- _(Optional)_ A [Tavily](https://tavily.com/) API key for web search
+
+---
+
+## Installation & first run
+
+```bash
+git clone <repo-url>
+cd spec4
+make spec4
+```
+
+`make spec4` runs `uv sync` (which creates a `.venv` in the project directory and installs all
+dependencies into it) and then launches the app. All packages stay inside `.venv` — nothing is
+installed into your global Python.
+
+Then open [http://localhost:8050](http://localhost:8050) in your browser.
+
+> **Subsequent runs:** `make run` (or `uv run python src/spec4/app.py`) reuses the existing `.venv`.
+
+---
+
+## Usage
+
+1. **Select a project directory** — new or existing; artifacts are saved to `.spec4/` inside it.
+2. **Connect** — select a provider, enter your API key, and choose a model. Optionally add a Tavily key for web search.
+3. **Choose a starting point** — pick an agent to begin with.
+4. **Plan** — chat with each agent. When an agent completes, download the result and continue to the next agent.
+
+### Picking up where you left off
+
+Each session auto-saves to `.spec4/` inside your project directory. On a future visit, select the same directory and previously completed artifacts will be loaded automatically. You can also upload JSON files manually on the agent-select screen.
+
+---
+
+## Project structure
+
+```
+src/spec4/
+├── app.py                  # Dash entry point — app wiring, root layout, page render
+├── app_constants.py        # Shared constants (theme, routes, fonts)
+├── session.py              # Session defaults, agent runner, artifact persistence
+├── layouts.py              # All page layout functions
+├── callbacks.py            # All Dash server-side callbacks
+├── providers.py            # Provider/model registry, live model fetching
+├── tavily_mcp.py           # Tavily web search integration
+├── project_manager.py      # .spec4/ artifact persistence
+├── a2a_bus.py              # In-memory A2A task bus
+└── agents/
+    ├── reviewer.py         # Code review agent
+    ├── brainstormer.py     # Vision development agent
+    ├── stack_advisor.py    # Technology stack recommendation agent
+    └── phaser.py           # Incremental phase planning agent
+tests/                      # pytest test suite
+Makefile                    # Common commands
+```
+
+---
+
+## Development
+
+```bash
+make spec4       # First-time setup: create .venv, install deps, and launch
+make install     # Create .venv and install all dependencies (uv sync)
+make run         # Start the app (http://localhost:8050)
+make dev         # Start with debug/hot-reload enabled
+make test        # Run tests
+make lint        # Lint check with ruff
+make serve       # Production server via gunicorn (requires: uv add gunicorn)
+
+# Add a dependency (always use uv so it stays in .venv)
+uv add <package>
+uv add --dev <package>
+```
+
+---
+
+## Supported providers
+
+| Provider | Models fetched from |
+|----------|-------------------|
+| OpenAI | `api.openai.com/v1/models` |
+| Anthropic | `api.anthropic.com/v1/models` |
+| Google Gemini | `generativelanguage.googleapis.com` |
+| Cohere | `api.cohere.com/v2/models` |
+| Mistral | `api.mistral.ai/v1/models` |
+
+Models are fetched live from each provider's API when you connect, with a hardcoded fallback list if the API is unavailable.
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE) for details.

spec4-0.1.0/README.md

@@ -0,0 +1,163 @@
+# Spec4 AI
+
+> AI-assisted software project planning — from idea to executable coding phases.
+
+Spec4 is a Dash app (using Dash Mantine Components) that guides you through three stages of project planning using a pipeline of specialised LLM agents. Start with a rough idea and finish with a set of structured, ordered development phases ready to hand to an AI coding agent like Claude Code.
+
+---
+
+## Installation
+
+**Option 1 — Install from PyPI (recommended for most users):**
+
+```bash
+uv tool install spec4
+spec4
+```
+
+**Option 2 — Run from source (for contributors and developers):**
+
+```bash
+git clone https://github.com/robertcrowe/spec4
+cd spec4
+make spec4
+```
+
+The app will be available at [http://localhost:8050](http://localhost:8050) in both cases.
+
+---
+
+## Features
+
+- **Four-stage planning pipeline** — Reviewer (optional) → Brainstormer → StackAdvisor → Phaser
+- **Any LLM provider** — works with OpenAI, Anthropic, Google Gemini, Cohere, and Mistral via LiteLLM
+- **Web search grounding** — all agents can search the web via Tavily to find canonical documentation
+- **Saved credentials** — optionally remember your provider, model, and API keys in the browser (localStorage via `dcc.Store` — never sent to or stored on the server)
+- **Incremental output** — each agent produces a downloadable JSON or ZIP file you can reuse in a later session
+- **Jump-in anywhere** — start at StackAdvisor or Phaser by uploading previously saved output
+- **Project persistence** — artifacts saved to a `.spec4/` folder inside your chosen project directory
+
+---
+
+## Agents
+
+### 🔍 Reviewer *(optional)*
+Analyzes an existing project directory to understand its architecture, technology stack, and coding style. Results inform Brainstormer and StackAdvisor when working on brownfield projects. Produces `code_review.json`.
+
+### 🧠 Brainstormer
+Develops a clear project vision through focused, one-at-a-time questions. Identifies technical standards via web search and embeds canonical documentation links in the output. Produces `vision.json`.
+
+### ⚙️ StackAdvisor
+Recommends languages, frameworks, hosting, and infrastructure based on the vision. Compares options, explains trade-offs, and uses web search to ground every recommendation. Produces `stack.json`.
+
+### 📋 Phaser
+Decomposes the vision and stack into an ordered sequence of development phases:
+
+- **Phase 1 is always a steel thread** — a minimal end-to-end path that validates the core architecture
+- **Each phase builds on the previous one**
+- **Stack spec fidelity** — confirms before adding any dependency not in the stack spec
+- **Verification criteria** — every phase includes the exact command needed to confirm it succeeded
+
+Produces `phases.zip` with one JSON file per phase.
+
+---
+
+## Requirements
+
+- Python 3.12+
+- **[uv](https://docs.astral.sh/uv/) package manager**
+- An API key for at least one supported LLM provider
+- _(Optional)_ A [Tavily](https://tavily.com/) API key for web search
+
+---
+
+## Installation & first run
+
+```bash
+git clone <repo-url>
+cd spec4
+make spec4
+```
+
+`make spec4` runs `uv sync` (which creates a `.venv` in the project directory and installs all
+dependencies into it) and then launches the app. All packages stay inside `.venv` — nothing is
+installed into your global Python.
+
+Then open [http://localhost:8050](http://localhost:8050) in your browser.
+
+> **Subsequent runs:** `make run` (or `uv run python src/spec4/app.py`) reuses the existing `.venv`.
+
+---
+
+## Usage
+
+1. **Select a project directory** — new or existing; artifacts are saved to `.spec4/` inside it.
+2. **Connect** — select a provider, enter your API key, and choose a model. Optionally add a Tavily key for web search.
+3. **Choose a starting point** — pick an agent to begin with.
+4. **Plan** — chat with each agent. When an agent completes, download the result and continue to the next agent.
+
+### Picking up where you left off
+
+Each session auto-saves to `.spec4/` inside your project directory. On a future visit, select the same directory and previously completed artifacts will be loaded automatically. You can also upload JSON files manually on the agent-select screen.
+
+---
+
+## Project structure
+
+```
+src/spec4/
+├── app.py                  # Dash entry point — app wiring, root layout, page render
+├── app_constants.py        # Shared constants (theme, routes, fonts)
+├── session.py              # Session defaults, agent runner, artifact persistence
+├── layouts.py              # All page layout functions
+├── callbacks.py            # All Dash server-side callbacks
+├── providers.py            # Provider/model registry, live model fetching
+├── tavily_mcp.py           # Tavily web search integration
+├── project_manager.py      # .spec4/ artifact persistence
+├── a2a_bus.py              # In-memory A2A task bus
+└── agents/
+    ├── reviewer.py         # Code review agent
+    ├── brainstormer.py     # Vision development agent
+    ├── stack_advisor.py    # Technology stack recommendation agent
+    └── phaser.py           # Incremental phase planning agent
+tests/                      # pytest test suite
+Makefile                    # Common commands
+```
+
+---
+
+## Development
+
+```bash
+make spec4       # First-time setup: create .venv, install deps, and launch
+make install     # Create .venv and install all dependencies (uv sync)
+make run         # Start the app (http://localhost:8050)
+make dev         # Start with debug/hot-reload enabled
+make test        # Run tests
+make lint        # Lint check with ruff
+make serve       # Production server via gunicorn (requires: uv add gunicorn)
+
+# Add a dependency (always use uv so it stays in .venv)
+uv add <package>
+uv add --dev <package>
+```
+
+---
+
+## Supported providers
+
+| Provider | Models fetched from |
+|----------|-------------------|
+| OpenAI | `api.openai.com/v1/models` |
+| Anthropic | `api.anthropic.com/v1/models` |
+| Google Gemini | `generativelanguage.googleapis.com` |
+| Cohere | `api.cohere.com/v2/models` |
+| Mistral | `api.mistral.ai/v1/models` |
+
+Models are fetched live from each provider's API when you connect, with a hardcoded fallback list if the API is unavailable.
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE) for details.

spec4-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "spec4"
+version = "0.1.0"
+description = "AI-assisted software project planning — from idea to executable coding phases"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Robert Crowe", email = "crowe3555@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "a2a-sdk>=0.3.24",
+    "dash>=2.17.0",
+    "dash-iconify>=0.1.2",
+    "dash-mantine-components>=0.14.0",
+    "litellm>=1.82.0",
+    "mcp>=1.26.0",
+]
+
+[project.scripts]
+spec4 = "spec4.app:main"
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-cov>=7.1.0",
+]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "Makefile.publish",
+    "dist/",
+]

spec4-0.1.0/src/spec4/__init__.py

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

spec4-0.1.0/src/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