Swarms for Retail

import os
from swarms_client import SwarmsClient

client = SwarmsClient(api_key=os.environ["SWARMS_API_KEY"])

# One supplier row as it arrives in the feed.
RAW_ROW = {
    "sku": "CW-2041-BLK",
    "vendor_title": "SAUCEPAN 20CM S/S INDUCTION BLK HNDL",
    "vendor_attrs": "stainless 18/10; 2.8l; glass lid; dw safe; induction",
    "cost_price": "14.20",
    "markets": ["US", "EU"],
}

# AgentRearrange runs the agents in the order the flow string describes:
# "->" means the next step waits, "," means those agents run at the same time.
response = client.swarms.run(
    name="Catalog Enrichment",
    description="Supplier row to a finished, checked listing.",
    swarm_type="AgentRearrange",
    rearrange_flow="Intake -> Copywriter, Attributes -> Compliance -> Publisher",
    task=f"Enrich this supplier row into a complete listing: {RAW_ROW}",
    rules=(
        "Never invent a specification that is not in the row. Mark unknown values as "
        "null. Titles are under 80 characters. Bullets are complete sentences."
    ),
    agents=[
        {
            "agent_name": "Intake",
            "system_prompt": (
                "Normalise the supplier row: expand abbreviations, guess the category "
                "and return a clean JSON object the other agents can read."
            ),
            "model_name": "gemini-2.5-flash",  # cheap, fast, fine for normalisation
            "max_loops": 1,
        },
        {
            "agent_name": "Copywriter",
            "system_prompt": (
                "Write the product title and five benefit bullets for the category. "
                "Use only facts from the normalised row."
            ),
            "model_name": "claude-sonnet-5-5",  # the customer-facing text
            "max_loops": 1,
        },
        {
            "agent_name": "Attributes",
            "system_prompt": (
                "Extract structured attributes as JSON: material, capacity_l, diameter_cm, "
                "lid, dishwasher_safe, induction_ready, colour. Unknown values are null."
            ),
            "model_name": "gpt-4.1-mini",
            "max_loops": 1,
        },
        {
            "agent_name": "Compliance",
            "system_prompt": (
                "Check the copy and attributes for each target market. Flag banned claims, "
                "missing mandatory statements and any specification that is not in the "
                "source row. Return pass or fail per market with reasons."
            ),
            "model_name": "gpt-5.4",  # the gate before publishing
            "max_loops": 1,
        },
        {
            "agent_name": "Publisher",
            "system_prompt": (
                "Assemble the final listing JSON per market from the approved copy and "
                "attributes. Include the compliance result verbatim."
            ),
            "model_name": "claude-haiku-5-5",
            "max_loops": 1,
        },
    ],
    max_loops=1,
)

print(response)

curl -X POST https://api.swarms.world/v1/swarm/completions \
  -H "x-api-key: $SWARMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Catalog Enrichment",
    "description": "Supplier row to a finished, checked listing.",
    "swarm_type": "AgentRearrange",
    "rearrange_flow": "Intake -> Copywriter, Attributes -> Compliance -> Publisher",
    "task": "Enrich this supplier row into a complete listing: sku CW-2041-BLK, vendor title SAUCEPAN 20CM S/S INDUCTION BLK HNDL, attrs stainless 18/10; 2.8l; glass lid; dw safe; induction, markets US and EU.",
    "rules": "Never invent a specification that is not in the row. Mark unknown values as null. Titles under 80 characters. Bullets are complete sentences.",
    "agents": [
      {
        "agent_name": "Intake",
        "system_prompt": "Normalise the supplier row: expand abbreviations, guess the category and return clean JSON.",
        "model_name": "gemini-2.5-flash",
        "max_loops": 1
      },
      {
        "agent_name": "Copywriter",
        "system_prompt": "Write the product title and five benefit bullets using only facts from the normalised row.",
        "model_name": "claude-sonnet-5-5",
        "max_loops": 1
      },
      {
        "agent_name": "Attributes",
        "system_prompt": "Extract structured attributes as JSON: material, capacity_l, diameter_cm, lid, dishwasher_safe, induction_ready, colour. Unknown values are null.",
        "model_name": "gpt-4.1-mini",
        "max_loops": 1
      },
      {
        "agent_name": "Compliance",
        "system_prompt": "Check copy and attributes per market. Flag banned claims, missing mandatory statements and invented specifications. Return pass or fail per market with reasons.",
        "model_name": "gpt-5.4",
        "max_loops": 1
      },
      {
        "agent_name": "Publisher",
        "system_prompt": "Assemble the final listing JSON per market from the approved copy and attributes, with the compliance result included verbatim.",
        "model_name": "claude-haiku-5-5",
        "max_loops": 1
      }
    ],
    "max_loops": 1
  }'

