spawnio 1.0.5__py3-none-any.whl

spawn/templates/data_project/etl/content.py

@@ -0,0 +1,239 @@
+ETL_RAW_CSV = """\
+date,category,amount,notes
+2024-01-05,Sales,1200,Q1 kickoff
+2024-01-12,sales,430,
+2024-01-18,SALES,980,follow-up
+2024-01-25,Marketing,210,campaign
+2024-02-03,marketing,560,
+2024-02-10,MARKETING,1450,conference
+2024-02-14,Operations,330,
+2024-02-22,operations,390,routine
+2024-03-01,OPERATIONS,1100,audit
+2024-03-08,Sales,270,
+2024-03-15,sales,620,Q2 push
+2024-03-21,,870,unknown category
+2024-03-28,Marketing,190,
+2024-04-04,MARKETING,710,Q2 end
+2024-04-11,Operations,1340,
+2024-04-18,Sales,250,follow-up
+"""
+
+ETL_CLEAN_CONTENT = """\
+import os
+import sys
+
+import pandas as pd
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def run() -> None:
+    input_path = os.getenv("INPUT_PATH", "data/raw.csv")
+    output_path = os.getenv("OUTPUT_PATH", "data/cleaned.csv")
+
+    try:
+        df = pd.read_csv(input_path)
+    except FileNotFoundError:
+        print(f"Input file not found at {{input_path}}. Check INPUT_PATH in .env.")
+        sys.exit(1)
+
+    original_count = len(df)
+
+    # Normalise category: lowercase and strip whitespace
+    df["category"] = df["category"].str.lower().str.strip()
+
+    # Drop rows with missing values in required columns
+    required_cols = ["date", "category", "amount"]
+    df = df.dropna(subset=required_cols)
+
+    cleaned_count = len(df)
+    dropped = original_count - cleaned_count
+
+    df.to_csv(output_path, index=False)
+
+    print(f"Cleaned {{cleaned_count}} rows (dropped {{dropped}} with missing values).")
+    print(f"Output written to {{output_path}}")
+
+
+if __name__ == "__main__":
+    run()
+"""
+
+ETL_RUN_CONTENT = """\
+import os
+
+from dotenv import load_dotenv
+
+from pipelines.clean_data import run as clean
+
+load_dotenv()
+
+
+def main() -> None:
+    output_path = os.getenv("OUTPUT_PATH", "data/cleaned.csv")
+    clean()
+    print(f"Pipeline complete. Output written to {{output_path}}")
+
+
+if __name__ == "__main__":
+    main()
+"""
+
+ETL_ENV_CONTENT = """\
+APP_NAME={project_name}
+INPUT_PATH=data/raw.csv
+OUTPUT_PATH=data/cleaned.csv
+"""
+
+ETL_TEST_CONTENT = """\
+import os
+from pathlib import Path
+
+import pandas as pd
+import pytest
+
+
+@pytest.fixture()
+def raw_csv(tmp_path: Path) -> Path:
+    content = (
+        "date,category,amount,notes\\n"
+        "2024-01-05,Sales,100,ok\\n"
+        "2024-01-06,SALES,200,\\n"
+        "2024-01-07,marketing,300,ok\\n"
+        "2024-01-08,,400,missing category\\n"
+        "2024-01-09,operations,,missing amount\\n"
+    )
+    p = tmp_path / "raw.csv"
+    p.write_text(content, encoding="utf-8")
+    return p
+
+
+def test_clean_produces_lowercase_categories(raw_csv: Path, tmp_path: Path):
+    out = tmp_path / "cleaned.csv"
+    os.environ["INPUT_PATH"] = str(raw_csv)
+    os.environ["OUTPUT_PATH"] = str(out)
+
+    from pipelines.clean_data import run
+    run()
+
+    df = pd.read_csv(out)
+    assert all(df["category"] == df["category"].str.lower().str.strip()), (
+        "category values are not all lowercase"
+    )
+
+
+def test_clean_drops_rows_with_missing_required_values(raw_csv: Path, tmp_path: Path):
+    out = tmp_path / "cleaned.csv"
+    os.environ["INPUT_PATH"] = str(raw_csv)
+    os.environ["OUTPUT_PATH"] = str(out)
+
+    from pipelines.clean_data import run
+    run()
+
+    df = pd.read_csv(out)
+    # Rows with missing category or amount should be gone
+    assert df["category"].notna().all(), "cleaned CSV still has missing category"
+    assert df["amount"].notna().all(), "cleaned CSV still has missing amount"
+
+
+def test_clean_missing_input_exits(tmp_path: Path):
+    os.environ["INPUT_PATH"] = str(tmp_path / "nonexistent.csv")
+    os.environ["OUTPUT_PATH"] = str(tmp_path / "out.csv")
+
+    from pipelines.clean_data import run
+    with pytest.raises(SystemExit) as exc_info:
+        run()
+    assert exc_info.value.code == 1
+
+
+def test_raw_csv_exists():
+    assert Path("data/raw.csv").exists(), "data/raw.csv must exist"
+"""
+
+
+def make_readme() -> str:
+    return (
+        "# {project_name}\n\n"
+        "An ETL Pipeline generated with Spawn using pandas and python-dotenv.\n\n"
+        "## Getting Started\n\n"
+        "1. Rename `.env.example` to `.env` (optional — defaults work out of the box):\n\n"
+        "```bash\n"
+        "# .env\n"
+        "INPUT_PATH=data/raw.csv\n"
+        "OUTPUT_PATH=data/cleaned.csv\n"
+        "```\n\n"
+        "2. Install dependencies:\n\n"
+        "```bash\n"
+        "uv sync\n"
+        "```\n\n"
+        "3. Run the pipeline:\n\n"
+        "```bash\n"
+        "uv run python -m pipelines.run\n"
+        "```\n\n"
+        "## Configuration\n\n"
+        "`INPUT_PATH` and `OUTPUT_PATH` are read from `.env` (via python-dotenv).\n"
+        "Override them to point at any CSV file without editing code:\n\n"
+        "```env\n"
+        "INPUT_PATH=data/my_data.csv\n"
+        "OUTPUT_PATH=data/my_data_clean.csv\n"
+        "```\n\n"
+        "## What the Pipeline Does\n\n"
+        "1. Reads the raw CSV from `INPUT_PATH`\n"
+        "2. Normalises the `category` column (lowercase + strip whitespace)\n"
+        "3. Drops rows with missing values in required columns\n"
+        "4. Writes the cleaned CSV to `OUTPUT_PATH`\n\n"
+        "## Project Structure\n\n"
+        "```\n"
+        "{project_name}/\n"
+        "├── data/\n"
+        "│   ├── raw.csv             # Source data\n"
+        "│   └── cleaned.csv         # Output (created on first run)\n"
+        "├── pipelines/\n"
+        "│   ├── clean_data.py       # Cleaning logic\n"
+        "│   └── run.py              # Pipeline entry point\n"
+        "├── src/\n"
+        "├── tests/\n"
+        "│   └── test_etl.py\n"
+        "├── .env.example\n"
+        "└── README.md\n"
+        "```\n\n"
+        "## Running Tests\n\n"
+        "```bash\n"
+        "uv run pytest\n"
+        "```\n"
+    )
+
+# ─── GitHub Actions ───────────────────────────────────────────────────────
+
+GITHUB_ACTIONS_CI_BASE = """\
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync
+"""
+
+GITHUB_ACTIONS_CI_RUFF_STEP = """\
+      - name: Lint
+        run: uv run ruff check .
+"""
+
+GITHUB_ACTIONS_CI_PYTEST_STEP = """\
+      - name: Test
+        run: uv run pytest
+"""

