[Epic] Semantic alignment for coffee-farm price agreement

[codyhartsook]

[WIP] High-level epic draft. Intent and components are settled; deliverables below will be broken out into sub-issues. Details may still change.

Dependencies

• Blocked by Add IoC CFN infrastructure setup in local docker compose and private deployment #700 - the IoC CFN infrastructure (CFN service, mgmt backend, cognition engines, knowledge/memory) must be running via local docker compose / private deployment before this negotiation loop can be exercised end-to-end.

Intent

Give the three existing coffee-farm A2A agents (Brazil, Colombia, Vietnam) the ability to negotiate and agree on a single commodity coffee price - plus contract duration and delivery terms - using the IoC CFN semantic-alignment (SAO) cognition engine.

Today the pieces exist but nothing connects them:

• The CFN semantic-alignment engine is a caller-mediated referee: it discovers negotiable issues/options, seeds and evaluates offers, and detects agreement. It speaks SSTP-over-HTTP and never calls the agents.
• The farms are A2A servers that expect to be called, each on a different framework (LlamaIndex, LangGraph, Google ADK).

This epic delivers the missing bridge (an orchestrator) plus a negotiate skill on each farm, so a full start -> decide SAO loop runs end-to-end and the farms converge on a shared agreement grounded in each farm's private economics.

Scope / architecture

In the caller-mediated model the orchestrator drives the CFN loop and, each round, calls each farm over A2A to decide, then hands replies back to the engine. The one production change is marked in the diagram: the per-farm decision step becomes a real A2A call to that farm's negotiate skill.

Setup - mgmt backend (:9000)

orchestrator --> POST /api/auth/login                       => access_token
orchestrator --> GET  /api/workspaces                       => workspace_id
orchestrator --> POST /api/workspaces/{wid}/                => mas_id,
                      multi-agentic-systems (create/lookup)     agents [{id, name}]

Negotiation loop - CFN (:9002) + SAO engine (:8089)

orchestrator                     CFN / SAO engine                 farms (A2A)
    |                                                                  |
    | POST .../semantic-negotiation/start                              |
    |   {session_id, agents, content_text, n_steps} -->                |
    |                        IntentDiscovery  -> issues                |
    |                        OptionsGeneration -> options_per_issue    |
    | <-- {status:"initiated", messages[]}   (round 1 seed offer)      |
    |                                                                  |
    |===== round loop: while status not in {agreed, broken, timeout} ==|
    |                                                                  |
    |  for each message in messages[]:                                 |
    |    payload.action           = "propose" | "respond"              |
    |    payload.allowed_actions  = valid replies this round           |
    |    payload.current_offer    = {issue: option}                    |
    |    semantic_context.issues / .options_per_issue                  |
    |                                                                  |
    |  -- A2A call: negotiate(message-as-JSON) ----------------------> negotiate skill
    |         (per-farm decision step)                      reasons over farm's
    |  <-- {action: accept|reject|counter_offer, offer?, reason} ----- private economics
    |                                                                  |
    |  agent_replies += {participant_id, action, offer?}               |
    |                                                                  |
    | POST .../semantic-negotiation/decide                             |
    |   {session_id, agent_replies} -->                                |
    |                        SAO evaluate; snap free-text              |
    |                        offers to nearest option                  |
    | <-- {status, round, messages[] | final_result}                   |
    |===== loop with next messages[] ==================================|
    |                                                                  |
  summarize(final_result): final_agreement, validation, conflicts

Note: the ioc-cfn-mas-client-lib SDK's start_alignment / advance_alignment are thin wrappers over these semantic-negotiation/start and /decide endpoints.

Components

Component	New / existing	Location	Role
CFN service (:9002) + semantic-alignment engine (:8089)	existing (deployed)	-	The referee: start discovers issues/options, decide advances SAO rounds
ioc-cfn-mas-client-lib SDK	existing	pip package	start_alignment / advance_alignment wrappers over CFN /start and /decide
Orchestrator (coffee_alignment.py)	new	coffee_agents/lungo/agents/supervisors/auction/	Drives the round loop; bridges engine <-> farms via existing A2A infra (farm_registry, a2a_client_factory, send_a2a_with_retry)
Negotiate skill (per farm)	new	each farm's agent.py	Parses the JSON negotiate payload, reasons over that farm's private economics, returns {action, offer?, reason}
Brazil farm agent	existing	farms/brazil/ - LlamaIndex + LiteLLM, :9999	Add negotiate branch to intent classifier
Colombia farm agent	existing	farms/colombia/ - LangGraph + LangChain, :9998	Add NEGOTIATE node/edge to the graph
Vietnam farm agent	existing	farms/vietnam/ - Google ADK + LiteLLM, :9997	Add a negotiation_agent sub-agent for ADK delegation

Deliverables (candidate sub-issues)

• Verify the deployed CFN response shape - run start_alignment once, confirm messages / issues / options_per_issue keys and per-message payload fields; adjust the loop.
• Negotiate skill: Brazil (LlamaIndex, simplest) - add intent branch + utility-table prompt; test in isolation over A2A.
• Negotiate skill: Colombia (LangGraph node/edge).
• Negotiate skill: Vietnam (ADK sub-agent).
• Orchestrator coffee_alignment.py - the start/decide round driver + SSTP<->A2A bridge.
• End-to-end run + tuning - run all three farms, inspect round-by-round dialogue, tune content_text and per-farm economics until agreements are sensible.

Design caveats / open questions

• Price is discretized into option buckets, not a continuous number - biggest fit question. Decide if SAO-over-buckets is acceptable or if a finer option grid / post-processing is needed.
• Roles rotate per round - each farm must handle both proposer (propose -> counter_offer) and responder (respond -> accept/reject).
• Genuinely different private economics per farm so they don't trivially converge or deadlock (Vietnam drives price down, Colombia holds it up, Brazil splits).
• agent_id must match farm_registry slugs (brazil/colombia/vietnam) - they round-trip as participant_id.
• Negotiate intent detection - recommend a try-parse-JSON guard over extending each farm's LLM classifier.

Prerequisites

• CFN reachable (http://localhost:9002) with the semantic-alignment engine running; a registered workspace_id + mas_id.
• pip install ioc-cfn-mas-client-lib.
• All three farm servers running (:9999, :9998, :9997).

References

• Semantic-alignment docs (general): https://github.com/outshift-open/ioc-cfn-svc/blob/main/docs/semantic-alignment.md
• Hosted reference implementation (actual negotiation mechanics / proof-of-flow): https://gist.github.com/codyhartsook/2002b5bfd3ea7027ce57b76b66420ec4
• cfn-testing/POC.md, SEMANTIC_ALIGNMENT_FINDINGS.md
• ioc-cfn-cognition-engines/semantic_alignment/evaluation/framework/ (reference loop + negotiate prompt)
• Related infra epic: Add IoC CFN infrastructure setup in local docker compose and private deployment #700