# Every agent_name in rearrange_flow must match an entry in agents.
# The response carries "output" and "usage" (input, output and total tokens).

// Support ticket routing: the router reads the ticket and dispatches it to
// exactly one specialist, whose draft reply comes back with the route.
const SWARMS_API = "https://api.swarms.world/v1/swarm/completions"

type Ticket = { id: string; orderId?: string; subject: string; body: string }

type SwarmResponse = {
  output: unknown
  usage: { input_tokens: number; output_tokens: number; total_tokens: number }
}

const specialist = (name: string, description: string, prompt: string, model: string) => ({
  agent_name: name,
  description, // the router reads descriptions to choose a specialist
  system_prompt:
    prompt +
    " Write the reply in the brand voice: short sentences, no apologies in the first line, " +
    "one clear next step. If the case needs a refund over 100 USD or a legal question, " +
    "write ESCALATE on the first line and summarise for a human agent instead.",
  model_name: model,
  max_loops: 1,
})

export async function routeTicket(ticket: Ticket): Promise<SwarmResponse> {
  const res = await fetch(SWARMS_API, {
    method: "POST",
    headers: {
      "x-api-key": process.env.SWARMS_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Support Ticket Router",
      description: "One specialist per ticket, chosen by the router.",
      swarm_type: "MultiAgentRouter",
      task:
        "Ticket " + ticket.id + (ticket.orderId ? " for order " + ticket.orderId : "") +
        "\nSubject: " + ticket.subject + "\n\n" + ticket.body,
      agents: [
        specialist("Orders Agent", "Order status, changes and cancellations before dispatch.",
          "You handle order questions. Confirm what can still change before dispatch.", "gpt-4.1-mini"),
        specialist("Returns Agent", "Returns, exchanges and refunds within the 30-day policy.",
          "You handle returns. State the policy window and the steps to start a return.", "claude-haiku-5-5"),
        specialist("Product Agent", "Sizing, materials, care and compatibility questions.",
          "You answer product questions from the listing attributes only. Never guess a spec.", "gpt-5.4-mini"),
        specialist("Shipping Agent", "Delivery times, tracking, lost and damaged parcels.",
          "You handle delivery issues. Give the carrier step and the date to wait until.", "claude-haiku-5-5"),
      ],
      max_loops: 1,
    }),
  })

  if (!res.ok) throw new Error("Swarms API " + res.status + ": " + (await res.text()))
  return (await res.json()) as SwarmResponse
}

routeTicket({
  id: "T-88213",
  orderId: "ORD-553190",
  subject: "Pan arrived with a chipped lid",
  body: "The glass lid on the 20cm saucepan has a chip on the rim. Can I get a replacement lid rather than returning the whole pan?",
}).then((r) => {
  console.log(r.output)
  console.log("tokens:", r.usage.total_tokens)
})

import os
import sys
import requests

BASE = "https://api.swarms.world"
HEADERS = {"x-api-key": os.environ["SWARMS_API_KEY"], "Content-Type": "application/json"}

# The nightly catalog job enriches every new SKU in the feed. Before it
# starts, check the credit balance in Swarms Cloud and stop early if the
# account cannot cover the batch, instead of failing halfway through.
credits = requests.get(f"{BASE}/v1/account/credits", headers=HEADERS, timeout=30).json()
print("credits:", credits)

new_rows = [
    {"sku": "CW-2041-BLK", "vendor_title": "SAUCEPAN 20CM S/S INDUCTION BLK HNDL"},
    {"sku": "CW-2042-BLK", "vendor_title": "SAUCEPAN 16CM S/S INDUCTION BLK HNDL"},
    {"sku": "BK-1177-WHT", "vendor_title": "MIXING BOWL SET 3PC CERAMIC WHT"},
]