spawn/templates/data_project/ml/__init__.py

@@ -0,0 +1,62 @@
+from pathlib import Path
+
+from spawn.templates.base import BaseTemplate
+from spawn.templates.data_project.ml.content import (
+    ML_SAMPLE_CSV,
+    ML_TRAIN_CONTENT,
+    ML_TEST_CONTENT,
+    make_readme,
+    GITHUB_ACTIONS_CI_BASE,
+    GITHUB_ACTIONS_CI_RUFF_STEP,
+    GITHUB_ACTIONS_CI_PYTEST_STEP,
+)
+
+FOLDERS = ["data", "models", "experiments", "src", "tests"]
+
+FILES = [
+    ("data/dataset.csv",       ML_SAMPLE_CSV),
+    ("src/__init__.py",        ""),
+    ("src/train.py",           ML_TRAIN_CONTENT),
+    ("tests/test_ml.py",       ML_TEST_CONTENT),
+    ("tests/__init__.py",      ""),
+    ("models/.gitkeep",        ""),
+    ("experiments/.gitkeep",   ""),
+]
+
+DEPENDENCIES = ["pandas", "numpy", "scikit-learn", "joblib"]
+
+NEXT_STEPS = [
+    "cd {project_name}",
+    "uv run python src/train.py",
+]
+
+
+class MLProjectTemplate(BaseTemplate):
+    data_type = "Machine Learning"
+    _CI_BASE = GITHUB_ACTIONS_CI_BASE
+    _CI_RUFF_STEP = GITHUB_ACTIONS_CI_RUFF_STEP
+    _CI_PYTEST_STEP = GITHUB_ACTIONS_CI_PYTEST_STEP
+
+    def __init__(self, extras: list[str] | None = None) -> None:
+        self.extras = extras or []
+        super().__init__(
+            name="Data Project",
+            folders=list(FOLDERS),
+            starter_files=list(FILES),
+            next_steps=list(NEXT_STEPS),
+        )
+
+    def get_readme_content(self, context: dict) -> str | None:
+        return make_readme().format_map(context)
+
+    def get_dependencies(self) -> list[str]:
+        base = list(DEPENDENCIES)
+        if "pytest" in self.extras:
+            base.append("pytest")
+        if "ruff" in self.extras:
+            base.append("ruff")
+        return base
+
+    def post_install(self, project_path: Path) -> None:
+        from spawn.templates.data_project import _DataProjectPostInstallMixin
+        _DataProjectPostInstallMixin.post_install(self, project_path)  # type: ignore[arg-type]

