Co-consult

Directory examples/python/co_consult

Follow a travel request through intake, parallel flight/hotel/activity searches, advisory research and an evidence-checked proposal. Follow-up chat reuses saved searches. The example registers 31 capabilities under co-consult, version 0.3.0, and includes an installable node manifest with entrypoint node:app. This is application logic built on the shared runtime.

Agent node label co-consult, version 0.3.0.

Capabilities

Commands

Taken from this example's own README and module docstrings.

ATFGRAPH_SERVER=http://127.0.0.1:18880 python -m examples.python.co_consult.client_demo
docker compose -f examples/python/co_consult/compose.yaml up --build
python -m atfgraph.worker --module examples.python.co_consult.main:app --server http://127.0.0.1:18880
python -m atfgraph.worker --module node:app --server http://127.0.0.1:18880

Files

• examples/python/co_consult/README.md
• examples/python/co_consult/__init__.py
• examples/python/co_consult/agent.py
• examples/python/co_consult/agentnode.yaml
• examples/python/co_consult/client_demo.py
• examples/python/co_consult/conversation.py
• examples/python/co_consult/desks/__init__.py
• examples/python/co_consult/desks/activities.py
• examples/python/co_consult/desks/context.py
• examples/python/co_consult/desks/flights.py
• examples/python/co_consult/desks/hotels.py
• examples/python/co_consult/desks/intake.py
• examples/python/co_consult/desks/proposal.py
• examples/python/co_consult/fixtures.py
• examples/python/co_consult/helpers.py
• examples/python/co_consult/main.py
• examples/python/co_consult/models.py
• examples/python/co_consult/node.py
• examples/python/co_consult/requirements.txt
• examples/python/co_consult/response_types.py
• examples/python/co_consult/runtime.py
• examples/python/co_consult/sample_chat.json
• examples/python/co_consult/sample_payload.json
• examples/python/co_consult/saved.py
• examples/python/co_consult/shopstore.py
• examples/python/co_consult/suppliers/__init__.py
• examples/python/co_consult/suppliers/config.py
• examples/python/co_consult/suppliers/http.py
• examples/python/co_consult/suppliers/livn.py
• examples/python/co_consult/suppliers/sabre.py
• examples/python/co_consult/suppliers/serpapi.py

README

Rendered from examples/python/co_consult/README.md; the source file is not modified.

Follow a travel request through intake, parallel flight/hotel/activity searches, advisory research and an evidence-checked proposal. Follow-up chat reuses saved searches. The example registers 31 capabilities under co-consult, version 0.3.0, and includes an installable node manifest with entrypoint node:app. This is application logic built on the shared runtime.

Choose supplier behavior explicitly with CO_CONSULT_MODE:

Live failures remain visible: a desk reports missing settings, network failures or provider rejection, and the proposal lists the gap as partial. It never substitutes fixture inventory. This application does not book or hold inventory. Sabre quotes need revalidation, hotel rates are indicative, and activities show catalogue from-prices. Currency stays attached to each price; totals are not silently combined across currencies.

Decision generation has its own switch. The default CO_CONSULT_DECISIONS=model uses the configured SDK model URL/name. Select CO_CONSULT_DECISIONS=fixture for deterministic decisions; the proposal identifies them in confidence_caveats. Supplier fixture mode alone does not disable model calls.

flowchart TD
    entry[consult or chat] --> intake[intake_brief -> extract_brief]
    intake --> route[plan_trip -> resolve_route -> resolve_airport if needed]
    route --> flights[flights_desk]
    route --> hotels[hotels_desk]
    route --> activities[activities_desk]
    flights --> fare[flight_shop: fixture or Sabre -> rank_flight_offers -> interpret_fare_rules -> offer_detail from the saved shop]
    hotels --> property[hotel_search: fixture or SerpAPI -> rank_hotel_shortlist -> assess_property -> hotel_detail, cached per token]
    activities --> catalogue[frame_activity_query -> activity_search: fixture or LIVN MCP, up to twice -> rank_activities]
    fare --> context[context_desk -> plan_context_lookups -> context_lookup: fixture or SerpAPI -> summarise_lookup]
    property --> context
    catalogue --> context
    context --> propose[propose -> provenance_check + budget_fit -> compose_recommendation -> build_proposal]
    propose --> saved[Session memory: brief, shops, tracks, proposal]
    saved --> follow[chat follow-up or new selections; no supplier call]

Nested calls use app.traverse, giving each child its own ID under a shared root. Session memory stores raw supplier results under co-consult.shop.<shop_id>; child inputs pass compact shortlists rather than full responses.

Live supplier clients (suppliers/)

Supplier clients share an 8-connection HTTP pool with a 16 MB response cap. Timeout defaults to 60 seconds; CO_CONSULT_SUPPLIER_RETRIES defaults to two extra attempts for transport errors and HTTP 408/429/5xx, with exponential backoff. Other 4xx responses do not retry.

Reported errors scrub configured secrets and Bearer/API-key fragments; raw exception text is excluded. Startup checks refer to variable names rather than values. In live mode, check_live_configuration() refuses startup when no supplier is configured and reports missing names otherwise.

Environment (names only; set values in your own environment or node config)

Set values in your environment or managed node configuration. The example itself does not load .env; installed-node commands manage their own environment files and exclude them from package archives.

Tracing

main.py defaults to MLflow enabled, tracking URI databricks, and experiment /Shared/atfgraph/co-consult; existing environment values win. Requirements include MLflow. For successful export, the App service principal needs experiment permissions, or a laptop needs a Databricks profile/host credential. Set ATFGRAPH_MLFLOW_TRACING=false to disable it or choose a local tracking URI.

