[AkhileshNegi]

Issue

Closes #PLEASE_TYPE_ISSUE_NUMBER

Summary

• Before: publishing a flow with a coordinator node resulted in a 422 error as coordinators were not supported, and sessions only executed onboarding nodes.
• Now: flows can be published with a coordinator, routing turns to return the onboarding agent's reply.
• Added new publish rules ensuring the coordinator has outgoing edges.
• Updated API documentation and tests to support the new coordinator flow.

Checklist

Before submitting a pull request, please ensure that you mark these task.

• Ran fastapi run --reload app/main.py or docker compose up in the repository root and test.
• If you've fixed a bug or added code that is tested and has test cases.

Notes

Please add here if any other information is required for the reviewer.

Original PR description

Summary

coordinator nodes now run. A coordinator reads each message, matches it to one of its outgoing edges by data.intent, and hands off to that onboarding node in the same turn. If nothing matches, it asks a clarifying question. When an onboarding sub-flow finishes, the session goes back to the coordinator.

sequenceDiagram
    participant Worker as process_chatbot_session_message
    participant Coord as run_coordinator_turn
    participant Agent as run_chatbot_turn (onboarding)
    Worker->>Worker: resolve coordinator + every route target's settings (one DB session, before any LLM call)
    Worker->>Coord: history + message + routes
    alt intent matched
        Coord-->>Worker: target_node_id
        Worker->>Agent: target prompt/config, shared collected_fields
        Agent-->>Worker: reply, is_complete
        Worker->>Worker: active_node_id = complete ? coordinator : target
    else no clear match
        Coord-->>Worker: clarifying_question
        Worker->>Worker: active_node_id unchanged
    end
    Worker-->>Worker: store reply (node_id = replying node), POST webhook

Loading

The coordinator is one structured-output call (RouteDecision{intent, clarifying_question}). It doesn't use LangGraph. Intents are matched case-insensitively.

New publish rules (_list_coordinator_problems):

 validate_flow_for_publish
   _list_structural_problems
+  _list_coordinator_problems
+    ≤ 1 coordinator per flow
+    coordinator has ≥ 1 outgoing edge
+    every coordinator edge → onboarding node
+    every coordinator edge has non-empty data.intent, unique (casefolded)

Other changes:

• to_provider_error and STRUCTURED_OUTPUT_METHOD moved from the onboarding graph to services/chatbot/utils.py, so both agents share them.
• update_chatbot_session_progress takes an optional active_node_id. Passing None leaves it unchanged.
• API docs (publish_flow, save_flow, send_session_message) and the wiki (modules/chatbot.md, domain-map.md) are updated.

Evidence

• Before: publishing a flow with a coordinator node → 422 coordinator ... not supported yet. Sessions only ran onboarding nodes.
  After: the flow publishes, and a routed turn returns the onboarding agent's reply with node_id = the agent node.

New tests:

coordinator/test_graph.py
  test_matching_intent_routes_to_its_target
  test_no_matching_intent_asks_the_models_question
  test_opening_turn_clarifies_even_when_model_names_an_intent
  test_routing_failure_becomes_provider_error
services/test_session.py
  test_matched_intent_hands_off_to_target_in_the_same_turn
  test_ambiguous_message_asks_fallback_question_and_keeps_fields
  test_target_completing_in_the_routed_turn_returns_to_coordinator
  test_entry_onboarding_flow_stays_on_its_node_after_completion
services/test_flow.py
  test_intents_differing_only_by_case_are_duplicates
api/routes/chatbot/test_flow.py
  test_coordinator_flow_publishes_with_its_config_version_pinned
  422 cases: no routes, route to rag/output/coordinator, missing/duplicate intent
crud/test_chatbot.py
  test_active_node_moves_only_when_given

Local run: coordinator/ + services/chatbot/test_flow.py → 36 passed. I couldn't run the DB-backed suites locally because my test DB is stamped with a migration from another branch (089). CI should run them.

Merge Danger

Door: two-way

No migration and no schema change. Reverting brings back the old publish rule. A live flow published with a coordinator would then fail its turns with a failure webhook (not supported yet) until it's republished without one.

Blast Radius: chatbot-only

• completion_status now applies to one sub-flow in coordinator flows: it's complete on the turn that finishes a sub-flow and in_progress again on the next turn. Webhook consumers that treat complete as "session done" need to know this (documented in send_session_message.md).
• Flows that start on an onboarding node work as before.
• A routed turn makes 3 LLM calls (routing, extraction, reply), so it has more latency and token cost than a plain onboarding turn.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one): 1

• ready-for-review

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: ProjectTech4DevAI/kaapi-backend
• Branch: feature/chatbot-coordinator-node
• File: .coderabbit.yaml
• Commit: b33666a
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: e106f244-3b99-43c5-b921-2fb7f3179e17

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

CodeRabbit Verify

• Run CodeRabbit Verify to test the changes in this pull request.

[github-actions]

OpenAPI changes   ⚪ No API surface changes

Note

This PR does not modify the API contract.

_{main ↔ b4b0d27d · generated by oasdiff}

[codecov]

Codecov Report

❌ Patch coverage is 99.27361% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
backend/app/services/chatbot/session.py	95.16%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!