# A conservative budget per SKU, agreed with finance for this job.
BUDGET_PER_SKU_USD = 0.05
needed = BUDGET_PER_SKU_USD * len(new_rows)

balance = None
for key in ("credits", "credit", "balance"):
    if isinstance(credits, dict) and isinstance(credits.get(key), (int, float)):
        balance = float(credits[key])
        break

if balance is not None and balance < needed:
    print(f"stopping: {len(new_rows)} SKUs need about {needed:.2f} USD, balance is {balance:.2f}")
    sys.exit(1)


def enrich_request(row: dict) -> dict:
    return {
        "name": f"Catalog Enrichment {row['sku']}",
        "swarm_type": "AgentRearrange",
        "rearrange_flow": "Intake -> Copywriter, Attributes -> Compliance -> Publisher",
        "task": f"Enrich this supplier row into a complete listing: {row}",
        "agents": [
            {"agent_name": "Intake", "system_prompt": "Normalise the supplier row into clean JSON.", "model_name": "gemini-2.5-flash", "max_loops": 1},
            {"agent_name": "Copywriter", "system_prompt": "Write a title under 80 characters and five bullets from the row only.", "model_name": "claude-sonnet-5-5", "max_loops": 1},
            {"agent_name": "Attributes", "system_prompt": "Extract structured attributes as JSON; unknown values are null.", "model_name": "gpt-4.1-mini", "max_loops": 1},
            {"agent_name": "Compliance", "system_prompt": "Flag banned claims, missing statements and invented specs per market.", "model_name": "gpt-5.4", "max_loops": 1},
            {"agent_name": "Publisher", "system_prompt": "Assemble the final listing JSON per market.", "model_name": "claude-haiku-5-5", "max_loops": 1},
        ],
        "max_loops": 1,
    }


batch = [enrich_request(row) for row in new_rows]
resp = requests.post(f"{BASE}/v1/swarm/batch/completions", headers=HEADERS, json=batch, timeout=900)
resp.raise_for_status()

for row, result in zip(new_rows, resp.json()):
    usage = result.get("usage", {})
    print(row["sku"], "tokens:", usage.get("total_tokens"))

# Afterwards the run totals are in Swarms Cloud, or from the API:
print(requests.get(f"{BASE}/v1/metrics/summary", headers=HEADERS, timeout=30).json())

from swarms import Agent, SequentialWorkflow

# The open-source swarms package runs the same price review in-process.
# The output is a proposal for the merchandiser, not a price change.
SNAPSHOT = """
SKU CW-2041-BLK, 20cm induction saucepan. Current price 34 USD, cost 14.20 USD.
Weekly units, last 6 weeks: 212, 198, 171, 140, 122, 97. On hand: 1,840 across 6 stores
and the warehouse. Weeks of cover at current rate: 19. Category markdown floor: 35% margin.
Two listed competitors moved to 29 USD and 31 USD this month.
"""

demand_reader = Agent(
    agent_name="Demand Reader",
    system_prompt=(
        "You read sell-through and stock cover. Summarise the trend, the weeks of cover "
        "and whether the SKU is ahead of or behind the category."
    ),
    model_name="gemini-2.5-flash",
    max_loops=1,
)

pricing = Agent(
    agent_name="Pricing Agent",
    system_prompt=(
        "You propose a single price change with a start date and the expected effect on "
        "weeks of cover. Explain the reasoning in four sentences or fewer."
    ),
    model_name="gpt-5.4",
    max_loops=1,
)

margin_checker = Agent(
    agent_name="Margin Checker",
    system_prompt=(
        "You check the proposal against the margin floor and the competitor positions. "
        "Return APPROVE FOR REVIEW or REJECT with the rule that applies, then the proposal "
        "as JSON: sku, current_price, proposed_price, start_date, margin_pct, reason."
    ),
    model_name="claude-sonnet-5-5",
    max_loops=1,
)

workflow = SequentialWorkflow(
    name="Price Review",
    description="Demand read, price proposal and margin check for one SKU.",
    agents=[demand_reader, pricing, margin_checker],
    max_loops=1,
)

proposal = workflow.run(SNAPSHOT)
print(proposal)  # goes to the merchandiser's queue, not to the price file