feat(c-examples): aviation foundation + c-tool-calls + c-subagents (PR 1 of 4)

cockpit/langgraph/streaming/python/prompts/subagents.md

@@ -1,12 +1,23 @@
-# Chat Subagents Orchestrator
+# Trip Planner Orchestrator
 
-You are the orchestrator in a multi-agent system. You coordinate specialized
-subagents to handle user requests:
+You coordinate three specialized subagents to plan a trip. You delegate work
+by calling the `task` tool with a `role` and `task_description`.
 
-- **Research Agent**: Gathers background information and context
-- **Analysis Agent**: Analyzes findings and identifies patterns
-- **Summary Agent**: Produces a concise summary of results
+The three roles, in the order you should always call them:
 
-When the user asks a question, acknowledge their request and explain that
-you are delegating work to your specialized subagents. Each subagent will
-process the task in sequence and their progress will be visible in the UI.
+1. `task(role="research", ...)` — gathers destination intel (airports, weather, conditions)
+2. `task(role="booking", ...)` — finds flight options between origin and destination
+3. `task(role="itinerary", ...)` — synthesizes a final trip plan combining research + bookings
+
+When the user asks about a trip (e.g., "plan a trip from LAX to Tokyo" or
+"I want to fly from Boston to Miami next week"), call task() three times in
+that order, then summarize the final plan in 1-2 sentences. Each subagent
+will process its task and its output will be visible in the chat-subagents UI.
+
+If the user's request is ambiguous (e.g., they don't mention airports), ask
+a clarifying question before delegating. Once you have origin + destination,
+delegate to all three subagents.
+
+Note: the dataset is limited to 10 US airports (LAX, JFK, SFO, ORD, BOS,
+ATL, DFW, SEA, MIA, DEN). If the user asks about an airport not in this
+list, the research subagent will note it; suggest a nearby supported airport.

cockpit/langgraph/streaming/python/prompts/tool-calls.md

@@ -1,13 +1,16 @@
-# Chat Tool Calls Assistant
+# Aviation Assistant — Tool Calls Demo
 
-You are an assistant with access to search, calculator, and weather tools.
-Use these tools proactively to answer user questions.
+You are a helpful aviation assistant with access to flight and airport data
+through three tools:
 
-Available tools:
-- **search**: Search the web for information on any topic
-- **calculator**: Evaluate mathematical expressions
-- **weather**: Get current weather for any city
+- **lookup_flight(flight_number)** — status, route, and gate for a specific flight
+- **get_airport_info(airport_code)** — airport name, city, weather, terminals, runways
+- **find_routes(from_code, to_code, date_offset_days)** — available flights between two airports
 
-When the user asks a question, use the appropriate tool(s) to gather
-information before responding. Combine results from multiple tools
-when needed. Always explain which tools you used and why.
+Use these tools whenever the user asks about flights, airports, or routes.
+Combine multiple calls when helpful (e.g., "compare LAX and JFK" → call
+get_airport_info twice). Always cite which tools you used and summarize
+the results clearly.
+
+If a flight number or airport code isn't recognized, say so and suggest
+alternatives from the dataset (LAX, JFK, SFO, ORD, BOS, ATL, DFW, SEA, MIA, DEN).

cockpit/langgraph/streaming/python/src/aviation_data.py