The Console links stored trace metadata when forwarding succeeds. Default traces include execution names, timing, outcomes and usage, excluding payloads. ATFGRAPH_MLFLOW_CAPTURE_PAYLOADS=true adds inputs, outputs, prompts and replies for evaluation; experiment readers can then see traveller and supplier content. See the MLflow guide for capture and redaction controls.

Run

From the vNext checkout (module form)

From a checkout with the SDK installed and a server listening on 127.0.0.1:18880:

python -m atfgraph.worker --module examples.python.co_consult.main:app --server http://127.0.0.1:18880
ATFGRAPH_SERVER=http://127.0.0.1:18880 python -m examples.python.co_consult.client_demo

For live supplier searches, change CO_CONSULT_MODE to live and configure the supplier variables. Configure decision mode separately.

As an installed agent node (directory packaging)

The package manifest uses node:app. Its node.py makes the project importable as co_consult, preserving relative imports when installed and run from the package root.

target/debug/atfg install examples/python/co_consult --python python3 --sdk python
target/debug/atfg run co-consult
target/debug/atfg traverse co-consult.consult --new-session \
  --in '{"request":"A relaxed family trip with museums and gardens","origin":"Brisbane","destination":"Tokyo","depart_date":"2027-05-01","return_date":"2027-05-08","adults":2,"children_ages":"8,11","budget":"AUD 6000"}'
target/debug/atfg traverse co-consult.chat --session <session_id> --in '{"message":"Is that fare refundable?"}'
target/debug/atfg logs co-consult
target/debug/atfg stop co-consult
target/debug/atfg package examples/python/co_consult --out target/dist/packages

To run without package installation, start the worker from the project root:

cd examples/python/co_consult && python -m atfgraph.worker --module node:app --server http://127.0.0.1:18880

HTTP

curl -s -X POST http://127.0.0.1:18880/api/v2/sessions -H 'content-type: application/json' -d '{}'
curl -s -X POST http://127.0.0.1:18880/api/v2/traversers -H 'content-type: application/json' \
  -d '{"target":"co-consult.chat","session_id":"<session_id>","input":{"message":"Plan a family trip","hints":{"origin":"Brisbane","destination":"Tokyo","depart_date":"2027-05-01","return_date":"2027-05-08","adults":2,"children_ages":[8,11],"budget":"AUD 6000"}}}'
curl -s http://127.0.0.1:18880/api/v2/traversers/<id>
curl -s http://127.0.0.1:18880/api/v2/traversers/<id>/path

Docker Compose

Choose either the repository's complete stack or a standalone worker scaffold:

Complete stack. deploy/docker/compose.yaml includes the server and co-consult worker, using examples.python.co_consult.main:app by default with fixture suppliers. The Compose smoke/journey scripts exercise this stack:

export ATFGRAPH_API_KEY="$(openssl rand -hex 24)"   # required: the server binds 0.0.0.0 in its container
target/debug/atfg deploy compose up --name demo --build
target/debug/atfg deploy compose status --name demo
target/debug/atfg --server http://127.0.0.1:18880 --api-key "$ATFGRAPH_API_KEY" ls
target/debug/atfg deploy compose down --name demo --volumes --forget

For live suppliers, pass CO_CONSULT_MODE=live and supplier settings through the Compose environment. Review deploy/docker/README.md for image selection and rollback. Check decision settings separately before expecting a fully offline run.

Standalone worker. To connect co-consult containers to an existing server, generate a Dockerfile and compose.yaml in the project directory:

target/debug/atfg deploy scaffold examples/python/co_consult --target docker --label co-consult --module node:app
docker compose -f examples/python/co_consult/compose.yaml up --build

The scaffold runs python -m atfgraph.worker --module node:app --server "$ATFGRAPH_SERVER". Add the SDK to its requirements and configure the server URL/key. Selecting --target kubernetes generates a kustomize base under k8s/. Generated project files are distinct from the checked-in complete stack.

Sessions and follow-ups

consult and chat create a server session when none is supplied, and return its opaque ID. Send that ID on follow-up calls:

{"session_id": "<returned>", "message": "Is that fare refundable?"}
{"session_id": "<returned>", "message": "Choose the five-star hotel", "selections": {"property_tokens": ["<property_token>"]}}
{"session_id": "<returned>", "message": "Search fresh options", "refresh": true, "hints": {"depart_date": "2027-05-08", "return_date": "2027-05-15"}}

Session state lives at co-consult.state, updated with revision checks. Follow-ups and selection changes reuse saved shops without supplier calls and return source shop_ids. Use refresh=true when changing trip facts. A stable request_id deduplicates turns; interrupted attempts are reported rather than silently shopping again.

The worker credential owns sessions created here. A calling application must authenticate its users and authorize which session IDs each may reuse; the chat interface is not itself a user-authentication system.

Verify

cd python && .venv/bin/python -m pytest -c pyproject.toml ../tests/python_test_coconsult.py ../tests/test_coconsult_live.py -q

The fixture suite uses the in-memory graph double with a worker to check nested routing, gates, evidence, currencies, sessions, refresh and duplicate/interrupted turns. test_coconsult_live.py exercises the live-client code against local fake Sabre, SerpAPI and LIVN MCP services. It checks request shapes, saved follow-ups, passenger types, partial failures, retry/auth bounds, configuration errors, SSE replies and packaging. Despite its name, that suite does not contact real suppliers. Separate live searches require working credentials and provider access.