flowforge-map 0.1.0__py3-none-any.whl

flowforge/_dashboard/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" rx="14" fill="#0F1D26"/><circle cx="32" cy="32" r="9" fill="#4FD1C0"/><g stroke="#4FD1C0" stroke-width="4" stroke-linecap="round"><path d="M32 12v8M32 44v8M12 32h8M44 32h8"/></g></svg>

flowforge/_dashboard/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light dark" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="description" content="FlowForge: connect your apps, see what will run, and watch every step live." />
+    <title>FlowForge</title>
+    <script type="module" crossorigin src="/assets/index-BoGikST6.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BGT5seIN.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

flowforge/_example/trip-planner/.env.example

@@ -0,0 +1,3 @@
+# Both are optional; these are the defaults.
+OLLAMA_BASE_URL=http://localhost:11434/v1
+PLANNER_MODEL=llama3.1:8b

flowforge/_example/trip-planner/.gitignore

@@ -0,0 +1,2 @@
+trips/*
+!trips/.gitkeep

flowforge/_example/trip-planner/.mcp.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "time": {
+      "command": "uvx",
+      "args": ["mcp-server-time@2026.10.19"]
+    },
+    "fetch": {
+      "command": "uvx",
+      "args": ["mcp-server-fetch"]
+    },
+    "files": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem@2.0.0", "trips"]
+    },
+    "currency": {
+      "command": "python",
+      "args": ["mcp_servers/currency.py"]
+    }
+  }
+}

flowforge/_example/trip-planner/README.md

@@ -0,0 +1,48 @@
+# Trip planner (sample app for FlowForge)
+
+A small app that plans a relaxed day trip. It uses only free services that need no key, so you can run it, scan it, and break nothing. FlowForge uses it three ways:
+- the scanner's test case: the tables below are what a scan must find;
+- the demo;
+- the example map.
+
+```bash
+# from the FlowForge repo root, after `uv sync`
+cd examples/trip-planner
+../../.venv/bin/python planner.py Mangalore --to "Panambur Beach"
+```
+
+You need [Ollama](https://ollama.com) running with `llama3.1:8b` (`ollama pull llama3.1:8b`), plus `uvx` and `npx` for the MCP servers. Every call is tried on its own: a missing piece prints a ✗ and the plan goes on without it. A full run takes a minute or two on a laptop, mostly the local model.
+
+It sends your IP address to ip-api.com (to guess your city) and the city name to OpenStreetMap, Open-Meteo, OSRM and Wikipedia. Nothing else leaves your machine.
+
+## What it depends on (the scan must find these)
+
+| Kind | Dependency | Evidence |
+|---|---|---|
+| LLM | Ollama, `llama3.1:8b`, through the OpenAI SDK | `services/llm.py:5`, `services/llm.py:14`, `config.py:11` |
+| HTTP API | Nominatim (place → coordinates) | `config.py:15` |
+| HTTP API | Open-Meteo (weather) | `config.py:16` |
+| HTTP API | OSRM demo server (routes) | `config.py:17` |
+| HTTP API | ip-api (your city from your IP) | `config.py:18` |
+| HTTP API | Google Static Maps (a link it prints; never called by the app) | `config.py:24` |
+| HTTP API | Wikipedia, fetched through the `fetch` MCP server | `planner.py:67` |
+| MCP | `time` (`uvx mcp-server-time`, pinned) | `.mcp.json:3` |
+| MCP | `fetch` (`uvx mcp-server-fetch`) | `.mcp.json:7` |
+| MCP | `files` (`npx @modelcontextprotocol/server-filesystem`, pinned, only `trips/`) | `.mcp.json:11` |
+| MCP | `currency` (a local Python server) | `.mcp.json:15` |
+| Local | `tools/packing_list.py`, run as a subprocess | `planner.py:37` |
+
+Env var names it reads: `OLLAMA_BASE_URL`, `PLANNER_MODEL` (`config.py:11-12`), and `CURRENCY_API_URL` (`mcp_servers/currency.py:9`).
+
+These are libraries, not dependencies: `httpx`, `mcp`, `openai` (`requirements.txt`). They are the clients the app uses to reach the dependencies above.
+
+## Planted problems (the checks must find these)
+
+| What | Where | Found by |
+|---|---|---|
+| A hard-coded Google key (fake, `AIzaFAKE…`) | `config.py:23` | security findings (Phase 6) |
+| A plain `http://` API | `config.py:18` (ip-api's free tier is http only) | security findings (Phase 6) |
+| An unpinned MCP package | `.mcp.json:9` (`mcp-server-fetch`, no version) | security findings (Phase 6) |
+| An MCP server that never starts | `currency`: exits with "CURRENCY_API_URL is not set" | health checks (Phase 5) |
+
+The key is fake and never works. Never put a real key in this folder.

flowforge/_example/trip-planner/config.py

@@ -0,0 +1,27 @@
+"""Where every outside service lives. Keys come from the environment, except one planted mistake."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+
+# LLM: a local model through Ollama's OpenAI-compatible endpoint (free, nothing leaves the machine)
+OLLAMA_BASE_URL = os.getenv("OLLAMA_BASE_URL", "http://localhost:11434/v1")
+PLANNER_MODEL = os.getenv("PLANNER_MODEL", "llama3.1:8b")
+
+# HTTP APIs: free and keyless
+NOMINATIM_URL = "https://nominatim.openstreetmap.org/search"
+OPEN_METEO_URL = "https://api.open-meteo.com/v1/forecast"
+OSRM_URL = "https://router.project-osrm.org/route/v1/driving"
+IP_API_URL = "http://ip-api.com/json/"  # PLANTED: the free tier is plain http only, a security finding
+
+USER_AGENT = "flowforge-trip-planner-example/0.1 (+https://github.com/Vishwa-Thangapandiyan/flowforge-agent-orchestrator)"
+
+# PLANTED: a hard-coded key, the kind of mistake the scan must report. It is fake and never works.
+GOOGLE_STATIC_MAPS_KEY = "AIzaFAKEFAKEFAKEFAKEFAKE1234"
+STATIC_MAP_URL = "https://maps.googleapis.com/maps/api/staticmap"
+
+# MCP servers are listed in .mcp.json; the filesystem server may only touch this folder
+TRIPS_DIR = HERE / "trips"

flowforge/_example/trip-planner/mcp_servers/currency.py

@@ -0,0 +1,10 @@
+"""A currency MCP server that was never finished: it exits at start-up.
+
+PLANTED: FlowForge's health check should show this server as down, with the reason below.
+"""
+
+import os
+import sys
+
+if not os.getenv("CURRENCY_API_URL"):
+    sys.exit("currency server: CURRENCY_API_URL is not set")

flowforge/_example/trip-planner/planner.py

@@ -0,0 +1,113 @@
+"""Plan a day trip: `python planner.py Mangalore --to "Panambur Beach"`.
+
+Each outside call is tried on its own; a failed one is reported and the plan goes on without it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import subprocess
+import sys
+from collections.abc import Awaitable
+from datetime import date
+from urllib.parse import urlencode
+
+import httpx
+
+from config import GOOGLE_STATIC_MAPS_KEY, HERE, STATIC_MAP_URL, TRIPS_DIR
+from services import geo, llm, mcp_tools, weather
+
+
+async def attempt[T](label: str, work: Awaitable[T]) -> T | None:
+    """Await `work`; on any failure print why and return None."""
+    try:
+        result = await work
+    except Exception as exc:  # the demo keeps going without this piece
+        while isinstance(exc, ExceptionGroup):  # MCP's task groups wrap the real reason
+            exc = exc.exceptions[0]
+        print(f"  ✗ {label}: {str(exc) or type(exc).__name__}")
+        return None
+    print(f"  ✓ {label}")
+    return result
+
+
+def packing_list(max_c: float, rain: float) -> str:
+    """The local tool, run as a separate program (an argv list, never a shell)."""
+    done = subprocess.run([sys.executable, str(HERE / "tools" / "packing_list.py"),
+                           "--max-c", str(max_c), "--rain", str(rain)],
+                          capture_output=True, text=True, timeout=10, check=True)
+    return done.stdout.strip()
+
+
+def static_map_link(place: geo.Place) -> str:
+    query = {"center": f"{place.lat},{place.lon}", "zoom": 13, "size": "600x300", "key": GOOGLE_STATIC_MAPS_KEY}
+    return f"{STATIC_MAP_URL}?{urlencode(query)}"
+
+
+async def plan(city: str, sight: str | None) -> None:
+    print(f"Planning a day in {city}…")
+    async with httpx.AsyncClient(timeout=20) as client:
+        home = await attempt("where you are (ip-api)", geo.where_am_i(client))
+        place = await attempt("find the city (Nominatim)", geo.find_place(client, city))
+        if place is None:
+            print("Can't plan without the city's location.")
+            return
+        target = None
+        if sight:
+            target = await attempt("find the sight (Nominatim)", geo.find_place(client, f"{sight}, {city}"))
+        trip = await attempt("route to the sight (OSRM)", geo.route(client, place, target)) if target else None
+        forecast = await attempt("today's weather (Open-Meteo)", weather.today(client, place.lat, place.lon))
+
+    local_time = None
+    if forecast:
+        local_time = await attempt("local time (MCP time)", mcp_tools.call(
+            "time", "get_current_time", {"timezone": forecast["timezone"]}))
+    background = await attempt("about the city (MCP fetch)", mcp_tools.call(
+        "fetch", "fetch", {"url": f"https://en.wikipedia.org/wiki/{city.replace(' ', '_')}", "max_length": 1500}))
+    rate = await attempt("rupee rate (MCP currency)", mcp_tools.call("currency", "rate", {"to": "USD"}))
+    packing = None
+    if forecast:
+        try:
+            packing = packing_list(forecast["max_c"], forecast["rain_chance"])
+            print("  ✓ packing list (local tool)")
+        except (OSError, subprocess.SubprocessError) as exc:
+            print(f"  ✗ packing list (local tool): {exc}")
+
+    facts = [f"City: {place.name}", f"Traveller is in: {home or 'unknown'}"]
+    if target and trip:
+        facts.append(f"Sight: {target.name}, {trip['km']} km and {trip['minutes']} min by car from the centre")
+    if forecast:
+        facts.append(f"Weather: {forecast['min_c']}–{forecast['max_c']} °C, {forecast['rain_chance']}% chance of rain")
+    if local_time:
+        facts.append(f"Local time: {local_time}")
+    if rate:
+        facts.append(f"Exchange rate: {rate}")
+    if background:
+        facts.append(f"About the city: {background[:1200]}")
+    itinerary = await attempt("write the plan (Ollama)", llm.write_itinerary("\n".join(facts)))
+
+    print()
+    print(itinerary or "No plan written: the LLM wasn't reachable. Is Ollama running?")
+    if packing:
+        print(f"\nPack: {packing}")
+    print(f"\nMap: {static_map_link(place)}")
+    if itinerary:
+        TRIPS_DIR.mkdir(exist_ok=True)
+        path = TRIPS_DIR / f"{city.lower().replace(' ', '-')}-{date.today()}.md"
+        saved = await attempt("save the plan (MCP files)", mcp_tools.call(
+            "files", "write_file", {"path": str(path), "content": itinerary}))
+        if saved is not None:
+            print(f"Saved to {path.relative_to(HERE)}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Plan a relaxed day trip with free, keyless services.")
+    parser.add_argument("city")
+    parser.add_argument("--to", dest="sight", help="a sight in the city, for the route")
+    args = parser.parse_args()
+    asyncio.run(plan(args.city, args.sight))
+
+
+if __name__ == "__main__":
+    main()

flowforge/_example/trip-planner/requirements.txt

@@ -0,0 +1,3 @@
+httpx>=0.27
+mcp>=2.0
+openai>=1.40

flowforge/_example/trip-planner/services/geo.py

@@ -0,0 +1,49 @@
+"""Places and routes: Nominatim (place → coordinates), OSRM (driving route), ip-api (where you are)."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+import httpx
+
+from config import IP_API_URL, NOMINATIM_URL, OSRM_URL, USER_AGENT
+
+# Nominatim's usage policy: at most one request a second, with a User-Agent that names the app
+_NOMINATIM_GAP_S = 1.1
+
+
+@dataclass
+class Place:
+    name: str
+    lat: float
+    lon: float
+
+
+async def find_place(client: httpx.AsyncClient, query: str) -> Place:
+    response = await client.get(NOMINATIM_URL, params={"q": query, "format": "json", "limit": 1},
+                                headers={"User-Agent": USER_AGENT})
+    response.raise_for_status()
+    results = response.json()
+    if not results:
+        raise LookupError(f"no place called {query!r}")
+    first = results[0]
+    await asyncio.sleep(_NOMINATIM_GAP_S)
+    return Place(first["display_name"].split(",")[0], float(first["lat"]), float(first["lon"]))
+
+
+async def route(client: httpx.AsyncClient, start: Place, end: Place) -> dict[str, float]:
+    """Driving distance (km) and time (minutes) from the public OSRM demo server."""
+    coords = f"{start.lon},{start.lat};{end.lon},{end.lat}"
+    response = await client.get(f"{OSRM_URL}/{coords}", params={"overview": "false"})
+    response.raise_for_status()
+    best = response.json()["routes"][0]
+    return {"km": round(best["distance"] / 1000, 1), "minutes": round(best["duration"] / 60)}
+
+
+async def where_am_i(client: httpx.AsyncClient) -> str:
+    """Your city from your IP address (ip-api's free tier, plain http)."""
+    response = await client.get(IP_API_URL, params={"fields": "status,city,country"})
+    response.raise_for_status()
+    data = response.json()
+    return f"{data['city']}, {data['country']}" if data.get("status") == "success" else "unknown"

flowforge/_example/trip-planner/services/llm.py

@@ -0,0 +1,18 @@
+"""The itinerary writer: a local Ollama model through the OpenAI SDK."""
+
+from __future__ import annotations
+
+from openai import AsyncOpenAI
+
+from config import OLLAMA_BASE_URL, PLANNER_MODEL
+
+SYSTEM = ("You plan one relaxed day trip. Use only the facts given. "
+          "Answer in short markdown: a title, then Morning, Afternoon and Evening, two bullets each.")
+
+
+async def write_itinerary(facts: str) -> str:
+    client = AsyncOpenAI(base_url=OLLAMA_BASE_URL, api_key="ollama", timeout=180)  # Ollama ignores the key
+    reply = await client.chat.completions.create(
+        model=PLANNER_MODEL, temperature=0.3,
+        messages=[{"role": "system", "content": SYSTEM}, {"role": "user", "content": facts}])
+    return reply.choices[0].message.content or ""

flowforge/_example/trip-planner/services/mcp_tools.py

@@ -0,0 +1,26 @@
+"""MCP servers from .mcp.json: local time, page fetch, saving files, and a broken currency server."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+from config import HERE
+
+SERVERS: dict[str, dict[str, Any]] = json.loads((HERE / ".mcp.json").read_text(encoding="utf-8"))["mcpServers"]
+
+
+async def call(server: str, tool: str, arguments: dict[str, Any]) -> str:
+    """Start one server from .mcp.json, call one tool, return its text."""
+    spec = SERVERS[server]
+    params = StdioServerParameters(command=spec["command"], args=spec.get("args", []), cwd=str(HERE))
+    async with stdio_client(params) as (read, write), ClientSession(read, write) as session:
+        await session.initialize()
+        result = await session.call_tool(tool, arguments)
+    text = "\n".join(block.text for block in result.content if getattr(block, "type", "") == "text")
+    if result.is_error:
+        raise RuntimeError(text or f"{server}.{tool} failed")
+    return text

flowforge/_example/trip-planner/services/weather.py

@@ -0,0 +1,25 @@
+"""Today's weather from Open-Meteo (free, no key)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from config import OPEN_METEO_URL
+
+
+async def today(client: httpx.AsyncClient, lat: float, lon: float) -> dict[str, Any]:
+    response = await client.get(OPEN_METEO_URL, params={
+        "latitude": lat, "longitude": lon, "timezone": "auto", "forecast_days": 1,
+        "daily": "temperature_2m_max,temperature_2m_min,precipitation_probability_max",
+    })
+    response.raise_for_status()
+    data = response.json()
+    daily = data["daily"]
+    return {
+        "timezone": data["timezone"],
+        "max_c": daily["temperature_2m_max"][0],
+        "min_c": daily["temperature_2m_min"][0],
+        "rain_chance": daily["precipitation_probability_max"][0],
+    }

flowforge/_example/trip-planner/tools/packing_list.py

@@ -0,0 +1,24 @@
+"""A local command: a packing list from today's weather. Called by planner.py as a subprocess."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--max-c", type=float, required=True)
+    parser.add_argument("--rain", type=float, required=True)
+    args = parser.parse_args()
+    items = ["water bottle", "phone charger"]
+    if args.max_c >= 28:
+        items += ["sunscreen", "cap"]
+    if args.max_c <= 15:
+        items.append("jacket")
+    if args.rain >= 40:
+        items.append("umbrella")
+    print(", ".join(items))
+
+
+if __name__ == "__main__":
+    main()

flowforge/_workflows/diamond_mock.json

@@ -0,0 +1,71 @@
+{
+  "id": "diamond_mock",
+  "name": "Mock diamond — hand-checkable (critical path a → b → e = 500 ms)",
+  "max_concurrency": 2,
+  "steps": [
+    {
+      "id": "a",
+      "type": "mock",
+      "params": {
+        "duration_ms": 100,
+        "step": "a"
+      }
+    },
+    {
+      "id": "b",
+      "type": "mock",
+      "depends_on": [
+        "a"
+      ],
+      "params": {
+        "duration_ms": 300,
+        "step": "b"
+      }
+    },
+    {
+      "id": "c",
+      "type": "mock",
+      "depends_on": [
+        "a"
+      ],
+      "params": {
+        "duration_ms": 100,
+        "step": "c"
+      }
+    },
+    {
+      "id": "d",
+      "type": "mock",
+      "depends_on": [
+        "a"
+      ],
+      "params": {
+        "duration_ms": 50,
+        "step": "d"
+      }
+    },
+    {
+      "id": "e",
+      "type": "mock",
+      "depends_on": [
+        "b",
+        "c"
+      ],
+      "params": {
+        "duration_ms": 100,
+        "step": "e"
+      }
+    },
+    {
+      "id": "f",
+      "type": "mock",
+      "depends_on": [
+        "d"
+      ],
+      "params": {
+        "duration_ms": 50,
+        "step": "f"
+      }
+    }
+  ]
+}

flowforge/_workflows/stripe_to_razorpay.json

@@ -0,0 +1,38 @@
+{
+  "id": "stripe_to_razorpay",
+  "name": "Stripe → Razorpay migration analysis",
+  "max_concurrency": 4,
+  "type_concurrency": { "llm": 3 },
+  "steps": [
+    { "id": "fetch_stripe_endpoints", "type": "http", "estimated_ms": 500,
+      "params": { "url": "https://docs.stripe.com/api/payment_intents.md", "max_chars": 8000 } },
+    { "id": "fetch_stripe_lifecycle", "type": "mcp", "estimated_ms": 2500,
+      "params": { "tool": "fetch", "arguments": { "url": "https://docs.stripe.com/api/payment_intents", "max_length": 6000 } } },
+    { "id": "fetch_razorpay_endpoints", "type": "http", "estimated_ms": 500,
+      "params": { "url": "https://razorpay.com/docs/api/payments.md", "max_chars": 8000 } },
+    { "id": "fetch_razorpay_for_risks", "type": "http", "estimated_ms": 500,
+      "description": "Deliberate duplicate of fetch_razorpay_endpoints: the cache should make only one request.",
+      "params": { "url": "https://razorpay.com/docs/api/payments.md", "max_chars": 8000 } },
+
+    { "id": "summarize_stripe", "type": "llm", "depends_on": ["fetch_stripe_endpoints"], "estimated_ms": 4000,
+      "params": { "temperature": 0, "max_tokens": 600,
+        "prompt": "List every Stripe PaymentIntent endpoint (method + path) with a one-line purpose, from these docs:\n\n{{steps.fetch_stripe_endpoints.output.body}}" } },
+    { "id": "summarize_stripe_lifecycle", "type": "llm", "depends_on": ["fetch_stripe_lifecycle"], "estimated_ms": 3000,
+      "params": { "temperature": 0, "max_tokens": 400,
+        "prompt": "Describe the PaymentIntent status lifecycle (each status and what moves it to the next) from these Stripe docs:\n\n{{steps.fetch_stripe_lifecycle.output.content}}" } },
+    { "id": "summarize_razorpay", "type": "llm", "depends_on": ["fetch_razorpay_endpoints"], "estimated_ms": 4000,
+      "params": { "temperature": 0, "max_tokens": 600,
+        "prompt": "List every Razorpay Payments API endpoint (method + path) with a one-line purpose, from these docs:\n\n{{steps.fetch_razorpay_endpoints.output.body}}" } },
+
+    { "id": "map_endpoints", "type": "llm", "depends_on": ["summarize_stripe", "summarize_razorpay"], "estimated_ms": 6000,
+      "params": { "temperature": 0, "max_tokens": 800,
+        "prompt": "Map each Stripe endpoint to its closest Razorpay equivalent as a markdown table. Flag anything with no equivalent.\n\nSTRIPE:\n{{steps.summarize_stripe.output.text}}\n\nRAZORPAY:\n{{steps.summarize_razorpay.output.text}}" } },
+
+    { "id": "migration_notes", "type": "llm", "depends_on": ["map_endpoints", "summarize_stripe_lifecycle"], "estimated_ms": 6000,
+      "params": { "temperature": 0, "max_tokens": 900,
+        "prompt": "Write step-by-step migration notes (Python) for moving a Stripe PaymentIntent integration to Razorpay, using this mapping and lifecycle.\n\nMAPPING:\n{{steps.map_endpoints.output.text}}\n\nSTRIPE LIFECYCLE:\n{{steps.summarize_stripe_lifecycle.output.text}}" } },
+    { "id": "risk_report", "type": "llm", "depends_on": ["map_endpoints", "fetch_razorpay_for_risks"], "estimated_ms": 4000,
+      "params": { "temperature": 0, "max_tokens": 500,
+        "prompt": "List the top migration risks (currency, refunds, idempotency, webhooks) given this mapping and the Razorpay docs.\n\nMAPPING:\n{{steps.map_endpoints.output.text}}\n\nRAZORPAY DOCS:\n{{steps.fetch_razorpay_for_risks.output.body}}" } }
+  ]
+}

flowforge/agent/__init__.py

@@ -0,0 +1,5 @@
+"""FlowForge as an MCP server for coding agents (D28, D29)."""
+
+from flowforge.agent.server import AGENT_CALLS_SETTING, build_server, preview
+
+__all__ = ["AGENT_CALLS_SETTING", "build_server", "preview"]