@@ -0,0 +1,159 @@
+"""Aviation mock dataset for c-* example demos.
+
+Hardcoded data for the c-tool-calls and c-subagents demos (and future c-*
+aviation-themed examples). Zero external API calls — everything is canned
+for deterministic demos and offline-friendly development.
+
+The dataset is small but cohesive: ~10 US airports, 4 major airlines,
+~30 flights criss-crossing those airports. Each airport has a static
+"current weather" entry that doesn't change between calls (for
+repeatability in screencasts and snapshot tests).
+"""
+
+# ── Airports ────────────────────────────────────────────────────────────────
+
+AIRPORTS = {
+    "LAX": {"code": "LAX", "name": "Los Angeles International", "city": "Los Angeles", "country": "USA",
+            "weather": {"temp_f": 72, "conditions": "Partly Cloudy"}, "terminals": 9, "runways": 4},
+    "JFK": {"code": "JFK", "name": "John F. Kennedy International", "city": "New York", "country": "USA",
+            "weather": {"temp_f": 58, "conditions": "Clear"}, "terminals": 6, "runways": 4},
+    "SFO": {"code": "SFO", "name": "San Francisco International", "city": "San Francisco", "country": "USA",
+            "weather": {"temp_f": 64, "conditions": "Foggy"}, "terminals": 4, "runways": 4},
+    "ORD": {"code": "ORD", "name": "O'Hare International", "city": "Chicago", "country": "USA",
+            "weather": {"temp_f": 48, "conditions": "Light Rain"}, "terminals": 4, "runways": 8},
+    "BOS": {"code": "BOS", "name": "Logan International", "city": "Boston", "country": "USA",
+            "weather": {"temp_f": 52, "conditions": "Overcast"}, "terminals": 4, "runways": 6},
+    "ATL": {"code": "ATL", "name": "Hartsfield-Jackson Atlanta International", "city": "Atlanta", "country": "USA",
+            "weather": {"temp_f": 68, "conditions": "Sunny"}, "terminals": 2, "runways": 5},
+    "DFW": {"code": "DFW", "name": "Dallas/Fort Worth International", "city": "Dallas", "country": "USA",
+            "weather": {"temp_f": 76, "conditions": "Sunny"}, "terminals": 5, "runways": 7},
+    "SEA": {"code": "SEA", "name": "Seattle-Tacoma International", "city": "Seattle", "country": "USA",
+            "weather": {"temp_f": 55, "conditions": "Drizzle"}, "terminals": 3, "runways": 3},
+    "MIA": {"code": "MIA", "name": "Miami International", "city": "Miami", "country": "USA",
+            "weather": {"temp_f": 82, "conditions": "Humid, Sunny"}, "terminals": 3, "runways": 4},
+    "DEN": {"code": "DEN", "name": "Denver International", "city": "Denver", "country": "USA",
+            "weather": {"temp_f": 60, "conditions": "Clear, Windy"}, "terminals": 1, "runways": 6},
+}
+
+# ── Airlines ────────────────────────────────────────────────────────────────
+
+AIRLINES = {
+    "AA": {"code": "AA", "name": "American Airlines", "hub": "DFW"},
+    "UA": {"code": "UA", "name": "United Airlines", "hub": "ORD"},
+    "DL": {"code": "DL", "name": "Delta Air Lines", "hub": "ATL"},
+    "B6": {"code": "B6", "name": "JetBlue Airways", "hub": "JFK"},
+}
+
+# ── Flights ─────────────────────────────────────────────────────────────────
+
+FLIGHTS = [
+    # United transcontinental
+    {"flight_number": "UA123", "airline": "UA", "from": "LAX", "to": "JFK",
+     "depart_local": "08:00", "arrive_local": "16:30", "duration_min": 330,
+     "status": "on_time", "gate": "B14", "aircraft": "Boeing 787"},
+    {"flight_number": "UA456", "airline": "UA", "from": "JFK", "to": "LAX",
+     "depart_local": "10:00", "arrive_local": "13:15", "duration_min": 375,
+     "status": "delayed", "gate": "T7-12", "aircraft": "Boeing 757"},
+    {"flight_number": "UA789", "airline": "UA", "from": "ORD", "to": "SFO",
+     "depart_local": "09:30", "arrive_local": "12:00", "duration_min": 270,
+     "status": "on_time", "gate": "C15", "aircraft": "Airbus A320"},
+
+    # American out of DFW hub
+    {"flight_number": "AA101", "airline": "AA", "from": "DFW", "to": "LAX",
+     "depart_local": "07:15", "arrive_local": "08:45", "duration_min": 210,
+     "status": "on_time", "gate": "A23", "aircraft": "Boeing 737"},
+    {"flight_number": "AA202", "airline": "AA", "from": "DFW", "to": "JFK",
+     "depart_local": "11:00", "arrive_local": "15:30", "duration_min": 210,
+     "status": "on_time", "gate": "D8", "aircraft": "Boeing 737"},
+    {"flight_number": "AA303", "airline": "AA", "from": "DFW", "to": "MIA",
+     "depart_local": "13:45", "arrive_local": "17:30", "duration_min": 165,
+     "status": "on_time", "gate": "C11", "aircraft": "Airbus A321"},
+    {"flight_number": "AA404", "airline": "AA", "from": "BOS", "to": "DFW",
+     "depart_local": "06:30", "arrive_local": "10:00", "duration_min": 270,
+     "status": "cancelled", "gate": "B5", "aircraft": "Boeing 737"},
+
+    # Delta hub-and-spoke from ATL
+    {"flight_number": "DL501", "airline": "DL", "from": "ATL", "to": "LAX",
+     "depart_local": "10:00", "arrive_local": "11:45", "duration_min": 285,
+     "status": "on_time", "gate": "F20", "aircraft": "Boeing 757"},
+    {"flight_number": "DL502", "airline": "DL", "from": "ATL", "to": "JFK",
+     "depart_local": "14:20", "arrive_local": "16:50", "duration_min": 150,
+     "status": "on_time", "gate": "B9", "aircraft": "Boeing 737"},
+    {"flight_number": "DL503", "airline": "DL", "from": "ATL", "to": "SEA",
+     "depart_local": "09:15", "arrive_local": "11:35", "duration_min": 320,
+     "status": "delayed", "gate": "A17", "aircraft": "Airbus A330"},
+    {"flight_number": "DL504", "airline": "DL", "from": "ATL", "to": "MIA",
+     "depart_local": "16:00", "arrive_local": "17:50", "duration_min": 110,
+     "status": "on_time", "gate": "T2", "aircraft": "Boeing 717"},
+
+    # JetBlue from JFK
+    {"flight_number": "B6601", "airline": "B6", "from": "JFK", "to": "LAX",
+     "depart_local": "07:30", "arrive_local": "10:55", "duration_min": 385,
+     "status": "on_time", "gate": "T5-12", "aircraft": "Airbus A321"},
+    {"flight_number": "B6602", "airline": "B6", "from": "JFK", "to": "BOS",
+     "depart_local": "12:15", "arrive_local": "13:30", "duration_min": 75,
+     "status": "on_time", "gate": "T5-9", "aircraft": "Embraer 190"},
+    {"flight_number": "B6603", "airline": "B6", "from": "JFK", "to": "MIA",
+     "depart_local": "15:45", "arrive_local": "18:55", "duration_min": 190,
+     "status": "on_time", "gate": "T5-15", "aircraft": "Airbus A320"},
+    {"flight_number": "B6604", "airline": "B6", "from": "BOS", "to": "MIA",
+     "depart_local": "09:00", "arrive_local": "12:35", "duration_min": 215,
+     "status": "on_time", "gate": "C42", "aircraft": "Airbus A320"},
+
+    # Denver hub (United secondary)
+    {"flight_number": "UA850", "airline": "UA", "from": "DEN", "to": "LAX",
+     "depart_local": "08:45", "arrive_local": "10:00", "duration_min": 135,
+     "status": "on_time", "gate": "B33", "aircraft": "Boeing 737"},
+    {"flight_number": "UA851", "airline": "UA", "from": "DEN", "to": "ORD",
+     "depart_local": "11:30", "arrive_local": "14:55", "duration_min": 145,
+     "status": "on_time", "gate": "B41", "aircraft": "Airbus A319"},
+    {"flight_number": "UA852", "airline": "UA", "from": "SFO", "to": "DEN",
+     "depart_local": "06:00", "arrive_local": "09:25", "duration_min": 145,
+     "status": "on_time", "gate": "F8", "aircraft": "Boeing 737"},
+
+    # Seattle (United + Delta)
+    {"flight_number": "UA901", "airline": "UA", "from": "SEA", "to": "ORD",
+     "depart_local": "07:00", "arrive_local": "12:55", "duration_min": 235,
+     "status": "on_time", "gate": "S2", "aircraft": "Boeing 737"},
+    {"flight_number": "DL902", "airline": "DL", "from": "SEA", "to": "ATL",
+     "depart_local": "14:30", "arrive_local": "22:05", "duration_min": 275,
+     "status": "on_time", "gate": "B12", "aircraft": "Boeing 757"},
+
+    # SFO-LAX shuttle
+    {"flight_number": "UA1001", "airline": "UA", "from": "SFO", "to": "LAX",
+     "depart_local": "06:00", "arrive_local": "07:25", "duration_min": 85,
+     "status": "on_time", "gate": "F3", "aircraft": "Airbus A320"},
+    {"flight_number": "UA1002", "airline": "UA", "from": "SFO", "to": "LAX",
+     "depart_local": "09:30", "arrive_local": "10:55", "duration_min": 85,
+     "status": "on_time", "gate": "F5", "aircraft": "Airbus A320"},
+    {"flight_number": "UA1003", "airline": "UA", "from": "LAX", "to": "SFO",
+     "depart_local": "08:00", "arrive_local": "09:25", "duration_min": 85,
+     "status": "on_time", "gate": "B22", "aircraft": "Airbus A320"},
+    {"flight_number": "UA1004", "airline": "UA", "from": "LAX", "to": "SFO",
+     "depart_local": "12:15", "arrive_local": "13:40", "duration_min": 85,
+     "status": "delayed", "gate": "B26", "aircraft": "Airbus A320"},
+
+    # Chicago hub (United + American)
+    {"flight_number": "UA710", "airline": "UA", "from": "ORD", "to": "BOS",
+     "depart_local": "06:30", "arrive_local": "09:45", "duration_min": 135,
+     "status": "on_time", "gate": "C12", "aircraft": "Boeing 737"},
+    {"flight_number": "AA711", "airline": "AA", "from": "ORD", "to": "DFW",
+     "depart_local": "07:15", "arrive_local": "09:50", "duration_min": 155,
+     "status": "on_time", "gate": "K8", "aircraft": "Boeing 737"},
+    {"flight_number": "UA712", "airline": "UA", "from": "ORD", "to": "DEN",
+     "depart_local": "10:00", "arrive_local": "11:30", "duration_min": 150,
+     "status": "on_time", "gate": "C20", "aircraft": "Embraer 175"},
+
+    # MIA southbound
+    {"flight_number": "AA801", "airline": "AA", "from": "MIA", "to": "JFK",
+     "depart_local": "08:00", "arrive_local": "11:00", "duration_min": 180,
+     "status": "on_time", "gate": "D40", "aircraft": "Boeing 737"},
+    {"flight_number": "DL802", "airline": "DL", "from": "MIA", "to": "ATL",
+     "depart_local": "12:30", "arrive_local": "14:20", "duration_min": 110,
+     "status": "on_time", "gate": "H5", "aircraft": "Boeing 717"},
+
+    # BOS additional
+    {"flight_number": "B6605", "airline": "B6", "from": "BOS", "to": "SFO",
+     "depart_local": "07:45", "arrive_local": "11:30", "duration_min": 405,
+     "status": "on_time", "gate": "C40", "aircraft": "Airbus A321"},
+]