spawn/templates/data_project/ml/content.py

@@ -0,0 +1,239 @@
+ML_SAMPLE_CSV = """\
+feature_1,feature_2,feature_3,feature_4,target
+2.5,1.4,0.3,0.1,0
+4.7,3.2,1.3,0.2,0
+4.6,3.1,1.5,0.2,0
+5.0,3.6,1.4,0.2,0
+5.4,3.9,1.7,0.4,0
+4.6,3.4,1.4,0.3,0
+5.0,3.4,1.5,0.2,0
+4.4,2.9,1.4,0.2,0
+4.9,3.1,1.5,0.1,0
+5.4,3.7,1.5,0.2,0
+4.8,3.4,1.6,0.2,0
+4.8,3.0,1.4,0.1,0
+4.3,3.0,1.1,0.1,0
+5.8,4.0,1.2,0.2,0
+5.7,4.4,1.5,0.4,0
+5.4,3.9,1.3,0.4,0
+5.1,3.5,1.4,0.3,0
+5.7,3.8,1.7,0.3,0
+5.1,3.8,1.5,0.3,0
+5.4,3.4,1.7,0.2,0
+7.0,3.2,4.7,1.4,1
+6.4,3.2,4.5,1.5,1
+6.9,3.1,4.9,1.5,1
+5.5,2.3,4.0,1.3,1
+6.5,2.8,4.6,1.5,1
+5.7,2.8,4.5,1.3,1
+6.3,3.3,4.7,1.6,1
+4.9,2.4,3.3,1.0,1
+6.6,2.9,4.6,1.3,1
+5.2,2.7,3.9,1.4,1
+5.0,2.0,3.5,1.0,1
+5.9,3.0,4.2,1.5,1
+6.0,2.2,4.0,1.0,1
+6.1,2.9,4.7,1.4,1
+5.6,2.9,3.6,1.3,1
+6.7,3.1,4.4,1.4,1
+5.6,3.0,4.5,1.5,1
+5.8,2.7,4.1,1.0,1
+6.2,2.2,4.5,1.5,1
+5.6,2.5,3.9,1.1,1
+"""
+
+ML_TRAIN_CONTENT = """\
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+
+import joblib
+import pandas as pd
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.metrics import accuracy_score
+from sklearn.model_selection import train_test_split
+
+
+def train() -> None:
+    data_path = Path("data/dataset.csv")
+    if not data_path.exists():
+        print(f"Dataset not found at {{data_path}}. Ensure data/dataset.csv exists.")
+        return
+
+    df = pd.read_csv(data_path)
+    feature_cols = [c for c in df.columns if c != "target"]
+    X = df[feature_cols].values
+    y = df["target"].values
+
+    X_train, X_test, y_train, y_test = train_test_split(
+        X, y, test_size=0.2, random_state=42
+    )
+
+    clf = RandomForestClassifier(n_estimators=100, random_state=42)
+    clf.fit(X_train, y_train)
+
+    y_pred = clf.predict(X_test)
+    accuracy = float(accuracy_score(y_test, y_pred))
+    print(f"Test accuracy: {{accuracy:.4f}}")
+
+    Path("models").mkdir(exist_ok=True)
+    model_path = Path("models/model.joblib")
+    joblib.dump(clf, model_path)
+    print(f"Model saved to {{model_path}}")
+
+    Path("experiments").mkdir(exist_ok=True)
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    experiment = {{
+        "timestamp": timestamp,
+        "accuracy": accuracy,
+        "model_type": "RandomForestClassifier",
+        "n_train": len(X_train),
+        "n_test": len(X_test),
+    }}
+    exp_path = Path(f"experiments/{{timestamp}}.json")
+    exp_path.write_text(json.dumps(experiment, indent=2), encoding="utf-8")
+    print(f"Experiment logged to {{exp_path}}")
+
+
+if __name__ == "__main__":
+    train()
+"""
+
+ML_TEST_CONTENT = """\
+import json
+from pathlib import Path
+
+import pytest
+
+
+def test_train_produces_model(tmp_path, monkeypatch):
+    import shutil
+
+    monkeypatch.chdir(tmp_path)
+    # Copy the bundled dataset into the tmp working directory
+    src_dataset = Path(__file__).parent.parent / "data" / "dataset.csv"
+    (tmp_path / "data").mkdir()
+    shutil.copy(src_dataset, tmp_path / "data" / "dataset.csv")
+
+    from src.train import train
+    train()
+
+    model_path = tmp_path / "models" / "model.joblib"
+    assert model_path.exists(), "models/model.joblib was not created"
+
+
+def test_train_accuracy_is_valid(tmp_path, monkeypatch):
+    import shutil
+
+    monkeypatch.chdir(tmp_path)
+    src_dataset = Path(__file__).parent.parent / "data" / "dataset.csv"
+    (tmp_path / "data").mkdir()
+    shutil.copy(src_dataset, tmp_path / "data" / "dataset.csv")
+
+    from src.train import train
+    train()
+
+    exp_files = list((tmp_path / "experiments").glob("*.json"))
+    assert exp_files, "No experiment file written"
+    experiment = json.loads(exp_files[0].read_text(encoding="utf-8"))
+    accuracy = experiment["accuracy"]
+    assert isinstance(accuracy, float)
+    assert 0.0 <= accuracy <= 1.0, f"Accuracy out of range: {{accuracy}}"
+
+
+def test_dataset_csv_exists():
+    assert Path("data/dataset.csv").exists(), "data/dataset.csv must exist"
+"""
+
+
+def make_readme() -> str:
+    return (
+        "# {project_name}\n\n"
+        "A Machine Learning project generated with Spawn using scikit-learn.\n\n"
+        "## Getting Started\n\n"
+        "1. Install dependencies:\n\n"
+        "```bash\n"
+        "uv sync\n"
+        "```\n\n"
+        "2. Train the model:\n\n"
+        "```bash\n"
+        "uv run python src/train.py\n"
+        "```\n\n"
+        "Each run trains a `RandomForestClassifier` on `data/dataset.csv`, saves\n"
+        "the model to `models/model.joblib`, and writes a timestamped JSON to\n"
+        "`experiments/` with accuracy and metadata.\n\n"
+        "## Example\n\n"
+        "```\n"
+        "$ uv run python src/train.py\n"
+        "Test accuracy: 1.0000\n"
+        "Model saved to models/model.joblib\n"
+        "Experiment logged to experiments/20240101_120000.json\n"
+        "```\n\n"
+        "Note: the bundled sample dataset is intentionally easy to classify, so\n"
+        "accuracy will typically be 1.0 — replace `data/dataset.csv` with your own\n"
+        "data for realistic results.\n\n"
+        "## Experiment Tracking\n\n"
+        "Every training run appends a new file to `experiments/`:\n\n"
+        "```json\n"
+        "{{\n"
+        '  "timestamp": "20240101_120000",\n'
+        '  "accuracy": 1.0,\n'
+        '  "model_type": "RandomForestClassifier",\n'
+        '  "n_train": 32,\n'
+        '  "n_test": 8\n'
+        "}}\n"
+        "```\n\n"
+        "## Project Structure\n\n"
+        "```\n"
+        "{project_name}/\n"
+        "├── data/\n"
+        "│   └── dataset.csv         # Labeled training data\n"
+        "├── models/\n"
+        "│   └── model.joblib        # Saved model (created on first run)\n"
+        "├── experiments/            # Per-run JSON metrics\n"
+        "├── src/\n"
+        "│   └── train.py            # Training script\n"
+        "├── tests/\n"
+        "│   └── test_ml.py\n"
+        "└── README.md\n"
+        "```\n\n"
+        "## Running Tests\n\n"
+        "```bash\n"
+        "uv run pytest\n"
+        "```\n"
+    )
+
+# ─── GitHub Actions ───────────────────────────────────────────────────────
+
+GITHUB_ACTIONS_CI_BASE = """\
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync
+"""
+
+GITHUB_ACTIONS_CI_RUFF_STEP = """\
+      - name: Lint
+        run: uv run ruff check .
+"""
+
+GITHUB_ACTIONS_CI_PYTEST_STEP = """\
+      - name: Test
+        run: uv run pytest
+"""

