v0.2.0: production infrastructure — spec-first generators, security validator, ArtifactBundle

Dockerfile

@@ -2,6 +2,11 @@ FROM python:3.11-slim
 
 WORKDIR /app
 
+# Install agent-generator from the repo (includes all production infrastructure)
+COPY agent_generator_pkg/ /tmp/agent-generator-pkg/
+RUN pip install --no-cache-dir /tmp/agent-generator-pkg/ && rm -rf /tmp/agent-generator-pkg/
+
+# Install web dependencies
 COPY requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
 

agent_generator_pkg/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2025 ruslanmv.com
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

agent_generator_pkg/README.md

@@ -0,0 +1,174 @@
+<p align="left">
+  <img src="https://github.com/ruslanmv/agent-generator/blob/master/docs/images/logo.png" alt="Agent-Generator Logo" width="300">
+</p>
+
+# agent-generator
+
+**Create AI agents from a single sentence.**
+
+[![PyPI](https://img.shields.io/pypi/v/agent-generator.svg)](https://pypi.org/project/agent-generator/)
+[![Python 3.10+](https://img.shields.io/pypi/pyversions/agent-generator.svg)](https://pypi.org/project/agent-generator/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Try it](https://img.shields.io/badge/demo-Hugging%20Face-yellow)](https://huggingface.co/spaces/ruslanmv/agent-generator)
+<a href="https://github.com/agent-matrix/matrix-hub"><img src="https://img.shields.io/badge/Powered%20by-matrix--hub-brightgreen" alt="Powered by matrix-hub"></a>
+
+---
+
+## What does it do?
+
+You type what you want. You get a complete project.
+
+```bash
+agent-generator "Build a research team with a researcher and a writer" -f crewai
+```
+
+That's it. You now have working Python code with agents, tasks, and tools.
+
+---
+
+## Try it online
+
+No install needed. Open the demo and start building:
+
+**https://huggingface.co/spaces/ruslanmv/agent-generator**
+
+---
+
+## Install
+
+```bash
+pip install agent-generator
+```
+
+That gives you the CLI and all core features. Python 3.10+ required.
+
+**Optional extras:**
+
+```bash
+pip install "agent-generator[openai]"     # OpenAI provider
+pip install "agent-generator[all]"        # All providers + frameworks
+```
+
+---
+
+## Quick start
+
+### Step 1 -- Set credentials (pick one)
+
+```bash
+# Option A: WatsonX (default)
+export WATSONX_API_KEY=your-key
+export WATSONX_PROJECT_ID=your-project-id
+
+# Option B: OpenAI
+export OPENAI_API_KEY=sk-your-key
+export AGENTGEN_PROVIDER=openai
+```
+
+### Step 2 -- Generate
+
+```bash
+# CrewAI team
+agent-generator "Research team that finds papers and writes summaries" -f crewai -o team.py
+
+# LangGraph pipeline
+agent-generator "ETL pipeline: extract, transform, load" -f langgraph -o pipeline.py
+
+# WatsonX YAML agent
+agent-generator "Customer support assistant" -f watsonx_orchestrate -o support.yaml
+
+# Just test it (no credentials needed)
+agent-generator "Hello world agent" -f crewai --dry-run
+```
+
+### Step 3 -- Run
+
+```bash
+python team.py
+```
+
+---
+
+## Supported frameworks
+
+| Framework | What you get |
+|-----------|-------------|
+| **CrewAI** | `crew.py` + `agents.yaml` + `tasks.yaml` + tools + tests |
+| **LangGraph** | `graph.py` with `StateGraph` and typed state |
+| **WatsonX Orchestrate** | `agent.yaml` ready for `orchestrate agents import` |
+| **CrewAI Flow** | Flow class with `@start` / `@listen` |
+| **ReAct** | Reasoning loop with tool registry |
+
+---
+
+## Built-in tools
+
+Your agents can use these out of the box:
+
+| Tool | What it does |
+|------|-------------|
+| `web_search` | Search the web |
+| `pdf_reader` | Read PDF files |
+| `http_client` | Call APIs |
+| `sql_query` | Query databases |
+| `file_writer` | Save files |
+| `vector_search` | Semantic search |
+
+---
+
+## Web UI
+
+A visual wizard that guides you step by step:
+
+```bash
+uvicorn agent_generator.wsgi:app --port 8000
+```
+
+Open **http://localhost:8000** -- describe your agents, pick a framework, download a ZIP.
+
+Works with local LLMs (Ollama), remote LLMs (OllaBridge), or cloud APIs (OpenAI).
+
+---
+
+## CLI options
+
+```
+agent-generator "your description" [options]
+```
+
+| Flag | What it does |
+|------|-------------|
+| `-f crewai` | Pick framework: `crewai`, `langgraph`, `watsonx_orchestrate`, `crewai_flow`, `react` |
+| `-o file.py` | Save to file (otherwise prints to screen) |
+| `--dry-run` | Generate without calling any LLM |
+| `--mcp` | Add a FastAPI server wrapper |
+| `-p openai` | Use OpenAI instead of WatsonX |
+| `--show-cost` | Show estimated cost before generating |
+
+---
+
+## Docker
+
+```bash
+docker build -t agent-generator .
+docker run -e WATSONX_API_KEY=... -p 8000:8000 agent-generator
+```
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/ruslanmv/agent-generator.git
+cd agent-generator
+pip install -e ".[dev,all]"
+pytest                # run tests
+ruff check src/       # lint
+mkdocs serve          # docs
+```
+
+---
+
+## License
+
+Apache 2.0 -- PRs and issues welcome.

agent_generator_pkg/pyproject.toml

@@ -0,0 +1,145 @@
+# ────────────────────────────────────────────────────────────────
+#  pyproject.toml  •  build + metadata for agent-generator
+# ────────────────────────────────────────────────────────────────
+
+[build-system]
+requires      = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name            = "agent-generator"
+version         = "0.2.0"
+description     = "Turn plain-English requirements into production-ready multi-agent AI projects (CrewAI, LangGraph, WatsonX Orchestrate)."
+readme          = "README.md"
+requires-python = ">=3.10"
+license         = { file = "LICENSE" }
+authors         = [
+  { name = "Ruslan M. V.", email = "contact@ruslanmv.com" }
+]
+keywords = [
+  "multi-agent",
+  "crewai",
+  "langgraph",
+  "watsonx",
+  "orchestrate",
+  "LLM",
+  "code-generation",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Framework :: FastAPI",
+  "Topic :: Software Development :: Code Generators",
+  "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+
+# -----------------------------------------------------------------
+# Core runtime dependencies
+# -----------------------------------------------------------------
+dependencies = [
+  "pydantic>=2.12,<3",
+  "pydantic-settings>=2.13,<3",
+  "python-dotenv>=1.0",
+  "typer>=0.24,<1",
+  "jinja2>=3.1,<4",
+  "requests>=2.33,<3",
+  "rich>=14.0,<15",
+  "structlog>=25.0,<26",
+  "pyyaml>=6.0,<7",
+]
+
+# -----------------------------------------------------------------
+# Optional extras
+# -----------------------------------------------------------------
+[project.optional-dependencies]
+openai = [
+  "openai>=2.30,<3",
+  "tiktoken>=0.12,<1",
+]
+crewai = [
+  "crewai>=1.12,<2",
+]
+langgraph = [
+  "langgraph>=1.1,<2",
+  "langchain-core>=0.1",
+]
+web = [
+  "fastapi>=0.135,<1",
+  "uvicorn>=0.42,<1",
+  "python-multipart>=0.0.18",
+  "requests>=2.33,<3",
+]
+all = [
+  "agent-generator[openai,crewai,langgraph,web]",
+]
+dev = [
+  "pytest>=8.2",
+  "pytest-xdist>=3.5",
+  "pytest-asyncio>=0.24",
+  "mypy>=1.10",
+  "ruff>=0.4",
+  "black>=24.4",
+  "isort>=5.0",
+  "pytest-cov>=5.0",
+  "pre-commit>=3.7",
+  "mkdocs>=1.6",
+  "mkdocs-material>=9.5",
+]
+
+# -----------------------------------------------------------------
+# CLI entry-point
+# -----------------------------------------------------------------
+[project.scripts]
+agent-generator = "agent_generator.cli:_main"
+
+# -----------------------------------------------------------------
+# URLs
+# -----------------------------------------------------------------
+[project.urls]
+Homepage   = "https://github.com/ruslanmv/agent-generator"
+Repository = "https://github.com/ruslanmv/agent-generator"
+Issues     = "https://github.com/ruslanmv/agent-generator/issues"
+
+# -----------------------------------------------------------------
+# Ruff configuration
+# -----------------------------------------------------------------
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+ignore = ["F841", "E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["agent_generator"]
+
+# -----------------------------------------------------------------
+# Pytest configuration
+# -----------------------------------------------------------------
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+# -----------------------------------------------------------------
+# MyPy configuration
+# -----------------------------------------------------------------
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+
+# -----------------------------------------------------------------
+# Hatchling configuration
+# -----------------------------------------------------------------
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_generator"]

agent_generator_pkg/src/agent_generator/__init__.py

@@ -0,0 +1,40 @@
+# ────────────────────────────────────────────────────────────────
+#  src/agent_generator/__init__.py
+# ────────────────────────────────────────────────────────────────
+"""
+🎉 **agent‑generator**
+
+This package turns plain‑English requirements into ready‑to‑run multi‑agent
+teams for CrewAI, LangGraph, ReAct, or watsonx Orchestrate.
+
+Public surface
+--------------
+* `__version__`           – semantic‑version string
+* `get_settings()`        – singleton accessor to global Settings
+* `Settings`              – Pydantic config model (sub‑module import)
+* `FRAMEWORKS`            – mapping name → framework generator class
+* `PROVIDERS`             – mapping name → LLM provider class
+"""
+
+from __future__ import annotations
+
+# ------------------------------------------------------------------ #
+# Version
+# ------------------------------------------------------------------ #
+__version__: str = "0.2.0"
+
+# ------------------------------------------------------------------ #
+# Surface imports (lazy‑safe)
+# ------------------------------------------------------------------ #
+from agent_generator.config import Settings, get_settings  # noqa: E402
+from agent_generator.frameworks import FRAMEWORKS  # noqa: E402
+from agent_generator.providers import PROVIDERS  # noqa: E402
+
+# Anything else you’d like to expose at package level goes here
+__all__ = [
+    "__version__",
+    "Settings",
+    "get_settings",
+    "PROVIDERS",
+    "FRAMEWORKS",
+]

agent_generator_pkg/src/agent_generator/application/build_service.py

@@ -0,0 +1,125 @@
+"""Build service: take a validated ProjectSpec and produce generated files."""
+from __future__ import annotations
+
+import ast
+from typing import Any
+
+from agent_generator.config import Settings, get_settings_lenient
+from agent_generator.domain.project_spec import ProjectSpec
+from agent_generator.domain.artifact_bundle import ArtifactBundle, GeneratedFile, ValidationIssue
+from agent_generator.frameworks import FRAMEWORKS
+
+
+def _spec_to_mermaid(spec: ProjectSpec) -> str:
+    """Generate a Mermaid diagram directly from a ProjectSpec (no Workflow needed)."""
+    lines = ["graph TD"]
+    for t in spec.tasks:
+        label = t.description[:60].replace('"', "'")
+        lines.append(f'    {t.id}["{label}"]')
+    for t in spec.tasks:
+        for dep in t.depends_on:
+            lines.append(f"    {dep} --> {t.id}")
+    return "\n".join(lines)
+
+
+def build(
+    spec: ProjectSpec,
+    mcp: bool = False,
+) -> ArtifactBundle:
+    """Build a project from a validated ProjectSpec.
+
+    Returns an ArtifactBundle with generated files, manifest, warnings, and errors.
+    """
+    from agent_generator.application.validation_service import validate_artifact
+
+    framework_name = spec.framework.value
+    if framework_name not in FRAMEWORKS:
+        framework_name = "crewai"
+
+    settings = get_settings_lenient()
+
+    # Generate code directly from spec (no Workflow adapter)
+    generator = FRAMEWORKS[framework_name]()
+    code = generator.generate_from_spec(spec, settings, mcp=mcp or spec.runtime.mcp_wrapper)
+    diagram = _spec_to_mermaid(spec)
+
+    # Build file list
+    project_name = spec.name
+    generated_files: list[GeneratedFile] = []
+
+    ext = generator.file_extension
+    if ext == "yaml":
+        generated_files.append(GeneratedFile(
+            path=f"{project_name}.yaml",
+            content=code,
+            language="yaml",
+        ))
+    else:
+        generated_files.append(GeneratedFile(
+            path=f"src/{project_name}/main.py",
+            content=code,
+            language="python",
+        ))
+        generated_files.append(GeneratedFile(
+            path=f"src/{project_name}/__init__.py",
+            content=f'"""Generated {project_name} package."""\n',
+            language="python",
+        ))
+
+    generated_files.append(GeneratedFile(
+        path="README.md",
+        content=(
+            f"# {project_name}\n\n{spec.description}\n\n"
+            f"Framework: {framework_name}\n\n"
+            f"Generated by [agent-generator](https://github.com/ruslanmv/agent-generator).\n"
+        ),
+        language="markdown",
+    ))
+
+    # Syntax validation
+    errors: list[ValidationIssue] = []
+    warnings: list[ValidationIssue] = []
+    for f in generated_files:
+        if f.path.endswith(".py"):
+            try:
+                ast.parse(f.content)
+            except SyntaxError as e:
+                errors.append(ValidationIssue(
+                    level="error",
+                    message=f"{f.path}: Syntax error line {e.lineno}: {e.msg}",
+                ))
+
+    # Build manifest
+    manifest: dict[str, Any] = {
+        "framework": framework_name,
+        "diagram": diagram,
+        "generator_version": "0.2.0",
+        "project_name": project_name,
+    }
+
+    artifact = ArtifactBundle(
+        files=generated_files,
+        manifest=manifest,
+        warnings=warnings,
+        errors=errors,
+    )
+
+    # Run security validation
+    artifact = validate_artifact(artifact)
+
+    return artifact
+
+
+def build_dict(spec: ProjectSpec, mcp: bool = False) -> dict[str, Any]:
+    """Build and return a backward-compatible dict (for CLI/web)."""
+    artifact = build(spec, mcp=mcp)
+    return {
+        "files": {f.path: f.content for f in artifact.files},
+        "diagram": artifact.manifest.get("diagram", ""),
+        "framework": artifact.manifest.get("framework", spec.framework.value),
+        "warnings": [w.message for w in artifact.warnings],
+        "errors": [e.message for e in artifact.errors],
+        "spec": spec.model_dump(),
+        "manifest": artifact.manifest,
+        "valid": artifact.valid,
+    }

agent_generator_pkg/src/agent_generator/application/planning_service.py

@@ -0,0 +1,152 @@
+"""Unified planning service used by CLI and Web API."""
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from agent_generator.domain.project_spec import (
+    AgentSpec,
+    ArtifactMode,
+    FrameworkChoice,
+    LLMSpec,
+    ProjectSpec,
+    RuntimeSpec,
+    TaskSpec,
+    ToolSpec,
+)
+from agent_generator.planners.keyword_planner import KeywordPlanner
+from agent_generator.planners.spec_normalizer import SpecNormalizer
+from agent_generator.validators.spec_validator import SpecValidator
+
+_keyword_planner = KeywordPlanner()
+_normalizer = SpecNormalizer()
+_validator = SpecValidator()
+
+
+def _slugify(text: str) -> str:
+    slug = re.sub(r"[^a-z0-9\s-]", "", text.lower())
+    slug = re.sub(r"[\s_]+", "-", slug.strip())
+    return slug[:40] or "agent-project"
+
+
+def _extract_roles(prompt: str, hints: dict) -> list[dict]:
+    """Extract agent roles from keyword hints + prompt analysis."""
+    roles = hints.get("suggested_roles", [])
+    if not roles:
+        roles = ["assistant"]
+    agents = []
+    for role in roles[:4]:
+        agents.append(
+            {
+                "id": role.replace(" ", "_").lower(),
+                "role": role.replace("_", " ").title(),
+                "goal": f"Handle {role}-related tasks effectively",
+                "backstory": f"An experienced {role} with deep domain expertise.",
+                "tools": hints.get("suggested_tools", [])[:2],
+            }
+        )
+    return agents
+
+
+def _extract_tasks(prompt: str, agents: list[dict]) -> list[dict]:
+    """Extract tasks from prompt sentences."""
+    sentences = [
+        s.strip()
+        for s in re.split(r"[.!?]+", prompt)
+        if s.strip() and len(s.strip()) > 5
+    ]
+    if not sentences:
+        sentences = [prompt.strip()]
+    tasks = []
+    for i, sentence in enumerate(sentences[:8]):
+        agent_idx = i % len(agents)
+        task_id = f"task_{i + 1}"
+        tasks.append(
+            {
+                "id": task_id,
+                "description": sentence,
+                "agent_id": agents[agent_idx]["id"],
+                "expected_output": f"Completed: {sentence[:80]}",
+                "depends_on": [f"task_{i}"] if i > 0 else [],
+            }
+        )
+    return tasks
+
+
+def plan(
+    prompt: str,
+    framework: Optional[str] = None,
+    artifact_mode: Optional[str] = None,
+    provider: Optional[str] = None,
+    mcp: bool = False,
+    use_llm: bool = False,
+) -> tuple[ProjectSpec, list[str]]:
+    """Plan a project from a natural language prompt.
+
+    Returns (validated_spec, warnings).
+    This is the ONLY entry point for creating a ProjectSpec.
+    Used by both CLI and Web API.
+
+    Parameters
+    ----------
+    use_llm : bool
+        If True *and* a provider is given, attempt LLM-based planning
+        before falling back to the keyword-based planner.
+    """
+    # Step 1: keyword classification (always runs -- provides hints)
+    hints = _keyword_planner.classify(
+        prompt, user_framework=framework, user_artifact_mode=artifact_mode
+    )
+
+    # ── Optional LLM planning stage ──────────────────────────────
+    if use_llm and provider:
+        try:
+            from agent_generator.providers import PROVIDERS
+
+            if provider in PROVIDERS:
+                from agent_generator.config import get_settings_lenient
+                from agent_generator.planners.llm_planner import LLMPlanner
+
+                provider_inst = PROVIDERS[provider](get_settings_lenient())
+                llm_planner = LLMPlanner(provider_inst)
+                llm_spec = llm_planner.plan(prompt, hints)
+                if llm_spec is not None:
+                    spec, warnings = _normalizer.normalize(llm_spec)
+                    validation = _validator.validate(spec)
+                    return spec, warnings + validation.warnings
+        except Exception:
+            pass  # Fall through to keyword-based planning
+
+    # ── Keyword-based fallback (always works, no credentials) ────
+    fw = hints["suggested_framework"]
+    mode = hints["suggested_artifact_mode"]
+    agents = _extract_roles(prompt, hints)
+    tasks = _extract_tasks(prompt, agents)
+    tools = [
+        {"id": t, "template": t, "inputs": {}}
+        for t in hints.get("suggested_tools", [])
+    ]
+
+    spec = ProjectSpec(
+        name=_slugify(prompt[:50]),
+        description=prompt[:500],
+        framework=FrameworkChoice(fw),
+        artifact_mode=ArtifactMode(mode),
+        llm=LLMSpec(provider=provider or "watsonx"),
+        agents=[AgentSpec(**a) for a in agents],
+        tasks=[TaskSpec(**t) for t in tasks],
+        tools=[ToolSpec(**t) for t in tools],
+        runtime=RuntimeSpec(mcp_wrapper=mcp),
+    )
+
+    # Step 3: normalize (fix references, apply defaults)
+    spec, norm_warnings = _normalizer.normalize(spec)
+
+    # Step 4: validate
+    validation = _validator.validate(spec)
+    all_warnings = norm_warnings + validation.warnings
+
+    if not validation.valid:
+        all_warnings.extend(validation.errors)
+
+    return spec, all_warnings

agent_generator_pkg/src/agent_generator/application/release_service.py

@@ -0,0 +1,16 @@
+"""Release service — package artifacts for distribution."""
+from __future__ import annotations
+
+from io import BytesIO
+from zipfile import ZipFile, ZIP_DEFLATED
+
+from agent_generator.domain.artifact_bundle import ArtifactBundle
+
+
+def build_zip_bytes(artifact: ArtifactBundle, project_name: str = "project") -> bytes:
+    """Create a ZIP archive from an ArtifactBundle."""
+    buf = BytesIO()
+    with ZipFile(buf, "w", ZIP_DEFLATED) as zf:
+        for file in artifact.files:
+            zf.writestr(f"{project_name}/{file.path}", file.content)
+    return buf.getvalue()

agent_generator_pkg/src/agent_generator/application/validation_service.py

@@ -0,0 +1,26 @@
+"""Central validation service for specs and artifacts."""
+from __future__ import annotations
+
+from agent_generator.domain.project_spec import ProjectSpec
+from agent_generator.domain.artifact_bundle import ArtifactBundle
+from agent_generator.validators.spec_validator import SpecValidator, ValidationResult
+from agent_generator.validators.security_validator import SecurityValidator
+
+_spec_validator = SpecValidator()
+_security_validator = SecurityValidator()
+
+
+def validate_spec(spec: ProjectSpec) -> ValidationResult:
+    """Validate a ProjectSpec. Returns ValidationResult with errors/warnings."""
+    return _spec_validator.validate(spec)
+
+
+def validate_artifact(artifact: ArtifactBundle) -> ArtifactBundle:
+    """Run security validation on generated artifacts. Mutates and returns the bundle."""
+    issues = _security_validator.validate(artifact)
+    for issue in issues:
+        if issue.level == "error":
+            artifact.errors.append(issue)
+        else:
+            artifact.warnings.append(issue)
+    return artifact

agent_generator_pkg/src/agent_generator/cli.py

@@ -0,0 +1,245 @@
+# ────────────────────────────────────────────────────────────────
+#  src/agent_generator/cli.py
+# ────────────────────────────────────────────────────────────────
+"""
+Command-line interface for **agent-generator**.
+Core command
+------------
+
+agent-generator "Build me a social-media team" \
+  --framework crewai \
+  --provider watsonx \
+  --output social_team.py --mcp
+
+The CLI glues together:
+
+* Settings (env + defaults)        → `config.py`
+* Prompt parser                    → `utils.parser`
+* Provider registry                → `providers.__init__`
+* Framework generator registry     → `frameworks.base`
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+import typer
+from dotenv import load_dotenv
+from pydantic_settings import SettingsError
+from rich import print as rprint
+from rich.console import Console
+from rich.syntax import Syntax
+
+from agent_generator.application.build_service import build_dict as build_project
+from agent_generator.application.planning_service import plan as plan_project
+from agent_generator.config import Settings, get_settings
+from agent_generator.frameworks import FRAMEWORKS
+from agent_generator.providers import PROVIDERS
+
+# 1) Treat the current working directory as the project root
+project_root = Path.cwd()
+
+# 2) Load .env **only** from the current working directory
+load_dotenv(dotenv_path=project_root / ".env", override=False)
+
+# ────────────────────────────────────────────────────────────────
+# Typer app
+# ────────────────────────────────────────────────────────────────
+app = typer.Typer(
+    add_completion=False,
+    help="Transform plain English into fully configured multi‑agent teams.",
+)
+
+console = Console()
+
+VERSION = "0.2.0"  # 🛈 bump on release
+
+
+# ---------------------------------------------------------------- #
+# Helpers
+# ---------------------------------------------------------------- #
+def _validate_choice(value: str, allowed: set[str], name: str) -> str:
+    if value not in allowed:
+        console.print(
+            f"[red]{name} '{value}' is invalid. Options: {sorted(allowed)}[/]"
+        )
+        raise typer.Exit(code=1)
+    return value
+
+
+def _write_or_echo(text: str, output: Optional[Path]) -> None:
+    if output:
+        output.write_text(text, encoding="utf-8")
+        console.print(f"[bold green]✓ Written to {output}[/]")
+    else:
+        console.print(
+            Syntax(text, "python" if text.lstrip().startswith("from") else "yaml")
+        )
+
+
+# ---------------------------------------------------------------- #
+# generate command
+# ---------------------------------------------------------------- #
+@app.command()
+def generate(
+    prompt: str = typer.Argument(..., help="Natural‑language requirement sentence(s)."),
+    framework: str = typer.Option(
+        ..., "--framework", "-f", help="Target framework.", show_choices=False
+    ),
+    provider: Optional[str] = typer.Option(
+        None, "--provider", "-p", help="LLM provider (defaults to config)."
+    ),
+    model: Optional[str] = typer.Option(None, help="Override model name."),
+    temperature: Optional[float] = typer.Option(None, help="Sampling temperature."),
+    max_tokens: Optional[int] = typer.Option(None, help="Max tokens for completion."),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Write result to file instead of stdout. "
+        "File extension inferred from framework if omitted.",
+    ),
+    mcp: bool = typer.Option(
+        False,
+        "--mcp/--no-mcp",
+        help="Wrap Python output in an MCP FastAPI server.",
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Skip LLM call."),
+    show_cost: bool = typer.Option(
+        False, "--show-cost", help="Display token/cost info."
+    ),
+    version: bool = typer.Option(False, "--version", "-V", is_eager=True),
+):
+    """Generate code (or YAML) for a multi‑agent workflow."""
+    if version:
+        rprint(f"[bold]agent‑generator {VERSION}[/]")
+        raise typer.Exit()
+
+    # ────────────── Pre‑flight env check ──────────────
+    provider_name = provider or os.getenv("AGENTGEN_PROVIDER", "watsonx")
+    required: list[str] = []
+    if provider_name == "watsonx":
+        required = ["WATSONX_API_KEY", "WATSONX_PROJECT_ID"]
+    elif provider_name == "openai":
+        required = ["OPENAI_API_KEY"]
+
+    missing = [v for v in required if not os.getenv(v)]
+    if missing:
+        console.print(
+            f"\n[red]⚠️  Missing environment variables for provider '{provider_name}':[/red]\n"
+            + "\n".join(f"  • {v}" for v in missing)
+            + "\n\nPlease set them (or add to your .env), for example:\n"
+            + (
+                "  export WATSONX_API_KEY=…\n"
+                "  export WATSONX_PROJECT_ID=…\n"
+                "  export WATSONX_URL=https://us-south.ml.cloud.ibm.com\n"
+                if provider_name == "watsonx"
+                else "  export OPENAI_API_KEY=sk-…\n"
+            )
+        )
+        raise typer.Exit(code=1)
+
+    # ───────── Load defaults and catch missing env vars ─────────
+    try:
+        defaults = get_settings()
+    except SettingsError as e:
+        console.print(f"\n[red]⚠️ Configuration error:[/red]\n{e}\n")
+        raise typer.Exit(code=1)
+
+    # ───────── Validate choices ─────────
+    framework = _validate_choice(framework, set(FRAMEWORKS), "Framework")
+    _provider_name = provider or defaults.provider
+    _provider_name = _validate_choice(_provider_name, set(PROVIDERS), "Provider")
+
+    # ───────── Plan (spec-first pipeline) ─────────
+    spec, plan_warnings = plan_project(
+        prompt, framework=framework, provider=provider_name, mcp=mcp,
+    )
+    if plan_warnings:
+        for w in plan_warnings:
+            console.print(f"[yellow]⚠ {w}[/]")
+
+    # ───────── Dry‑run shortcut ─────────
+    if dry_run:
+        console.print(
+            "[yellow]Dry‑run only → generating code without LLM calls or env checks.[/]"
+        )
+        result = build_project(spec, mcp=mcp)
+        # Pick the main generated file
+        code = ""
+        for path, content in result["files"].items():
+            if path.endswith(".py") or path.endswith(".yaml"):
+                if "main.py" in path or path.endswith(".yaml"):
+                    code = content
+                    break
+        if not code:
+            code = next(iter(result["files"].values()), "")
+        _write_or_echo(code, output)
+        return
+
+    # ───────── Load mutable settings ─────────
+    try:
+        settings = Settings(
+            provider=_provider_name,
+            model=model or defaults.model,
+            temperature=temperature or defaults.temperature,
+            max_tokens=max_tokens or defaults.max_tokens,
+        )
+    except SettingsError as e:
+        console.print(f"\n[red]⚠️ Configuration error:[/red]\n{e}\n")
+        raise typer.Exit(code=1)
+
+    # ───────── Build from spec ─────────
+    result = build_project(spec, mcp=mcp)
+
+    # Check for build errors
+    if result.get("errors"):
+        for err in result["errors"]:
+            console.print(f"[red]ERROR:[/] {err}")
+        if any("unsafe" in e.lower() or "forbidden" in e.lower() for e in result["errors"]):
+            console.print("[red]Build blocked due to security violations.[/]")
+            raise typer.Exit(code=1)
+
+    # Pick the main generated file
+    code = ""
+    for path, content in result["files"].items():
+        if path.endswith(".py") or path.endswith(".yaml"):
+            if "main.py" in path or path.endswith(".yaml"):
+                code = content
+                break
+    if not code:
+        code = next(iter(result["files"].values()), "")
+
+    # ───────── Render prompt + call LLM (optional enhancement) ─────────
+    provider_cls = PROVIDERS[_provider_name]
+    try:
+        provider_inst = provider_cls(settings)
+    except ImportError as e:
+        console.print(f"\n[red]⚠️ {e}[/red]\n")
+        raise typer.Exit(code=1)
+
+    # ───────── Cost estimate ─────────
+    if show_cost:
+        ptok = provider_inst.tokenize(prompt)
+        ctok = provider_inst.tokenize(code)
+        cost = provider_inst.estimate_cost(ptok, ctok)
+        console.print(
+            f"[cyan]≈ prompt_tokens={ptok}, completion_tokens={ctok}, "
+            f"est. cost=${cost:.4f}[/]"
+        )
+
+    # ───────── Output ─────────
+    _write_or_echo(code, output)
+
+
+# ---------------------------------------------------------------- #
+# Entry point for `python -m agent_generator.cli`
+# ---------------------------------------------------------------- #
+def _main() -> None:  # noqa: D401
+    app()
+
+
+if __name__ == "__main__":
+    _main()

agent_generator_pkg/src/agent_generator/config.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import functools
+from pathlib import Path
+from typing import Literal, Optional
+
+from dotenv import load_dotenv
+from pydantic import Field, field_validator, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict, SettingsError
+
+# ────────────────────────────────────────────────────────────────
+# Immediately load .env from the current working directory
+# ────────────────────────────────────────────────────────────────
+load_dotenv(dotenv_path=Path.cwd() / ".env", override=False)
+
+
+# ────────────────────────────────────────────────────────────────
+# Settings model
+# ────────────────────────────────────────────────────────────────
+class Settings(BaseSettings):
+    """
+    Runtime configuration for *agent-generator*.
+
+    Environment variables with the prefix **AGENTGEN_** are read automatically,
+    but none are required.
+    If **AGENTGEN_PROVIDER** is *omitted*, the provider defaults to **watsonx**.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="AGENTGEN_",
+        env_file=str(Path.cwd() / ".env"),
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # LLM provider - default is *watsonx*
+    provider: Literal["watsonx", "openai"] = Field(
+        default="watsonx",
+        description="Default LLM provider; can be overridden by CLI flag or env.",
+    )
+
+    # Global model + sampling
+    model: str = Field(
+        default="meta-llama/llama-3-3-70b-instruct",
+        description="Model identifier understood by the chosen provider.",
+    )
+    temperature: float = Field(default=0.7, ge=0, le=2)
+    max_tokens: int = Field(default=4096, ge=16)
+
+    # Provider-specific model overrides (use validation_alias for env mapping)
+    watsonx_model: Optional[str] = Field(
+        default=None, validation_alias="WATSONX_MODEL"
+    )
+    openai_model: Optional[str] = Field(
+        default=None, validation_alias="OPENAI_MODEL"
+    )
+
+    # Credentials
+    watsonx_api_key: Optional[str] = Field(
+        default=None, validation_alias="WATSONX_API_KEY"
+    )
+    watsonx_project_id: Optional[str] = Field(
+        default=None, validation_alias="WATSONX_PROJECT_ID"
+    )
+    watsonx_url: str = Field(
+        default="https://us-south.ml.cloud.ibm.com",
+        validation_alias="WATSONX_URL",
+    )
+    openai_api_key: Optional[str] = Field(
+        default=None, validation_alias="OPENAI_API_KEY"
+    )
+
+    # Misc
+    log_level: str = Field(default="INFO")
+    mcp_default_port: int = Field(default=8080, ge=1, le=65535)
+
+    # Skip credential validation (for dry-run / testing)
+    skip_credential_check: bool = Field(default=False)
+
+    # ──────────────────────────────────────────────────
+    # Validators
+    # ──────────────────────────────────────────────────
+    @field_validator("log_level", mode="before")
+    @classmethod
+    def _normalise_log_level(cls, v: str) -> str:
+        v_up = v.upper()
+        if v_up not in {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}:
+            raise ValueError(
+                "log_level must be one of DEBUG | INFO | WARNING | ERROR | CRITICAL"
+            )
+        return v_up
+
+    @model_validator(mode="after")
+    def _apply_overrides_and_check(self):
+        # Apply provider-specific model override
+        if self.provider == "watsonx" and self.watsonx_model:
+            object.__setattr__(self, "model", self.watsonx_model)
+
+        # For OpenAI, use explicit override or default to gpt-4o
+        if self.provider == "openai":
+            if self.openai_model:
+                object.__setattr__(self, "model", self.openai_model)
+            else:
+                object.__setattr__(self, "model", "gpt-4o")
+
+        # Skip credential checks if requested
+        if self.skip_credential_check:
+            return self
+
+        # Credential checks with copy-pasteable guidance
+        if self.provider == "openai":
+            if not self.openai_api_key:
+                raise SettingsError(
+                    "OPENAI_API_KEY is required.\n"
+                    "Run  pip install 'agent-generator[openai]'  to enable OpenAI support.\n"
+                    "Set it in your environment or .env file, e.g.:\n"
+                    "  export OPENAI_API_KEY=sk-your-key-here"
+                )
+
+        if self.provider == "watsonx":
+            missing = []
+            if not self.watsonx_api_key:
+                missing.append("WATSONX_API_KEY")
+            if not self.watsonx_project_id:
+                missing.append("WATSONX_PROJECT_ID")
+            if missing:
+                raise SettingsError(
+                    "Watsonx credentials missing: " + ", ".join(missing) + ".\n"
+                    "Set the required environment variables (example):\n"
+                    "  export WATSONX_API_KEY=...\n"
+                    "  export WATSONX_PROJECT_ID=...\n"
+                    "  export WATSONX_URL=https://us-south.ml.cloud.ibm.com\n"
+                    "Or add the same keys to your .env file."
+                )
+        return self
+
+    # Convenience flags
+    @property
+    def is_watsonx(self) -> bool:
+        return self.provider == "watsonx"
+
+    @property
+    def is_openai(self) -> bool:
+        return self.provider == "openai"
+
+
+# ────────────────────────────────────────────────
+# Singleton accessor
+# ────────────────────────────────────────────────
+@functools.lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Return a *cached* Settings instance (lazy `.env` read)."""
+    return Settings()
+
+
+def get_settings_lenient() -> Settings:
+    """Return Settings without credential validation (for parsing/planning)."""
+    return Settings(skip_credential_check=True)

agent_generator_pkg/src/agent_generator/data/default_prompts.yaml

@@ -0,0 +1,31 @@
+# ────────────────────────────────────────────────────────────────
+#  default_prompts.yaml — reusable prompt fragments
+# ────────────────────────────────────────────────────────────────
+#
+# These snippets are injected by utils/prompts.py when building the
+# provider‑specific prompt.  Edit to fine‑tune tone or add few‑shot
+# examples for better planning / code style consistency.
+#
+# Structure:
+#   system   : merged at the top of every prompt
+#   user     : optional user examples
+#   assistant: optional assistant examples
+# ----------------------------------------------------------------
+
+system: |
+  You are an expert software engineer specialising in multi‑agent AI
+  systems.  Generate clear, idiomatic code and follow PEP‑8 style rules.
+  Respond **only** with code blocks unless explicitly asked for plain text.
+
+user: |
+  I need a team of agents that will research the latest AI trends and
+  write a brief executive summary for C‑level readers.
+
+assistant: |
+  ```python
+  # Auto‑generated CrewAI script (abbreviated)
+  from crewai import Agent, Task, Crew
+  researcher = Agent(...)
+  writer     = Agent(...)
+  ...
+

agent_generator_pkg/src/agent_generator/domain/artifact_bundle.py

@@ -0,0 +1,31 @@
+"""Typed output contract for generated projects."""
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class GeneratedFile(BaseModel):
+    """A single generated file in the artifact bundle."""
+    path: str = Field(..., description="Relative file path.")
+    content: str = Field(..., description="File content.")
+    language: str | None = Field(default=None, description="Language hint for syntax highlighting.")
+
+
+class ValidationIssue(BaseModel):
+    """A validation finding attached to a build."""
+    level: Literal["info", "warning", "error"] = "warning"
+    message: str = ""
+
+
+class ArtifactBundle(BaseModel):
+    """Complete typed output of a build operation."""
+    files: list[GeneratedFile] = Field(default_factory=list)
+    manifest: dict[str, Any] = Field(default_factory=dict)
+    warnings: list[ValidationIssue] = Field(default_factory=list)
+    errors: list[ValidationIssue] = Field(default_factory=list)
+
+    @property
+    def valid(self) -> bool:
+        return not any(e.level == "error" for e in self.errors)

agent_generator_pkg/src/agent_generator/domain/capability_matrix.py

@@ -0,0 +1,65 @@
+"""Framework capability matrix -- what each framework supports."""
+from __future__ import annotations
+
+CAPABILITY_MATRIX: dict[str, dict[str, bool]] = {
+    "crewai": {
+        "code_only": True,
+        "yaml_only": True,
+        "code_and_yaml": True,
+        "tool_templates": True,
+        "mcp_wrapper": True,
+    },
+    "crewai_flow": {
+        "code_only": True,
+        "yaml_only": False,
+        "code_and_yaml": False,
+        "tool_templates": True,
+        "mcp_wrapper": True,
+    },
+    "langgraph": {
+        "code_only": True,
+        "yaml_only": False,
+        "code_and_yaml": False,
+        "tool_templates": True,
+        "mcp_wrapper": True,
+    },
+    "react": {
+        "code_only": True,
+        "yaml_only": False,
+        "code_and_yaml": False,
+        "tool_templates": True,
+        "mcp_wrapper": True,
+    },
+    "watsonx_orchestrate": {
+        "code_only": False,
+        "yaml_only": True,
+        "code_and_yaml": False,
+        "tool_templates": False,
+        "mcp_wrapper": False,
+    },
+}
+
+
+def validate_combination(framework: str, mode: str) -> bool:
+    """Return True if the given artifact mode is supported by the framework."""
+    return CAPABILITY_MATRIX.get(framework, {}).get(mode, False)
+
+
+def supported_modes(framework: str) -> list[str]:
+    """Return the list of supported artifact modes for a framework."""
+    caps = CAPABILITY_MATRIX.get(framework, {})
+    return [
+        k
+        for k, v in caps.items()
+        if v and k in ("code_only", "yaml_only", "code_and_yaml")
+    ]
+
+
+def supports_tools(framework: str) -> bool:
+    """Return True if the framework supports tool templates."""
+    return CAPABILITY_MATRIX.get(framework, {}).get("tool_templates", False)
+
+
+def supports_mcp(framework: str) -> bool:
+    """Return True if the framework supports MCP wrapping."""
+    return CAPABILITY_MATRIX.get(framework, {}).get("mcp_wrapper", False)

agent_generator_pkg/src/agent_generator/domain/project_spec.py

@@ -0,0 +1,94 @@
+"""Canonical project specification -- the single source of truth between planning and rendering."""
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class FrameworkChoice(str, Enum):
+    CREWAI = "crewai"
+    CREWAI_FLOW = "crewai_flow"
+    LANGGRAPH = "langgraph"
+    REACT = "react"
+    WATSONX_ORCHESTRATE = "watsonx_orchestrate"
+
+
+class ArtifactMode(str, Enum):
+    CODE_ONLY = "code_only"
+    YAML_ONLY = "yaml_only"
+    CODE_AND_YAML = "code_and_yaml"
+
+
+class AgentSpec(BaseModel):
+    """Specification for a single agent in the project."""
+
+    id: str = Field(..., description="Unique agent identifier (snake_case).")
+    role: str = Field(..., description="Agent role name.")
+    goal: str = Field(..., description="What this agent tries to achieve.")
+    backstory: str = Field(default="", description="Background context for the agent.")
+    tools: list[str] = Field(default_factory=list, description="Tool IDs this agent can use.")
+    llm_override: Optional[str] = Field(
+        default=None, description="Override LLM model for this agent."
+    )
+
+
+class TaskSpec(BaseModel):
+    """Specification for a single task in the project."""
+
+    id: str = Field(..., description="Unique task identifier (snake_case).")
+    description: str = Field(..., description="What this task does.")
+    agent_id: str = Field(..., description="ID of the agent responsible.")
+    expected_output: str = Field(..., description="What the task should produce.")
+    depends_on: list[str] = Field(
+        default_factory=list, description="IDs of prerequisite tasks."
+    )
+
+
+class ToolSpec(BaseModel):
+    """Specification for a tool pulled from the tool catalog."""
+
+    id: str = Field(..., description="Unique tool identifier.")
+    template: str = Field(..., description="Key in the tool catalog.")
+    inputs: dict[str, str] = Field(
+        default_factory=dict, description="Template variable overrides."
+    )
+
+
+class LLMSpec(BaseModel):
+    """LLM provider and model configuration."""
+
+    provider: str = Field(default="watsonx")
+    model: str = Field(default="meta-llama/llama-3-3-70b-instruct")
+
+
+class RuntimeSpec(BaseModel):
+    """Runtime options for the generated project."""
+
+    serve_api: bool = Field(default=False)
+    mcp_wrapper: bool = Field(default=False)
+    mcp_port: int = Field(default=8080, ge=1, le=65535)
+
+
+class ProjectSpec(BaseModel):
+    """Canonical specification for a multi-agent project."""
+
+    name: str = Field(
+        ...,
+        description="Project slug (kebab-case).",
+        pattern=r"^[a-z0-9][a-z0-9-]*$",
+    )
+    version: str = Field(default="1.0", description="Schema version.")
+    template_tier: str = Field(default="production", description="Template tier: starter or production.")
+    metadata: dict[str, str] = Field(default_factory=dict, description="Arbitrary metadata tags.")
+    description: str = Field(
+        ..., description="One-line project description.", max_length=500
+    )
+    framework: FrameworkChoice
+    artifact_mode: ArtifactMode = Field(default=ArtifactMode.CODE_ONLY)
+    llm: LLMSpec = Field(default_factory=LLMSpec)
+    agents: list[AgentSpec] = Field(..., min_length=1)
+    tasks: list[TaskSpec] = Field(..., min_length=1)
+    tools: list[ToolSpec] = Field(default_factory=list)
+    runtime: RuntimeSpec = Field(default_factory=RuntimeSpec)

agent_generator_pkg/src/agent_generator/domain/render_plan.py

@@ -0,0 +1,26 @@
+"""Deterministic plan of which files to generate."""
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ArtifactEntry(BaseModel):
+    """A single file to be rendered from a Jinja2 template."""
+
+    path: str = Field(..., description="Relative file path in the output project.")
+    template: str = Field(..., description="Jinja2 template name to render.")
+    language: str = Field(
+        default="python", description="File language for syntax highlighting."
+    )
+
+
+class RenderPlan(BaseModel):
+    """Complete manifest of artifacts, dependencies, and framework version."""
+
+    artifacts: list[ArtifactEntry] = Field(default_factory=list)
+    dependencies: list[str] = Field(
+        default_factory=list, description="pip packages needed."
+    )
+    framework_version: str = Field(
+        default="", description="Framework pip specifier."
+    )

agent_generator_pkg/src/agent_generator/frameworks/__init__.py

@@ -0,0 +1,26 @@
+# ────────────────────────────────────────────────────────────────
+#  src/agent_generator/frameworks/__init__.py
+# ────────────────────────────────────────────────────────────────
+"""
+Framework generators registry.
+
+Each import below registers its subclass in the FRAMEWORKS dict
+via BaseFrameworkGenerator.__init_subclass__.
+"""
+
+from .base import FRAMEWORKS, BaseFrameworkGenerator
+from .crewai import CrewAIGenerator
+from .crewai_flow import CrewAIFlowGenerator
+from .langgraph import LangGraphGenerator
+from .react import ReActGenerator
+from .watsonx_orchestrate import WatsonXOrchestrateGenerator
+
+__all__ = [
+    "BaseFrameworkGenerator",
+    "FRAMEWORKS",
+    "CrewAIGenerator",
+    "CrewAIFlowGenerator",
+    "LangGraphGenerator",
+    "ReActGenerator",
+    "WatsonXOrchestrateGenerator",
+]

agent_generator_pkg/src/agent_generator/frameworks/base.py

@@ -0,0 +1,181 @@
+# ────────────────────────────────────────────────────────────────
+#  src/agent_generator/frameworks/base.py
+# ────────────────────────────────────────────────────────────────
+"""
+Base class + registry for every code-generation backend.
+
+Concrete generators live in sub-packages (crewai, langgraph, ...) and must
+implement ``_emit_core_code(workflow, settings)``.
+
+Two public entry points:
+
+* ``generate_from_spec(spec, settings)`` -- preferred v0.2 path, accepts
+  a ``ProjectSpec`` directly.
+* ``generate_code(workflow, settings)`` -- legacy path kept for backward
+  compatibility; accepts a ``Workflow`` object.
+
+Both handle the cross-cutting MCP server scaffold when ``mcp=True`` and
+the output language is Python.
+"""
+
+from __future__ import annotations
+
+import textwrap
+from abc import ABC, abstractmethod
+from typing import ClassVar, Dict, Type
+
+from agent_generator.config import Settings
+from agent_generator.domain.project_spec import ProjectSpec
+from agent_generator.models.workflow import Workflow
+
+# Public registry populated via BaseFrameworkGenerator.__init_subclass__
+FRAMEWORKS: Dict[str, Type["BaseFrameworkGenerator"]] = {}
+
+
+# ────────────────────────────────────────────────
+# Abstract base
+# ────────────────────────────────────────────────
+
+
+class BaseFrameworkGenerator(ABC):
+    """
+    Abstract interface every framework generator must implement.
+
+    Subclass attributes
+    -------------------
+    framework : str
+        Registry key (e.g. "crewai").
+    file_extension : str
+        "py" or "yaml". Dictates whether MCP wrapping is allowed.
+    """
+
+    framework: ClassVar[str] = "base"
+    file_extension: ClassVar[str] = "txt"
+
+    # Registry magic
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if cls.framework == "base":
+            # Don't register the base class itself
+            return
+        if cls.framework in FRAMEWORKS:
+            raise RuntimeError(f"Duplicate framework key: {cls.framework}")
+        FRAMEWORKS[cls.framework] = cls
+
+    # ── New preferred API (v0.2) ──────────────────────────────────
+
+    def generate_from_spec(
+        self,
+        spec: ProjectSpec,
+        settings: Settings,
+        *,
+        mcp: bool = False,
+    ) -> str:
+        """Generate code directly from a ProjectSpec (preferred path)."""
+        core_code = self._emit_from_spec(spec, settings).rstrip() + "\n"
+
+        if mcp and self.file_extension == "py":
+            core_code = self._wrap_mcp_server(core_code, settings.mcp_default_port)
+
+        return core_code
+
+    def _emit_from_spec(self, spec: ProjectSpec, settings: Settings) -> str:
+        """Override in subclass for native ProjectSpec support.
+
+        Default falls back to legacy Workflow adapter.
+        """
+        from agent_generator.models.agent import Agent, LLMConfig, Tool
+        from agent_generator.models.task import Task
+        from agent_generator.models.workflow import Workflow as WF
+        from agent_generator.models.workflow import WorkflowEdge
+
+        agents = [
+            Agent(
+                id=a.id,
+                role=a.role,
+                tools=[Tool(name=t, description=f"Tool: {t}") for t in a.tools],
+                llm=LLMConfig(provider=spec.llm.provider, model=spec.llm.model),
+            )
+            for a in spec.agents
+        ]
+        tasks = [
+            Task(
+                id=t.id,
+                goal=t.description,
+                inputs=list(t.depends_on),
+                outputs=[t.expected_output] if t.expected_output else [],
+                agent_id=t.agent_id,
+            )
+            for t in spec.tasks
+        ]
+        edges = [
+            WorkflowEdge(source=dep, target=t.id)
+            for t in spec.tasks
+            for dep in t.depends_on
+        ]
+        workflow = WF(agents=agents, tasks=tasks, edges=edges)
+        return self._emit_core_code(workflow, settings)
+
+    # ── Legacy API ────────────────────────────────────────────────
+
+    def generate_code(
+        self,
+        workflow: Workflow,
+        settings: Settings,
+        *,
+        mcp: bool = False,
+    ) -> str:
+        """Legacy API -- generate from Workflow object."""
+        core_code = self._emit_core_code(workflow, settings).rstrip() + "\n"
+
+        if mcp and self.file_extension == "py":
+            core_code = self._wrap_mcp_server(core_code, settings.mcp_default_port)
+
+        return core_code
+
+    @abstractmethod
+    def _emit_core_code(self, workflow: Workflow, settings: Settings) -> str:
+        """Legacy: framework-specific generation from Workflow."""
+
+    @staticmethod
+    def _wrap_mcp_server(code: str, port: int) -> str:
+        """
+        Append a tiny FastAPI MCP server so the file can be dockerised and
+        registered in an MCP Gateway.
+
+        Expects the core code to expose `main()` returning serialisable output.
+        """
+        wrapper = textwrap.dedent(
+            f"""
+            # ──────────────────────────────────────────────────────
+            #  MCP HTTP wrapper (auto-generated)
+            # ──────────────────────────────────────────────────────
+            if __name__ == "__main__":
+                import json
+                from fastapi import FastAPI
+                from fastapi.middleware.cors import CORSMiddleware
+                import uvicorn
+
+                app = FastAPI(title="agent-generator MCP skill")
+
+                app.add_middleware(
+                    CORSMiddleware,
+                    allow_origins=["*"],
+                    allow_credentials=True,
+                    allow_methods=["*"],
+                    allow_headers=["*"],
+                )
+
+                @app.post("/invoke")
+                async def invoke():
+                    result = main()  # type: ignore[name-defined]
+                    return json.loads(json.dumps(result, default=str))
+
+                uvicorn.run(app, host="0.0.0.0", port={port})
+            """
+        ).lstrip()
+
+        return f"{code}\n{wrapper}"
+
+
+__all__ = ["BaseFrameworkGenerator", "FRAMEWORKS"]

agent_generator_pkg/src/agent_generator/frameworks/crewai/__init__.py

@@ -0,0 +1,12 @@
+"""
+CrewAI framework plug‑in.
+
+Example
+-------
+    from agent_generator.frameworks import FRAMEWORKS
+    py_src = FRAMEWORKS["crewai"]().generate_code(workflow, settings, mcp=True)
+"""
+
+from .generator import CrewAIGenerator  # noqa: F401
+
+__all__ = ["CrewAIGenerator"]

agent_generator_pkg/src/agent_generator/frameworks/crewai/generator.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import textwrap
+
+from jinja2 import Template
+
+from agent_generator.config import Settings
+from agent_generator.frameworks.base import BaseFrameworkGenerator
+from agent_generator.models.workflow import Workflow
+
+_CREWAI_TEMPLATE = Template(
+    textwrap.dedent(
+        '''
+        """Auto-generated CrewAI project (crewai 1.x)."""
+
+        from crewai import Agent as CrewAgent, Task as CrewTask, Crew, Process
+        from typing import Any
+
+        # ─────────────────────────────────────────────────────────
+        # Agents
+        # ─────────────────────────────────────────────────────────
+        {% for agent in agents %}
+        {{ agent.id }} = CrewAgent(
+            role="{{ agent.role }}",
+            goal="{{ agent.role }} - achieve assigned objectives efficiently",
+            backstory="An experienced {{ agent.role | lower }} with deep domain expertise.",
+            verbose=True,
+            allow_delegation=False,
+            {%- if agent.tools %}
+            tools=[{{ agent.tools | map(attribute="name") | join(", ") }}],
+            {%- endif %}
+        )
+        {% endfor %}
+
+        # ─────────────────────────────────────────────────────────
+        # Tasks
+        # ─────────────────────────────────────────────────────────
+        {% for task in tasks %}
+        {{ task.id }} = CrewTask(
+            description="""{{ task.goal }}""",
+            agent={{ task.agent_id }},
+            expected_output="{{ task.outputs[0] if task.outputs else task.goal }}",
+        )
+        {% endfor %}
+
+        # ─────────────────────────────────────────────────────────
+        # Crew assembly
+        # ─────────────────────────────────────────────────────────
+        crew = Crew(
+            agents=[{% for agent in agents %}{{ agent.id }}, {% endfor %}],
+            tasks=[{% for task in tasks %}{{ task.id }}, {% endfor %}],
+            process=Process.sequential,
+            verbose=True,
+        )
+
+
+        def main() -> Any:
+            """Entry-point for MCP wrapper or direct execution."""
+            return crew.kickoff()
+
+
+        if __name__ == "__main__":
+            result = main()
+            print(result)
+        '''
+    ).strip("\n"),
+    trim_blocks=True,
+    lstrip_blocks=True,
+)
+
+
+class CrewAIGenerator(BaseFrameworkGenerator):
+    framework = "crewai"
+    file_extension = "py"
+
+    def _emit_core_code(self, workflow: Workflow, settings: Settings) -> str:
+        return (
+            _CREWAI_TEMPLATE.render(
+                agents=workflow.agents,
+                tasks=workflow.tasks,
+            )
+            + "\n"
+        )

agent_generator_pkg/src/agent_generator/frameworks/crewai_flow/__init__.py

@@ -0,0 +1,7 @@
+"""
+CrewAI Flow framework plug‑in.
+"""
+
+from .generator import CrewAIFlowGenerator  # noqa: F401
+
+__all__ = ["CrewAIFlowGenerator"]

agent_generator_pkg/src/agent_generator/frameworks/crewai_flow/generator.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import textwrap
+
+from jinja2 import Template
+
+from agent_generator.config import Settings
+from agent_generator.frameworks.base import BaseFrameworkGenerator
+from agent_generator.models.workflow import Workflow
+
+_FLOW_TEMPLATE = Template(
+    textwrap.dedent(
+        '''
+        """Auto-generated CrewAI Flow pipeline (crewai 1.x)."""
+
+        from crewai import Agent as CrewAgent, Task as CrewTask, Crew, Process
+        from crewai.flow.flow import Flow, listen, start
+        from pydantic import BaseModel, Field
+        from typing import Any
+
+        # ─────────────────────────────────────────────────────────
+        # Shared state
+        # ─────────────────────────────────────────────────────────
+
+        class FlowState(BaseModel):
+            """State passed between flow steps."""
+            results: dict[str, Any] = Field(default_factory=dict)
+            current_step: str = ""
+
+        # ─────────────────────────────────────────────────────────
+        # Agents
+        # ─────────────────────────────────────────────────────────
+        {% for agent in agents %}
+        {{ agent.id }} = CrewAgent(
+            role="{{ agent.role }}",
+            goal="{{ agent.role }} - complete assigned objectives",
+            backstory="An experienced {{ agent.role | lower }} with domain expertise.",
+            verbose=True,
+        )
+        {% endfor %}
+
+        # ─────────────────────────────────────────────────────────
+        # Flow definition
+        # ─────────────────────────────────────────────────────────
+
+        class WorkflowFlow(Flow[FlowState]):
+            """Multi-step flow orchestrating agent tasks."""
+
+            @start()
+            def begin(self):
+                """Initialize the flow and run the first task."""
+                self.state.current_step = "begin"
+                {%- if tasks %}
+                crew = Crew(
+                    agents=[{{ tasks[0].agent_id }}],
+                    tasks=[
+                        CrewTask(
+                            description="""{{ tasks[0].goal }}""",
+                            agent={{ tasks[0].agent_id }},
+                            expected_output="{{ tasks[0].outputs[0] if tasks[0].outputs else 'Result of the task' }}",
+                        )
+                    ],
+                    process=Process.sequential,
+                )
+                result = crew.kickoff()
+                self.state.results["{{ tasks[0].id }}"] = str(result)
+                {%- endif %}
+                return self.state
+            {%- for task in tasks[1:] %}
+
+            @listen(begin{% if not loop.first %}_step_{{ loop.index }}{% endif %})
+            def step_{{ loop.index + 1 }}(self):
+                """Execute: {{ task.goal }}"""
+                self.state.current_step = "{{ task.id }}"
+                crew = Crew(
+                    agents=[{{ task.agent_id }}],
+                    tasks=[
+                        CrewTask(
+                            description="""{{ task.goal }}""",
+                            agent={{ task.agent_id }},
+                            expected_output="{{ task.outputs[0] if task.outputs else 'Result of the task' }}",
+                        )
+                    ],
+                    process=Process.sequential,
+                )
+                result = crew.kickoff()
+                self.state.results["{{ task.id }}"] = str(result)
+                return self.state
+            {%- endfor %}
+
+
+        def main() -> Any:
+            """Entry-point for MCP wrapper or direct execution."""
+            flow = WorkflowFlow()
+            result = flow.kickoff()
+            return result
+
+
+        if __name__ == "__main__":
+            result = main()
+            print(result)
+        '''
+    ).strip("\n"),
+    trim_blocks=True,
+    lstrip_blocks=True,
+)
+
+
+class CrewAIFlowGenerator(BaseFrameworkGenerator):
+    framework = "crewai_flow"
+    file_extension = "py"
+
+    def _emit_core_code(self, workflow: Workflow, settings: Settings) -> str:
+        return (
+            _FLOW_TEMPLATE.render(
+                agents=workflow.agents,
+                tasks=workflow.tasks,
+            )
+            + "\n"
+        )

agent_generator_pkg/src/agent_generator/frameworks/langgraph/__init__.py

@@ -0,0 +1,7 @@
+"""
+LangGraph framework plug‑in.
+"""
+
+from .generator import LangGraphGenerator  # noqa: F401
+
+__all__ = ["LangGraphGenerator"]

agent_generator_pkg/src/agent_generator/frameworks/langgraph/generator.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import textwrap
+
+from jinja2 import Template
+
+from agent_generator.config import Settings
+from agent_generator.frameworks.base import BaseFrameworkGenerator
+from agent_generator.models.workflow import Workflow
+
+_LANG_TEMPLATE = Template(
+    textwrap.dedent(
+        '''
+        """Auto-generated LangGraph workflow (langgraph 1.x)."""
+
+        from __future__ import annotations
+
+        from typing import Any, TypedDict
+
+        from langgraph.graph import START, StateGraph
+
+        # ─────────────────────────────────────────────────────────
+        # State schema
+        # ─────────────────────────────────────────────────────────
+
+        class WorkflowState(TypedDict):
+            """Shared state passed between nodes."""
+            input: str
+            {%- for task in tasks %}
+            {{ task.id }}_output: str
+            {%- endfor %}
+
+        # ─────────────────────────────────────────────────────────
+        # Node functions
+        # ─────────────────────────────────────────────────────────
+        {% for task in tasks %}
+        def {{ task.id }}(state: WorkflowState) -> dict[str, Any]:
+            """{{ task.goal }}"""
+            # Process input and produce output for this step
+            context = state.get("input", "")
+            {%- if task.inputs %}
+            # Also consider upstream outputs
+            {%- for inp_name in task.inputs %}
+            prev = state.get("{{ inp_name }}", "")
+            if prev:
+                context = f"{context}\\n{prev}"
+            {%- endfor %}
+            {%- endif %}
+            result = f"[{{ task.id }}] Processed: {context[:200]}"
+            return {"{{ task.id }}_output": result}
+
+        {% endfor %}
+
+        # ─────────────────────────────────────────────────────────
+        # Graph construction
+        # ─────────────────────────────────────────────────────────
+
+        def build_graph() -> StateGraph:
+            """Build and return the compiled LangGraph workflow."""
+            graph = StateGraph(WorkflowState)
+            {%- for task in tasks %}
+            graph.add_node("{{ task.id }}", {{ task.id }})
+            {%- endfor %}
+
+            # Edges
+            {%- if edges %}
+            graph.add_edge(START, "{{ edges[0].source }}")
+            {%- for edge in edges %}
+            graph.add_edge("{{ edge.source }}", "{{ edge.target }}")
+            {%- endfor %}
+            {%- else %}
+            graph.add_edge(START, "{{ tasks[0].id }}")
+            {%- endif %}
+
+            return graph
+
+
+        def main() -> Any:
+            """Entry-point for MCP wrapper or direct execution."""
+            graph = build_graph()
+            app = graph.compile()
+            result = app.invoke({"input": ""})
+            return result
+
+
+        if __name__ == "__main__":
+            result = main()
+            print(result)
+        '''
+    ).strip("\n"),
+    trim_blocks=True,
+    lstrip_blocks=True,
+)
+
+
+class LangGraphGenerator(BaseFrameworkGenerator):
+    framework = "langgraph"
+    file_extension = "py"
+
+    def _emit_core_code(self, workflow: Workflow, settings: Settings) -> str:
+        return (
+            _LANG_TEMPLATE.render(
+                tasks=workflow.tasks,
+                edges=workflow.edges,
+            )
+            + "\n"
+        )

agent_generator_pkg/src/agent_generator/frameworks/react/__init__.py

@@ -0,0 +1,7 @@
+"""
+ReAct framework plug‑in.
+"""
+
+from .generator import ReActGenerator  # noqa: F401
+
+__all__ = ["ReActGenerator"]