cockpit/langgraph/streaming/python/src/aviation_tools.py

@@ -0,0 +1,90 @@
+"""LangChain @tool wrappers around the aviation mock dataset.
+
+Each tool's docstring is what the LLM sees for tool-selection — keep them
+informative and example-laden.
+"""
+
+from langchain_core.tools import tool
+from src.aviation_data import AIRPORTS, AIRLINES, FLIGHTS
+
+
+@tool
+async def lookup_flight(flight_number: str) -> dict:
+    """Look up the status, route, and gate for a specific flight number.
+
+    Use this when the user asks about a specific flight (e.g., "what's the
+    status of UA123?", "is AA404 on time?", "what gate is DL501 leaving from?").
+
+    Args:
+        flight_number: Flight number like 'UA123' or 'AA456'. Case-insensitive.
+
+    Returns:
+        dict with keys: flight_number, airline, from, to, depart_local,
+        arrive_local, status (on_time/delayed/cancelled), gate, aircraft,
+        duration_min.
+
+    Returns {"error": "Flight not found"} if the flight number is not in
+    the dataset.
+    """
+    fn = flight_number.upper().strip()
+    for f in FLIGHTS:
+        if f["flight_number"] == fn:
+            return f
+    return {"error": f"Flight {fn} not found in dataset"}
+
+
+@tool
+async def get_airport_info(airport_code: str) -> dict:
+    """Get details about an airport: name, city, current weather, terminals, runways.
+
+    Use this when the user asks about an airport (e.g., "what's the weather
+    at LAX?", "tell me about JFK", "how many runways does ORD have?").
+
+    Args:
+        airport_code: 3-letter IATA code like 'LAX' or 'JFK'. Case-insensitive.
+
+    Returns:
+        dict with keys: code, name, city, country, weather (with temp_f and
+        conditions), terminals, runways.
+
+    Returns {"error": "Airport not found"} if the code is not in the dataset.
+    """
+    code = airport_code.upper().strip()
+    if code in AIRPORTS:
+        return AIRPORTS[code]
+    return {"error": f"Airport {code} not in dataset. Available: {sorted(AIRPORTS.keys())}"}
+
+
+@tool
+async def find_routes(from_code: str, to_code: str, date_offset_days: int = 0) -> dict:
+    """Find available flights between two airports.
+
+    Use this when the user asks about flight options (e.g., "what flights
+    are there from LAX to JFK?", "find me a flight from Boston to Miami
+    tomorrow").
+
+    Args:
+        from_code: 3-letter IATA code for departure airport.
+        to_code: 3-letter IATA code for arrival airport.
+        date_offset_days: 0 = today, 1 = tomorrow, etc. Note: mock data is
+            the same regardless of date; the LLM can still reason about
+            the date in its response.
+
+    Returns:
+        dict with keys:
+          - "flights": list of flight dicts (same shape as lookup_flight)
+            sorted by depart_local, OR empty list if no routes.
+          - "from": echoed from_code
+          - "to": echoed to_code
+          - "date_offset_days": echoed
+    """
+    fc = from_code.upper().strip()
+    tc = to_code.upper().strip()
+    flights = sorted(
+        [f for f in FLIGHTS if f["from"] == fc and f["to"] == tc],
+        key=lambda f: f["depart_local"],
+    )
+    return {"from": fc, "to": tc, "date_offset_days": date_offset_days, "flights": flights}
+
+
+ALL_TOOLS = [lookup_flight, get_airport_info, find_routes]