spawn/templates/mcp_server/__init__.py

@@ -0,0 +1,83 @@
+from pathlib import Path
+
+from spawn.templates.base import BaseTemplate
+from spawn.templates.mcp_server.content import (
+    INIT_CONTENT,
+    SERVER_CONTENT,
+    TEST_CONTENT,
+    ENV_CONTENT,
+    GITHUB_ACTIONS_CI_BASE,
+    GITHUB_ACTIONS_CI_RUFF_STEP,
+    GITHUB_ACTIONS_CI_PYTEST_STEP,
+    make_readme,
+    make_agents_md,
+)
+
+MCP_SERVER_FOLDERS = [
+    "src",
+    "tests",
+]
+
+
+def _build_files() -> list:
+    return [
+        ("src/__init__.py",      INIT_CONTENT),
+        ("src/server.py",        SERVER_CONTENT),
+        ("tests/__init__.py",    INIT_CONTENT),
+        ("tests/test_server.py", TEST_CONTENT),
+        (".env.example",         ENV_CONTENT),
+    ]
+
+
+class MCPServerTemplate(BaseTemplate):
+    def __init__(self, extras: list[str] | None = None) -> None:
+        self.extras = extras or []
+
+        super().__init__(
+            name="MCP Server",
+            folders=list(MCP_SERVER_FOLDERS),
+            starter_files=_build_files(),
+            next_steps=[
+                "cd {project_name}",
+                "uv run python -m src.server",
+                "Add this server to Claude Desktop's config (see README.md)",
+            ],
+        )
+
+    def get_readme_content(self, context: dict) -> str | None:
+        return make_readme().format_map(context)
+
+    def get_agents_md_content(self, context: dict) -> str | None:
+        return make_agents_md().format_map(context)
+
+    def get_dependencies(self) -> list[str]:
+        base = ["mcp"]
+        if "pytest" in self.extras:
+            base.append("pytest")
+        if "ruff" in self.extras:
+            base.append("ruff")
+        return base
+
+    def post_install(self, project_path: Path) -> None:
+        pyproject = project_path / "pyproject.toml"
+        current   = pyproject.read_text(encoding="utf-8")
+        additions = ""
+
+        if "pytest" in self.extras:
+            additions += "\n[tool.pytest.ini_options]\ntestpaths = [\"tests\"]\n"
+
+        if "ruff" in self.extras:
+            additions += "\n[tool.ruff]\nline-length = 88\n"
+
+        if additions:
+            pyproject.write_text(current + additions, encoding="utf-8")
+
+        if "github-actions" in self.extras:
+            workflows_path = project_path / ".github" / "workflows"
+            workflows_path.mkdir(parents=True, exist_ok=True)
+            ci = GITHUB_ACTIONS_CI_BASE
+            if "ruff" in self.extras:
+                ci += GITHUB_ACTIONS_CI_RUFF_STEP
+            if "pytest" in self.extras:
+                ci += GITHUB_ACTIONS_CI_PYTEST_STEP
+            (workflows_path / "ci.yml").write_text(ci, encoding="utf-8")