Turn CSVs into API calls

Cookbook

Practical, pipeline-ready demos you can copy‑paste.

Turn CSVs into API calls

from alloy import command
import pandas as pd

@command(output=list[dict])
def csv_to_api(df: pd.DataFrame, endpoint_example: str) -> str:
    """Intelligently map CSV columns to API format."""
    return f"Map this data {df.head()} to match API: {endpoint_example}"

# Any CSV → Any API
df = pd.read_csv("customers.csv")
payloads = csv_to_api(df, "POST /customers {fullName, emailAddress, subscriptionTier}")
for p in payloads:
    requests.post("https://api.your-saas.com/customers", json=p)

Customer interview → Feature spec

from dataclasses import dataclass
from alloy import command

@dataclass
class FeatureSpec:
    user_story: str
    acceptance_criteria: list[str]
    technical_requirements: list[str]
    effort_estimate: str
    risks: list[str]

@command(output=FeatureSpec)
def interview_to_spec(transcript: str) -> str:
    return f"Extract feature requirements from: {transcript}"

PR review bot with tools

from alloy import command, tool

@tool
def read_file(path: str) -> str:
    with open(path, "r") as f:
        return f.read()

@command(output=dict, tools=[read_file])
def review_pr(diff: str, pr_description: str) -> str:
    return f"Review this PR considering our patterns: {pr_description}\nDiff: {diff}"

See examples/ for runnable versions and more demos.

Deep Agent (planning, subagents, workspace)

Pattern: compose primitives to build a multi‑phase agent that plans, spawns focused subagents, writes artifacts to a shared workspace, and compiles a final report — while keeping Alloy as a library (no framework glue).

Run (real model):

python examples/90-advanced/01_deep_agents.py

No API keys? You can preview behavior without network by setting ALLOY_BACKEND=fake when running the example.

Building blocks:

• plan_todo: no‑op tool that records a 3–7 bullet plan (contract‑enforced) for traceability.
• Filesystem tools: write_file, append_file, read_file, list_files with path safety and size/limit guards.
• spawn_subagent: tool that calls ask(...) with a focused system + limited tools for narrow subtasks.
• compile_report: synthesizes files/notes/*.md into files/REPORT.md with a "writer" system.
• require_report: DBC check forcing the final artifact before completion.

Orchestrator (sketch):

from dataclasses import dataclass
from alloy import command

@dataclass
class AgentResult:
    summary: str
    files: list[str]

@command(output=AgentResult, tools=[...], system="...rules...")
def deep_research(goal: str) -> str:
    return """
      Objective: {goal}
      - plan_todo to outline 3–7 bullets
      - write notes to files/notes/*.md; use spawn_subagent for narrow tasks
      - compile_report(title=...) → files/REPORT.md
      - require_report() must pass before returning
      Return JSON {summary, files}
    """.strip().format(goal=goal)

Full example: examples/90-advanced/01_deep_agents.py.