From eb616a19aa94b7af92c98a96f2f9eb2c9bed5c86 Mon Sep 17 00:00:00 2001 From: Ayush8923 <80516839+Ayush8923@users.noreply.github.com> Date: Fri, 9 Oct 2026 23:14:33 +0530 Subject: [PATCH 1/8] feat(*): init chatbot flow --- .../086_seed_anthropic_text_model_configs.py | 60 ++++ backend/app/api/docs/chatbot/message.md | 7 + backend/app/api/docs/openapi_config.py | 5 + backend/app/api/main.py | 2 + backend/app/api/routes/chatbot.py | 64 +++++ backend/app/crud/config/version.py | 5 + backend/app/models/__init__.py | 6 + backend/app/models/chatbot.py | 56 ++++ backend/app/services/chatbot/config.py | 141 ++++++++++ backend/app/services/chatbot/engine.py | 260 ++++++++++++++++++ backend/app/services/chatbot/utils.py | 59 ++++ backend/pyproject.toml | 1 + backend/uv.lock | 86 +++++- docs/wiki/INDEX.md | 1 + docs/wiki/domain-map.md | 4 +- docs/wiki/modules/chatbot.md | 23 ++ docs/wiki/modules/platform.md | 13 + 17 files changed, 780 insertions(+), 13 deletions(-) create mode 100644 backend/app/alembic/versions/086_seed_anthropic_text_model_configs.py create mode 100644 backend/app/api/docs/chatbot/message.md create mode 100644 backend/app/api/routes/chatbot.py create mode 100644 backend/app/models/chatbot.py create mode 100644 backend/app/services/chatbot/config.py create mode 100644 backend/app/services/chatbot/engine.py create mode 100644 backend/app/services/chatbot/utils.py create mode 100644 docs/wiki/modules/chatbot.md diff --git a/backend/app/alembic/versions/086_seed_anthropic_text_model_configs.py b/backend/app/alembic/versions/086_seed_anthropic_text_model_configs.py new file mode 100644 index 000000000..915218568 --- /dev/null +++ b/backend/app/alembic/versions/086_seed_anthropic_text_model_configs.py @@ -0,0 +1,60 @@ +"""seed anthropic text model_config rows + +Revision ID: 086 +Revises: 085 +Create Date: 2026-10-09 00:00:00.000000 + +`anthropic` has been a valid provider since 066 but had no model_config rows, +so it never showed up in /models/providers and config-version updates could +not tell its models are reasoning models. The `effort` key in `config` is what +`is_reasoning_model` keys on — it makes `_strip_unsupported_params` drop +`temperature`, which the Messages API rejects at non-default values. + +`effort.default` is "high" because that is what the Messages API applies when +the param is omitted. Sonnet 4.6 does not expose the "xhigh" level. + +claude-opus-5-5 pricing is left NULL until list prices are confirmed; cost +estimation returns None for NULL pricing rather than a wrong number. + +Downgrade deletes the two rows by key, so a row that already existed before +upgrade (ON CONFLICT DO NOTHING skipped it) is removed as well. +""" + +from alembic import op + +revision = "086" +down_revision = "085" +branch_labels = None +depends_on = None + + +def upgrade(): + op.execute( + """ + INSERT INTO global.model_config + (provider, model_name, completion_type, config, input_modalities, + output_modalities, pricing, is_active, inserted_at, updated_at) + VALUES + ('anthropic', 'claude-sonnet-4-6', '{text}', + '{"effort": {"type": "enum", "default": "high", "options": ["low", "medium", "high", "max"], "description": "How long the model spends reasoning. Higher = better but slower."}}', + '{TEXT,IMAGE,FILES}', '{TEXT}', + '{"response": {"input_token_cost": 3, "output_token_cost": 15}, "batch": {"input_token_cost": 1.5, "output_token_cost": 7.5}}', + true, NOW(), NOW()), + ('anthropic', 'claude-opus-5-5', '{text}', + '{"effort": {"type": "enum", "default": "high", "options": ["low", "medium", "high", "xhigh", "max"], "description": "How long the model spends reasoning. Higher = better but slower."}}', + '{TEXT,IMAGE,FILES}', '{TEXT}', + NULL, + true, NOW(), NOW()) + ON CONFLICT (provider, model_name) DO NOTHING + """ + ) + + +def downgrade(): + op.execute( + """ + DELETE FROM global.model_config + WHERE provider = 'anthropic' + AND model_name IN ('claude-sonnet-4-6', 'claude-opus-5-5') + """ + ) diff --git a/backend/app/api/docs/chatbot/message.md b/backend/app/api/docs/chatbot/message.md new file mode 100644 index 000000000..75ee043c9 --- /dev/null +++ b/backend/app/api/docs/chatbot/message.md @@ -0,0 +1,7 @@ +Run one turn of a prompt-driven chatbot conversation and return the full updated transcript. + +The chat model comes from a saved Kaapi config: `config_id` must be a config in the caller's project whose completion is `provider: "anthropic"`, `type: "text"` with `params.model` set. `config_version` picks a version (latest if omitted). The config's `params.effort` sets reasoning effort (provider default if absent) and `params.thinking` overrides the default adaptive thinking. `max_tokens` (default 1024) and `history_token_limit` (default 4000; older turns are summarized above it) are optional per-request overrides. + +There is no server-side session yet: send the admin-authored `system_prompt` on every call, and send the previous response's `messages` back as `history`. The returned `messages` contain the system prompt followed by every user/assistant turn so far, ending with the new assistant reply. Any `system` entries in `history` are ignored in favour of `system_prompt`. + +On the very first call, send an empty `history` and omit `message` to get the bot's opening greeting. Once `history` is non-empty, `message` is required. Returns 404 if the config or version isn't found in the project, 422 for a missing `message` or a config that isn't a usable Anthropic text config, and 502 for provider failures. diff --git a/backend/app/api/docs/openapi_config.py b/backend/app/api/docs/openapi_config.py index 99cee7875..8b9fc7342 100644 --- a/backend/app/api/docs/openapi_config.py +++ b/backend/app/api/docs/openapi_config.py @@ -27,6 +27,10 @@ "name": "LLM", "description": "Large Language Model inference and interaction endpoints", }, + { + "name": "Chatbot", + "description": "Prompt-driven conversational chatbot turns", + }, { "name": "Evaluation", "description": "Dataset upload, running evaluations, listing datasets as well as evaluations", @@ -89,6 +93,7 @@ "Collections", "Config Management", "LLM", + "Chatbot", "Evaluation", "Fine Tuning", "Model Evaluation", diff --git a/backend/app/api/main.py b/backend/app/api/main.py index a796c58b6..c181ddf2c 100644 --- a/backend/app/api/main.py +++ b/backend/app/api/main.py @@ -5,6 +5,7 @@ api_keys, assistants, auth, + chatbot, collection_job, collections, config, @@ -47,6 +48,7 @@ api_router.include_router(assessment_api_routes.router) api_router.include_router(assistants.router) api_router.include_router(auth.router) +api_router.include_router(chatbot.router) api_router.include_router(collection_job.router) api_router.include_router(collections.router) api_router.include_router(config.router) diff --git a/backend/app/api/routes/chatbot.py b/backend/app/api/routes/chatbot.py new file mode 100644 index 000000000..454f4853b --- /dev/null +++ b/backend/app/api/routes/chatbot.py @@ -0,0 +1,64 @@ +import logging + +from fastapi import APIRouter, Depends, HTTPException + +from app.api.deps import AuthContextDep, SessionDep +from app.api.permissions import Permission, require_permission +from app.models import ChatbotMessage, ChatbotTurnRequest, ChatbotTurnResponse +from app.services.chatbot.engine import ( + ChatbotInputError, + ChatbotProviderError, + run_chatbot_turn, +) +from app.services.chatbot.config import resolve_chatbot_model_settings +from app.utils import APIResponse, load_description + +logger = logging.getLogger(__name__) + +router = APIRouter(prefix="/chatbot", tags=["Chatbot"]) + + +# Synchronous by design (real-time request/response turn), not a Celery job. +@router.post( + "/message", + description=load_description("chatbot/message.md"), + response_model=APIResponse[ChatbotTurnResponse], + dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))], +) +async def send_chatbot_message( + request: ChatbotTurnRequest, + session: SessionDep, + auth_context: AuthContextDep, +) -> APIResponse[ChatbotTurnResponse]: + history: list[dict[str, str]] = [] + for entry in request.history: + history.append(entry.model_dump(mode="json")) + + try: + model_settings = resolve_chatbot_model_settings( + session=session, + project_id=auth_context.project_.id, + config_id=request.config_id, + config_version=request.config_version, + max_tokens=request.max_tokens, + history_token_limit=request.history_token_limit, + ) + transcript = await run_chatbot_turn( + system_prompt=request.system_prompt, + history=history, + user_message=request.message, + model_settings=model_settings, + ) + except ChatbotInputError as e: + raise HTTPException(status_code=422, detail=str(e)) + except ChatbotProviderError as e: + logger.warning( + f"[send_chatbot_message] Chatbot turn failed upstream | " + f"project_id: {auth_context.project_.id}" + ) + raise HTTPException(status_code=502, detail=str(e)) + + messages: list[ChatbotMessage] = [] + for entry in transcript: + messages.append(ChatbotMessage.model_validate(entry)) + return APIResponse.success_response(ChatbotTurnResponse(messages=messages)) diff --git a/backend/app/crud/config/version.py b/backend/app/crud/config/version.py index 313a4e27c..85be0ed64 100644 --- a/backend/app/crud/config/version.py +++ b/backend/app/crud/config/version.py @@ -213,6 +213,11 @@ def read_one(self, version_number: int) -> ConfigVersion | None: ) return self.session.exec(statement).one_or_none() + def read_latest(self) -> ConfigVersion | None: + """Read the highest non-deleted version of the configuration.""" + self._config_exists_or_raise(self.config_id) + return self._get_latest_version() + def read_all(self, skip: int = 0, limit: int = 100) -> list[ConfigVersionItems]: """ Read all versions for a specific configuration with pagination. diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py index 8a1559573..e13fe062a 100644 --- a/backend/app/models/__init__.py +++ b/backend/app/models/__init__.py @@ -35,6 +35,12 @@ BatchJobType, BatchJobUpdate, ) +from .chatbot import ( + ChatbotMessage, + ChatbotMessageRoleEnum, + ChatbotTurnRequest, + ChatbotTurnResponse, +) from .collection import ( Collection, CollectionIDPublic, diff --git a/backend/app/models/chatbot.py b/backend/app/models/chatbot.py new file mode 100644 index 000000000..c06a6540b --- /dev/null +++ b/backend/app/models/chatbot.py @@ -0,0 +1,56 @@ +from enum import StrEnum +from uuid import UUID + +from sqlmodel import Field, SQLModel + + +class ChatbotMessageRoleEnum(StrEnum): + SYSTEM = "system" + USER = "user" + ASSISTANT = "assistant" + + +class ChatbotMessage(SQLModel): + role: ChatbotMessageRoleEnum + content: str + + +class ChatbotTurnRequest(SQLModel): + config_id: UUID = Field( + description="Saved Kaapi config (Anthropic text completion) that supplies the model and reasoning settings.", + ) + config_version: int | None = Field( + default=None, + ge=1, + description="Version of `config_id` to use; omit to use its latest version.", + ) + max_tokens: int | None = Field( + default=None, + gt=0, + description="Cap on output tokens per model call; omit for the server default.", + ) + history_token_limit: int | None = Field( + default=None, + gt=0, + description="Token size of the history above which older turns are summarized; omit for the server default.", + ) + # Required every call in v0: there is no server-side storage of the flow prompt yet. + system_prompt: str = Field( + min_length=1, + description="Admin-authored flow prompt (goal, fields to collect, rules).", + ) + history: list[ChatbotMessage] = Field( + default_factory=list, + description="Every message before this turn, as returned by the previous call; empty on the first call.", + ) + message: str | None = Field( + default=None, + min_length=1, + description="The new user message; omit only to get the opening greeting on the first call.", + ) + + +class ChatbotTurnResponse(SQLModel): + messages: list[ChatbotMessage] = Field( + description="Full updated transcript (system prompt + every turn, including the new reply); resend it as `history` next call.", + ) diff --git a/backend/app/services/chatbot/config.py b/backend/app/services/chatbot/config.py new file mode 100644 index 000000000..9f3d4fc0f --- /dev/null +++ b/backend/app/services/chatbot/config.py @@ -0,0 +1,141 @@ +import logging +from typing import get_args +from uuid import UUID + +from fastapi import HTTPException +from pydantic import ValidationError +from sqlmodel import Session + +from app.crud.config import ConfigVersionCrud +from app.models import ConfigVersion +from app.models.llm.constants import Provider +from app.models.llm.request import ConfigBlob, KaapiTextCompletionConfig +from app.services.chatbot.engine import ChatbotInputError +from app.services.chatbot.utils import ( + DEFAULT_HISTORY_TOKEN_LIMIT, + DEFAULT_MAX_OUTPUT_TOKENS, + AnthropicEffort, + ChatbotModelSettings, + default_thinking, +) + +logger = logging.getLogger(__name__) + +_ANTHROPIC_EFFORT_LEVELS: tuple[AnthropicEffort, ...] = get_args(AnthropicEffort) + + +def _get_config_version( + *, session: Session, project_id: int, config_id: UUID, config_version: int | None +) -> ConfigVersion: + # The crud constructor and `exists_or_raise` already 404 when the config or + # version is outside this project, so ownership is enforced here. + version_crud = ConfigVersionCrud( + session=session, config_id=config_id, project_id=project_id + ) + if config_version is not None: + return version_crud.exists_or_raise(version_number=config_version) + + latest = version_crud.read_latest() + if latest is None: + logger.warning( + f"[_get_config_version] Config has no versions | " + f"config_id: {config_id}, project_id: {project_id}" + ) + raise HTTPException( + status_code=404, + detail=f"No version found for config '{config_id}'", + ) + return latest + + +def _to_anthropic_effort(effort: str | None) -> AnthropicEffort | None: + if effort is None: + return None + for level in _ANTHROPIC_EFFORT_LEVELS: + if level == effort: + return level + # Kaapi's "none"/"minimal" have no Anthropic equivalent; dropping them + # silently would let the provider default (often higher) take over. + raise ChatbotInputError( + f"[KAAPI] Config param 'effort' value '{effort}' is not an Anthropic effort " + f"level ({', '.join(_ANTHROPIC_EFFORT_LEVELS)}); update the config." + ) + + +def resolve_chatbot_model_settings( + *, + session: Session, + project_id: int, + config_id: UUID, + config_version: int | None, + max_tokens: int | None, + history_token_limit: int | None, +) -> ChatbotModelSettings: + """Turn a saved config (+ request overrides) into chat-model settings. + + Raises HTTPException(404) when the config/version isn't in the project and + ChatbotInputError when the config isn't a usable Anthropic text config. + """ + version_row = _get_config_version( + session=session, + project_id=project_id, + config_id=config_id, + config_version=config_version, + ) + + try: + blob = ConfigBlob.model_validate(version_row.config_blob) + except ValidationError as e: + logger.warning( + f"[resolve_chatbot_model_settings] [KAAPI] Stored config blob is invalid | " + f"config_id: {config_id}, version: {version_row.version}", + exc_info=True, + ) + raise ChatbotInputError( + f"[KAAPI] Stored configuration blob is invalid: {e}" + ) from e + + completion = blob.completion + if ( + not isinstance(completion, KaapiTextCompletionConfig) + or completion.provider != Provider.ANTHROPIC + ): + logger.warning( + f"[resolve_chatbot_model_settings] [KAAPI] Unsupported config for chatbot | " + f"config_id: {config_id}, version: {version_row.version}, " + f"provider: {completion.provider}, type: {completion.type}" + ) + raise ChatbotInputError( + "[KAAPI] Chatbot only supports configs with completion provider " + f"'{Provider.ANTHROPIC.value}' and type 'text'; got provider " + f"'{completion.provider}', type '{completion.type}'." + ) + + params = completion.params + if not params.model: + logger.warning( + f"[resolve_chatbot_model_settings] [KAAPI] Config has no model | " + f"config_id: {config_id}, version: {version_row.version}" + ) + raise ChatbotInputError( + "[KAAPI] Config is missing completion.params.model; set a model on the config." + ) + + thinking = params.thinking if params.thinking is not None else default_thinking() + model_settings = ChatbotModelSettings( + model=params.model, + max_tokens=max_tokens if max_tokens is not None else DEFAULT_MAX_OUTPUT_TOKENS, + reasoning_effort=_to_anthropic_effort(params.effort), + thinking=thinking, + history_token_limit=( + history_token_limit + if history_token_limit is not None + else DEFAULT_HISTORY_TOKEN_LIMIT + ), + ) + logger.info( + f"[resolve_chatbot_model_settings] Resolved chatbot model settings | " + f"config_id: {config_id}, version: {version_row.version}, " + f"model: {model_settings.model}, effort: {model_settings.reasoning_effort}" + ) + return model_settings diff --git a/backend/app/services/chatbot/engine.py b/backend/app/services/chatbot/engine.py new file mode 100644 index 000000000..380bf3eb0 --- /dev/null +++ b/backend/app/services/chatbot/engine.py @@ -0,0 +1,260 @@ +"""v0 chatbot: a single LangGraph node wrapping a LangChain chat model. + +Unlike a field-by-field collector, this mirrors OCS's own approach: the +admin supplies the full prompt (goal + fields + rules, written as free text -- +the same shape as OCS's `prompt` field) and the model manages the conversation +itself, reading the full message history every turn. There is no field-by-field +state machine in code here. + +No tools in v0 -- OCS's node also lets the admin attach tools (e.g. +set-session-state); that is deliberately left out here and is the natural next +step once this shape is proven. + +No checkpointer: like OCS, there is no LangGraph-level pause/resume. The caller +keeps the running message list itself and passes the full history into +`graph.invoke(...)` on every turn -- a fresh, complete run each time. +""" + +import asyncio +import logging +from typing import Annotated, TypedDict + +import anthropic +from langchain_core.language_models.chat_models import BaseChatModel +from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, SystemMessage +from langgraph.graph import END, START, StateGraph +from langgraph.graph.message import add_messages +from langgraph.graph.state import CompiledStateGraph + +from app.models.chatbot import ChatbotMessageRoleEnum +from app.services.chatbot.utils import ( + FLOW_KEEP_RECENT_MESSAGES, + ChatbotModelSettings, + get_chat_model, +) + +logger = logging.getLogger(__name__) + +CHATBOT_NODE = "chatbot_node" + +_SUMMARY_NOTE_PREFIX = "[Earlier conversation summary] " +_SUMMARIZE_INSTRUCTION = ( + "Summarize the conversation so far in 2-3 sentences. Keep every fact the " + "user has already given -- this note replaces the original messages." +) + +# Anthropic rejects a request whose first non-system turn isn't a user turn, so +# the opening greeting (and every later call, whose history starts with that +# greeting) needs a synthetic user turn in front. It's stripped from the +# returned transcript by this fixed id, so callers never see it. +_KICKOFF_MESSAGE_ID = "chatbot-kickoff" +_KICKOFF_MESSAGE_CONTENT = "Begin the conversation." + +ChatbotMessageDict = dict[str, str] + + +class ChatbotState(TypedDict): + # `add_messages` is LangGraph's prebuilt reducer for LangChain message + # lists: it appends new messages and merges by `.id` instead of naively + # concatenating, which is what lets callers keep re-sending the running + # history without duplicating turns. + messages: Annotated[list[BaseMessage], add_messages] + + +class ChatbotInputError(ValueError): + """The turn request can't produce a valid model call (caller's fault).""" + + +class ChatbotProviderError(Exception): + """The chat-model provider failed or was unreachable.""" + + +def _summarize_if_needed( + chat_model: BaseChatModel, + messages: list[BaseMessage], + *, + history_token_limit: int, +) -> list[BaseMessage]: + """Trim the view sent to the model once history crosses the token budget. + + Simplification: this only shrinks what THIS call sends to Anthropic: the + caller's own running history keeps growing untouched, so a long-enough + conversation re-summarizes from scratch each turn rather than compacting + state permanently. OCS's real history middleware persists the compression + point instead -- worth doing if this gets reused past v0. + """ + if len(messages) <= FLOW_KEEP_RECENT_MESSAGES + 1: # +1 for the system message + return messages + if chat_model.get_num_tokens_from_messages(messages) <= history_token_limit: + return messages + + system_message, *rest = messages + to_summarize, recent = ( + rest[:-FLOW_KEEP_RECENT_MESSAGES], + rest[-FLOW_KEEP_RECENT_MESSAGES:], + ) + # Anthropic requires the first non-system turn to be a user turn. `rest` + # always ends on this turn's unanswered human message, so it has odd + # length; cutting an even-sized window from its tail always lands one + # message short, opening on an assistant turn instead. Shift the boundary + # back until `recent` starts on a human message. + while recent and to_summarize and not isinstance(recent[0], HumanMessage): + recent.insert(0, to_summarize.pop()) + if not to_summarize: + return messages + + summary = chat_model.invoke( + [SystemMessage(content=_SUMMARIZE_INSTRUCTION), *to_summarize] + ) + logger.info( + f"[_summarize_if_needed] Compressed history | " + f"from: {len(to_summarize)} messages, to: 1 summary note" + ) + summary_note = SystemMessage(content=f"{_SUMMARY_NOTE_PREFIX}{summary.text}") + return [system_message, summary_note, *recent] + + +def build_chatbot_graph( + chat_model: BaseChatModel, *, history_token_limit: int +) -> CompiledStateGraph: + """One node, no branching -- `chat_model` is fixed for the graph's lifetime.""" + + def chatbot_node(state: ChatbotState) -> dict[str, list[BaseMessage]]: + messages = _summarize_if_needed( + chat_model, state["messages"], history_token_limit=history_token_limit + ) + response = chat_model.invoke(messages) + return {"messages": [response]} + + graph = StateGraph(ChatbotState) + graph.add_node(CHATBOT_NODE, chatbot_node) + graph.add_edge(START, CHATBOT_NODE) + graph.add_edge(CHATBOT_NODE, END) + return graph.compile() + + +def _to_langchain_messages( + *, system_prompt: str, history: list[ChatbotMessageDict], user_message: str | None +) -> list[BaseMessage]: + # `system_prompt` is the single source of the system turn; any system entry + # echoed back in `history` (the previous response includes it) is dropped + # so it isn't sent twice. + conversation: list[BaseMessage] = [] + for entry in history: + role = entry["role"] + content = entry["content"] + if role == ChatbotMessageRoleEnum.USER: + conversation.append(HumanMessage(content=content)) + elif role == ChatbotMessageRoleEnum.ASSISTANT: + conversation.append(AIMessage(content=content)) + elif role != ChatbotMessageRoleEnum.SYSTEM: + raise ChatbotInputError(f"Unsupported message role: {role}") + + if user_message is not None: + conversation.append(HumanMessage(content=user_message)) + + if not conversation or not isinstance(conversation[0], HumanMessage): + kickoff = HumanMessage(content=_KICKOFF_MESSAGE_CONTENT, id=_KICKOFF_MESSAGE_ID) + conversation.insert(0, kickoff) + + return [SystemMessage(content=system_prompt), *conversation] + + +def _to_message_dicts( + *, system_prompt: str, messages: list[BaseMessage] +) -> list[ChatbotMessageDict]: + transcript: list[ChatbotMessageDict] = [ + {"role": ChatbotMessageRoleEnum.SYSTEM.value, "content": system_prompt} + ] + for message in messages: + if message.id == _KICKOFF_MESSAGE_ID: + continue + if isinstance(message, HumanMessage): + role = ChatbotMessageRoleEnum.USER + elif isinstance(message, AIMessage): + role = ChatbotMessageRoleEnum.ASSISTANT + else: + continue + # `.text` drops thinking/tool blocks; the wire shape carries text only. + transcript.append({"role": role.value, "content": message.text}) + return transcript + + +async def run_chatbot_turn( + *, + system_prompt: str, + history: list[ChatbotMessageDict], + user_message: str | None, + model_settings: ChatbotModelSettings, +) -> list[ChatbotMessageDict]: + """Run one stateless turn and return the full updated transcript. + + `user_message` may be None only on the very first call (empty `history`), + which yields the bot's opening greeting. + """ + if user_message is None and history: + logger.warning( + f"[run_chatbot_turn] [KAAPI] Missing user message on a non-initial turn | " + f"history_count: {len(history)}" + ) + raise ChatbotInputError( + "[KAAPI] `message` is required once `history` is non-empty; omit it only " + "on the first call to get the opening greeting." + ) + + messages = _to_langchain_messages( + system_prompt=system_prompt, history=history, user_message=user_message + ) + logger.info( + f"[run_chatbot_turn] Starting turn | history_count: {len(history)}, " + f"has_user_message: {user_message is not None}, model: {model_settings.model}" + ) + + graph = build_chatbot_graph( + get_chat_model(model_settings), + history_token_limit=model_settings.history_token_limit, + ) + try: + # ChatAnthropic.invoke is sync; keep it off the event loop. + result = await asyncio.to_thread(graph.invoke, {"messages": messages}) + except anthropic.APITimeoutError as e: + logger.error( + f"[run_chatbot_turn] [KAAPI] Request to Anthropic timed out (code: APITimeoutError) | " + f"provider=anthropic, model={model_settings.model}", + exc_info=True, + ) + raise ChatbotProviderError( + "[KAAPI] Request timed out — retry smaller. If persistent, contact Kaapi. " + "(code: APITimeoutError)" + ) from e + except anthropic.APIConnectionError as e: + logger.error( + f"[run_chatbot_turn] [KAAPI] Could not reach Anthropic (code: APIConnectionError) | " + f"provider=anthropic, model={model_settings.model}", + exc_info=True, + ) + raise ChatbotProviderError( + "[KAAPI] Network/DNS issue reaching provider — check connectivity. " + "If persistent, contact Kaapi. (code: APIConnectionError)" + ) from e + except anthropic.APIStatusError as e: + # 5xx is provider-side (alert-worthy); 4xx is caller's fault (noise if alerted) + log = logger.error if e.status_code >= 500 else logger.warning + log( + f"[run_chatbot_turn] [ANTHROPIC] {e.message} (code: {e.status_code}) | " + f"provider=anthropic, model={model_settings.model}, request_id={e.request_id}", + exc_info=True, + ) + raise ChatbotProviderError( + f"[ANTHROPIC] Chat model call failed: {e.message} (code: {e.status_code}, " + f"request_id: {e.request_id})" + ) from e + + transcript = _to_message_dicts( + system_prompt=system_prompt, messages=result["messages"] + ) + logger.info( + f"[run_chatbot_turn] Turn completed | transcript_count: {len(transcript)}, " + f"reply_length: {len(transcript[-1]['content'])}" + ) + return transcript diff --git a/backend/app/services/chatbot/utils.py b/backend/app/services/chatbot/utils.py new file mode 100644 index 000000000..2ec9571a1 --- /dev/null +++ b/backend/app/services/chatbot/utils.py @@ -0,0 +1,59 @@ +"""Model/runtime settings for the v0 LangGraph + LangChain chatbot node. + +Like OCS's `LLMResponseWithPrompt` node, the model and reasoning settings come +from per-request input -- here a saved Kaapi config (see +`services/chatbot/config.py`) plus optional token overrides on the request. +Only Anthropic is wired up, since the node's chat model is `ChatAnthropic`. +""" + +from dataclasses import dataclass, field +from typing import Any, Literal + +from langchain_anthropic import ChatAnthropic + +from app.core.config import settings + +AnthropicEffort = Literal["low", "medium", "high", "xhigh", "max"] + +DEFAULT_MAX_OUTPUT_TOKENS = 1024 +DEFAULT_THINKING: dict[str, Any] = {"type": "adaptive"} + +# OCS's `history_mode=summarize`, simplified: once the running history crosses +# this many tokens, everything except the system prompt and the most recent +# turns is summarized into one note before the next model call. +DEFAULT_HISTORY_TOKEN_LIMIT = 4000 +FLOW_KEEP_RECENT_MESSAGES = 6 + + +def default_thinking() -> dict[str, Any]: + # Fresh copy so one request can't mutate the module-level default. + return dict(DEFAULT_THINKING) + + +@dataclass(frozen=True) +class ChatbotModelSettings: + model: str + max_tokens: int = DEFAULT_MAX_OUTPUT_TOKENS + # None lets the provider pick its own default effort. + reasoning_effort: AnthropicEffort | None = None + thinking: dict[str, Any] = field(default_factory=default_thinking) + history_token_limit: int = DEFAULT_HISTORY_TOKEN_LIMIT + + +def get_chat_model(model_settings: ChatbotModelSettings) -> ChatAnthropic: + """LangChain's provider abstraction, so swapping providers later is a + config change here, not a rewrite of the node. + """ + if not settings.ANTHROPIC_API_KEY: + raise RuntimeError( + "[get_chat_model] ANTHROPIC_API_KEY is not set; export it or set it in .env" + ) + kwargs: dict[str, Any] = { + "model": model_settings.model, + "max_tokens": model_settings.max_tokens, + "thinking": model_settings.thinking, + "anthropic_api_key": settings.ANTHROPIC_API_KEY, + } + if model_settings.reasoning_effort is not None: + kwargs["reasoning_effort"] = model_settings.reasoning_effort + return ChatAnthropic(**kwargs) diff --git a/backend/pyproject.toml b/backend/pyproject.toml index caf23c32b..cbf5f98f6 100644 --- a/backend/pyproject.toml +++ b/backend/pyproject.toml @@ -60,6 +60,7 @@ dependencies = [ "filetype>=1.2.0", "langgraph>=1.2.10", "langgraph-checkpoint-postgres>=3.1.1", + "langchain-anthropic>=1.7.5", ] [tool.uv] diff --git a/backend/uv.lock b/backend/uv.lock index 675933ab5..779da0eac 100644 --- a/backend/uv.lock +++ b/backend/uv.lock @@ -216,21 +216,20 @@ wheels = [ [[package]] name = "anthropic" -version = "0.104.1" +version = "1.12.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "anyio" }, - { name = "distro" }, { name = "docstring-parser" }, - { name = "httpx" }, + { name = "httpx2" }, { name = "jiter" }, { name = "pydantic" }, { name = "sniffio" }, { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/22/c7/7a655b948916f777354648ce979f68b94d5b8dbdb5f61fed1f37fad9378c/anthropic-0.104.1.tar.gz", hash = "sha256:17362b6c45f527afcc9b0fdf62011ffd359726ab2ebcb1978ea0cc41bd8d8d40", size = 850081, upload-time = "2026-05-22T15:36:57.432Z" } +sdist = { url = "https://files.pythonhosted.org/packages/bd/cc/0da23e94020c62c0077c17648252f32d575b187710faaf3b85145e8e555d/anthropic-1.12.1.tar.gz", hash = "sha256:10f720ab6ddf40ef12e0e5743412c3a6dfac1109c244e633c9a2dbd36778ad30", size = 1555908, upload-time = "2026-10-08T03:42:00.588Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/b8/12/d9ab42790494d7c428391a46cd28492395566a6a8ccb138d681978594455/anthropic-0.104.1-py3-none-any.whl", hash = "sha256:35c8cb456f5a4405aafe1f10f03f6fcc54fa51fa8ec01d655cc4b437d120e9b7", size = 832996, upload-time = "2026-05-22T15:36:59.519Z" }, + { url = "https://files.pythonhosted.org/packages/8b/35/1ccdc3e950dd869b66de15035e15d9614607fcef9664dec403fe639f01df/anthropic-1.12.1-py3-none-any.whl", hash = "sha256:1c1469bb3f4118291756816b7850cc839f17b2be5cdc99c8fde3890a61a49ca2", size = 1919752, upload-time = "2026-10-08T03:41:58.596Z" }, ] [[package]] @@ -271,6 +270,7 @@ dependencies = [ { name = "indic-nlp-library" }, { name = "jinja2" }, { name = "jiwer" }, + { name = "langchain-anthropic" }, { name = "langfuse" }, { name = "langgraph" }, { name = "langgraph-checkpoint-postgres" }, @@ -343,6 +343,7 @@ requires-dist = [ { name = "indic-nlp-library", specifier = ">=0.92" }, { name = "jinja2", specifier = ">=3.1.4,<4.0.0" }, { name = "jiwer", specifier = ">=3.1.0" }, + { name = "langchain-anthropic", specifier = ">=1.7.5" }, { name = "langfuse", specifier = "==4.7.1" }, { name = "langgraph", specifier = ">=1.2.10" }, { name = "langgraph-checkpoint-postgres", specifier = ">=3.1.1" }, @@ -1584,6 +1585,19 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/7e/f5/f66802a942d491edb555dd61e3a9961140fd64c90bce1eafd741609d334d/httpcore-1.0.9-py3-none-any.whl", hash = "sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55", size = 78784, upload-time = "2025-04-24T22:06:20.566Z" }, ] +[[package]] +name = "httpcore2" +version = "2.13.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "h11", marker = "sys_platform != 'emscripten'" }, + { name = "truststore", marker = "sys_platform != 'emscripten'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/cb/f3/1db7aa2bc2524062192bb0e0323969492d1883152a232fe36eea65f4e35c/httpcore2-2.13.1.tar.gz", hash = "sha256:e0aa977abe17e69a3b820a24542a6fa88702676d83880b8d194dcd18408e5103", size = 68071, upload-time = "2026-09-23T07:47:22.372Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/09/ba/a4568248771ce81957bfb7cc600264a40fbcda092391ee1c415c50be4bea/httpcore2-2.13.1-py3-none-any.whl", hash = "sha256:e1e05d4f25f7d7d496bfb96748f6f4b67657b03da069b3a68c36069f3db73d0a", size = 83423, upload-time = "2026-09-23T07:47:19.365Z" }, +] + [[package]] name = "httptools" version = "0.7.1" @@ -1628,6 +1642,32 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/2a/39/e50c7c3a983047577ee07d2a9e53faf5a69493943ec3f6a384bdc792deb2/httpx-0.28.1-py3-none-any.whl", hash = "sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad", size = 73517, upload-time = "2024-12-06T15:37:21.509Z" }, ] +[[package]] +name = "httpx2" +version = "2.13.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "anyio", marker = "sys_platform != 'emscripten'" }, + { name = "httpcore2", marker = "sys_platform != 'emscripten'" }, + { name = "httpx2-jsfetch", marker = "sys_platform == 'emscripten'" }, + { name = "idna" }, + { name = "truststore", marker = "sys_platform != 'emscripten'" }, + { name = "typing-extensions", marker = "python_full_version < '3.13'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/d5/44/474bef2a0e9d90f1715d32cb98b0738695ca17ba324095fb2497ed7fbd59/httpx2-2.13.1.tar.gz", hash = "sha256:e48744a19e3af5ee48313d0ce5fe941d5422fae5705ea922a4aabf94d7800dfa", size = 100405, upload-time = "2026-09-23T07:47:23.052Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d8/9c/6fe8931fd9f381042a9e4c7d5a7b4cbf7016b252bec0c99a49fce42c3326/httpx2-2.13.1-py3-none-any.whl", hash = "sha256:6dff50fabc270ee5fd25d845d0b078ed20564579744d6d962850975996d2f9a4", size = 95597, upload-time = "2026-09-23T07:47:20.995Z" }, +] + +[[package]] +name = "httpx2-jsfetch" +version = "1.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/cd/c4/0e5636363151a2a1795e0a77617168b9ca438e1748ec05fc9b5687f93d64/httpx2_jsfetch-1.0.tar.gz", hash = "sha256:70a0e3eabfef7cce5ad9c629f7d01ca05e418f586646f4ddf14782e4c1454c60", size = 6872, upload-time = "2026-08-07T00:13:07.492Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9b/43/832f631d32e4f1211caa2ba368317739fe71f0b8530e4c9d15dc454bac2a/httpx2_jsfetch-1.0-py3-none-any.whl", hash = "sha256:cb916b707601e69a07721aabc8f3f6659be3a6893bc1ff5c6f9e02241df2da32", size = 6382, upload-time = "2026-08-07T00:13:06.567Z" }, +] + [[package]] name = "huggingface-hub" version = "1.7.1" @@ -1668,11 +1708,11 @@ wheels = [ [[package]] name = "idna" -version = "3.15" +version = "3.20" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/82/77/7b3966d0b9d1d31a36ddf1746926a11dface89a83409bf1483f0237aa758/idna-3.15.tar.gz", hash = "sha256:ca962446ea538f7092a95e057da437618e886f4d349216d2b1e294abfdb65fdc", size = 199245, upload-time = "2026-05-12T22:45:57.011Z" } +sdist = { url = "https://files.pythonhosted.org/packages/f5/08/8eea9d4b8302028f3abb2c0813953f7aec26d33b7a8960ed760e65ff29fa/idna-3.20.tar.gz", hash = "sha256:a7db850025b95ded1eae8a46181a1a6c56c92c96f0e2b005d9ff8dc0210cab44", size = 216463, upload-time = "2026-09-17T14:11:04.752Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/d2/23/408243171aa9aaba178d3e2559159c24c1171a641aa83b67bdd3394ead8e/idna-3.15-py3-none-any.whl", hash = "sha256:048adeaf8c2d788c40fee287673ccaa74c24ffd8dcf09ffa555a2fbb59f10ac8", size = 72340, upload-time = "2026-05-12T22:45:55.733Z" }, + { url = "https://files.pythonhosted.org/packages/58/a2/bb081bab032533a855d44de1d56f8e8426114ff1ba5d1f07a438a0a654f8/idna-3.20-py3-none-any.whl", hash = "sha256:ab7ae7122974553370f0bdb919e1a960b2cd1bc1ef0276416d896db81c14582c", size = 69583, upload-time = "2026-09-17T14:11:03.168Z" }, ] [[package]] @@ -1904,11 +1944,26 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/fb/0f/834427d8c03ff1d7e867d3db3d176470c64871753252b21b4f4897d1fa45/kombu-5.6.2-py3-none-any.whl", hash = "sha256:efcfc559da324d41d61ca311b0c64965ea35b4c55cc04ee36e55386145dace93", size = 214219, upload-time = "2025-12-29T20:30:05.74Z" }, ] +[[package]] +name = "langchain-anthropic" +version = "1.7.5" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "anthropic" }, + { name = "langchain-core" }, + { name = "pydantic" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/91/e6/45ead93ef6d9f244b502a6a32bf9a185b3da1cc7fa8003896a102dadac09/langchain_anthropic-1.7.5.tar.gz", hash = "sha256:6016f38e5c4bf12c16ecfa76abf133a978f459f4d2887b8e28435ae1ff00beb3", size = 764625, upload-time = "2026-09-29T15:22:07.106Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/eb/a8/c507f2c1859b584843983e98bc71e0066c16a77e6c181921c928e0fdbcf7/langchain_anthropic-1.7.5-py3-none-any.whl", hash = "sha256:b21ef0e0c2d6175235a5b7eef4f5f89057df92d42dbfab66920a05605ef7173a", size = 65239, upload-time = "2026-09-29T15:22:05.832Z" }, +] + [[package]] name = "langchain-core" -version = "1.5.3" +version = "1.6.9" source = { registry = "https://pypi.org/simple" } dependencies = [ + { name = "httpx" }, { name = "jsonpatch" }, { name = "langchain-protocol" }, { name = "langsmith" }, @@ -1919,9 +1974,9 @@ dependencies = [ { name = "typing-extensions" }, { name = "uuid-utils" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/65/3e/63af6b9d76d9be907c7c524d6ec18a2efed7e0e2d123fea0230d78dbd73f/langchain_core-1.5.3.tar.gz", hash = "sha256:a56457ac444fef41e9404443c187f0ecea708d36e816ea4ba9573c027f7d1a2d", size = 972461, upload-time = "2026-07-30T14:55:55.833Z" } +sdist = { url = "https://files.pythonhosted.org/packages/a7/d3/e9611e44e62ab8175127e137587c62dc2ed00e2615aebd89dfdb77f5fba0/langchain_core-1.6.9.tar.gz", hash = "sha256:34394228603e6f0bd24ce4e773b58b7d160e1b8cf489ecb350cf41f5366f5e92", size = 1010051, upload-time = "2026-10-08T20:11:19.881Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/36/e6/c7c39efe0bc7e1b7c3d8f54f85846e04c901913c3d3e99068b218558c6f1/langchain_core-1.5.3-py3-none-any.whl", hash = "sha256:48b56fa580277209594dd7baf837f5b9a2a3651613f34ff9fb1728b429df015f", size = 561687, upload-time = "2026-07-30T14:55:54.419Z" }, + { url = "https://files.pythonhosted.org/packages/49/41/fdcdd869c052874b17e2325c986cf8c2fc6bbefa3b9d5404dd64dfffb12a/langchain_core-1.6.9-py3-none-any.whl", hash = "sha256:2bacea12270fd4cfdeeefdc5977e7e8b3c30814c509534d1ef43f4e5b7d3f657", size = 572951, upload-time = "2026-10-08T20:11:18.189Z" }, ] [[package]] @@ -4622,6 +4677,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/16/e1/3079a9ff9b8e11b846c6ac5c8b5bfb7ff225eee721825310c91b3b50304f/tqdm-4.67.3-py3-none-any.whl", hash = "sha256:ee1e4c0e59148062281c49d80b25b67771a127c85fc9676d3be5f243206826bf", size = 78374, upload-time = "2026-02-03T17:35:50.982Z" }, ] +[[package]] +name = "truststore" +version = "0.10.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/53/a3/1585216310e344e8102c22482f6060c7a6ea0322b63e026372e6dcefcfd6/truststore-0.10.4.tar.gz", hash = "sha256:9d91bd436463ad5e4ee4aba766628dd6cd7010cf3e2461756b3303710eebc301", size = 26169, upload-time = "2025-08-12T18:49:02.73Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/19/97/56608b2249fe206a67cd573bc93cd9896e1efb9e98bce9c163bcdc704b88/truststore-0.10.4-py3-none-any.whl", hash = "sha256:adaeaecf1cbb5f4de3b1959b42d41f6fab57b2b1666adb59e89cb0b53361d981", size = 18660, upload-time = "2025-08-12T18:49:01.46Z" }, +] + [[package]] name = "typer" version = "0.23.1" diff --git a/docs/wiki/INDEX.md b/docs/wiki/INDEX.md index 9bc299d34..f6fb3646b 100644 --- a/docs/wiki/INDEX.md +++ b/docs/wiki/INDEX.md @@ -21,6 +21,7 @@ Deep design narrative lives in `docs/architecture/*.md`; open those only for des - [modules/knowledge-base.md](modules/knowledge-base.md) — documents, collections, transforms, vector-store providers. Deep dive: `docs/architecture/kaapi-knowledge-base-ARCHITECTURE.md` - [modules/responses.md](modules/responses.md) — OpenAI Responses API integration, conversations, threads, assistants. No deep-dive doc yet. - [modules/assessment.md](modules/assessment.md) — assessments and assessment runs. No deep-dive doc yet. +- [modules/chatbot.md](modules/chatbot.md) — v0 stateless prompt-driven chatbot (`POST /chatbot/message`, LangGraph + Anthropic, model driven by a saved config). No deep-dive doc yet. - [modules/tenancy.md](modules/tenancy.md) — users, orgs, projects, API keys, onboarding, login. - [modules/platform.md](modules/platform.md) — analytics, notifications, feature flags, languages, credentials, model config, cron. diff --git a/docs/wiki/domain-map.md b/docs/wiki/domain-map.md index 073d65540..643985f70 100644 --- a/docs/wiki/domain-map.md +++ b/docs/wiki/domain-map.md @@ -23,8 +23,8 @@ APIKey → Organization, Project, User # programmatic access | User | user.py | — | UserProject, APIKey, Notification | | APIKey | api_key.py | Organization, Project, User | auth dependency on every API route (logical) | | Credential | credentials.py | Organization, Project | provider clients: OpenAI/Gemini/Anthropic calls (logical); bucket providers (`google-gcp` → GCS signing, logical) | -| Config | config/config.py | Project | ConfigVersion; LLM call path; Assessment; EvaluationRun (`config_id`) | -| ConfigVersion | config/version.py | Config | resolved by `LLMCallConfig` saved references (logical) | +| Config | config/config.py | Project | ConfigVersion; LLM call path; Chatbot turn (`POST /chatbot/message`, logical); Assessment; EvaluationRun (`config_id`) | +| ConfigVersion | config/version.py | Config | resolved by `LLMCallConfig` saved references and chatbot `config_id`/`config_version` (logical) | | LlmCall | llm/request.py | Job, LlmChain, Org, Project | Langfuse traces (logical); analytics | | LlmChain | llm/request.py | Org, Project | LlmCall | | Job | job.py | Project | LlmCall; Assessment (RESPONSE method); Celery job execution (logical); evaluation prompt improvement (`JobType.PROMPT_IMPROVEMENT`, logical) | diff --git a/docs/wiki/modules/chatbot.md b/docs/wiki/modules/chatbot.md new file mode 100644 index 000000000..261046755 --- /dev/null +++ b/docs/wiki/modules/chatbot.md @@ -0,0 +1,23 @@ +# Module: Chatbot + +v0 prompt-driven chatbot: one LangGraph node over a LangChain chat model (Anthropic). Stateless — the caller resends `system_prompt` + full `history` every turn. The model and reasoning settings come from a saved Kaapi config (`config_id` + optional `config_version`, latest if omitted); only Anthropic text completion configs are supported. No deep-dive doc yet. + +All paths relative to `backend/app/`. + +## Routes +- `api/routes/chatbot.py` — `POST /chatbot/message` (one synchronous turn; requires project scope) + +## Tables (SQLModel) +None of its own. Request/response shapes only: `models/chatbot.py` (`ChatbotMessage`, `ChatbotMessageRoleEnum`, `ChatbotTurnRequest`, `ChatbotTurnResponse`). Reads `config` / `config_version` (see the config module) to resolve the model. + +## Services / CRUD +- `services/chatbot/config.py` — `resolve_chatbot_model_settings` (saved config + request overrides → `ChatbotModelSettings`; 404 via `ConfigVersionCrud`, 422 for non-Anthropic/non-text/no-model configs) +- `services/chatbot/engine.py` — `run_chatbot_turn` (dict <-> LangChain message conversion, error mapping), `build_chatbot_graph`, history summarization +- `services/chatbot/utils.py` — `ChatbotModelSettings`, defaults (`DEFAULT_MAX_OUTPUT_TOKENS`, `DEFAULT_HISTORY_TOKEN_LIMIT`, `FLOW_KEEP_RECENT_MESSAGES`), `get_chat_model` +- `crud/config/version.py` — `ConfigVersionCrud.read_latest` (used when `config_version` is omitted) + +## Async +- None; synchronous request/response, not Celery. + +## External +- Anthropic via `langchain-anthropic` (`ANTHROPIC_API_KEY` setting). diff --git a/docs/wiki/modules/platform.md b/docs/wiki/modules/platform.md index 19d4923b4..eab9471f1 100644 --- a/docs/wiki/modules/platform.md +++ b/docs/wiki/modules/platform.md @@ -40,3 +40,16 @@ single source of truth: Adding a provider = add the enum member, the model, and its `PROVIDER_CONFIGS` entry; nothing else needs to know. + +## Model config catalog + +`global.model_config` rows are seeded by migrations (052 OpenAI, 063 STT/TTS, +066 `google-aistudio` copies, 086 Anthropic `claude-sonnet-4-6` / +`claude-opus-5-5`). `GET /models/providers` lists only providers that have an +active row, so a provider with no rows is invisible to the config UI. + +A `config.effort` key marks a reasoning model (`is_reasoning_model`): the OpenAI +mapper routes `effort` into `reasoning`, and config-version updates strip +`temperature`. A missing (provider, model) row only logs a warning at config +save — validation is liberal — but the model then gets no effort handling and +no cost estimate (`pricing` NULL also means no estimate). From 5a65515ba7b67f8a54b84ed01681bcc5c07c0812 Mon Sep 17 00:00:00 2001 From: Ayush8923 <80516839+Ayush8923@users.noreply.github.com> Date: Sat, 17 Oct 2026 19:34:36 +0530 Subject: [PATCH 2/8] fix: update the global model config migration --- .../087_seed_anthropic_text_model_configs.py | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 backend/app/alembic/versions/087_seed_anthropic_text_model_configs.py diff --git a/backend/app/alembic/versions/087_seed_anthropic_text_model_configs.py b/backend/app/alembic/versions/087_seed_anthropic_text_model_configs.py new file mode 100644 index 000000000..86e0aff00 --- /dev/null +++ b/backend/app/alembic/versions/087_seed_anthropic_text_model_configs.py @@ -0,0 +1,60 @@ +"""seed anthropic text model_config rows + +Revision ID: 087 +Revises: 086 +Create Date: 2026-10-09 00:00:00.000000 + +`anthropic` has been a valid provider since 066 but had no model_config rows, +so it never showed up in /models/providers and config-version updates could +not tell its models are reasoning models. The `effort` key in `config` is what +`is_reasoning_model` keys on — it makes `_strip_unsupported_params` drop +`temperature`, which the Messages API rejects at non-default values. + +`effort.default` is "high" because that is what the Messages API applies when +the param is omitted. Sonnet 4.6 does not expose the "xhigh" level. + +claude-opus-5-5 pricing is left NULL until list prices are confirmed; cost +estimation returns None for NULL pricing rather than a wrong number. + +Downgrade deletes the two rows by key, so a row that already existed before +upgrade (ON CONFLICT DO NOTHING skipped it) is removed as well. +""" + +from alembic import op + +revision = "087" +down_revision = "086" +branch_labels = None +depends_on = None + + +def upgrade(): + op.execute( + """ + INSERT INTO global.model_config + (provider, model_name, completion_type, config, input_modalities, + output_modalities, pricing, is_active, inserted_at, updated_at) + VALUES + ('anthropic', 'claude-sonnet-4-6', '{text}', + '{"effort": {"type": "enum", "default": "high", "options": ["low", "medium", "high", "max"], "description": "How long the model spends reasoning. Higher = better but slower."}}', + '{TEXT,IMAGE,FILES}', '{TEXT}', + '{"response": {"input_token_cost": 3, "output_token_cost": 15}, "batch": {"input_token_cost": 1.5, "output_token_cost": 7.5}}', + true, NOW(), NOW()), + ('anthropic', 'claude-opus-5-5', '{text}', + '{"effort": {"type": "enum", "default": "high", "options": ["low", "medium", "high", "xhigh", "max"], "description": "How long the model spends reasoning. Higher = better but slower."}}', + '{TEXT,IMAGE,FILES}', '{TEXT}', + NULL, + true, NOW(), NOW()) + ON CONFLICT (provider, model_name) DO NOTHING + """ + ) + + +def downgrade(): + op.execute( + """ + DELETE FROM global.model_config + WHERE provider = 'anthropic' + AND model_name IN ('claude-sonnet-4-6', 'claude-opus-5-5') + """ + ) From 6f2ae62aa29695eae8f4371de7f3f0a6a0da0c8a Mon Sep 17 00:00:00 2001 From: Ayush8923 <80516839+Ayush8923@users.noreply.github.com> Date: Tue, 20 Oct 2026 08:54:22 +0530 Subject: [PATCH 3/8] fix: cleanups --- backend/app/api/routes/chatbot.py | 9 --------- 1 file changed, 9 deletions(-) diff --git a/backend/app/api/routes/chatbot.py b/backend/app/api/routes/chatbot.py index 454f4853b..fb10f91b7 100644 --- a/backend/app/api/routes/chatbot.py +++ b/backend/app/api/routes/chatbot.py @@ -1,5 +1,3 @@ -import logging - from fastapi import APIRouter, Depends, HTTPException from app.api.deps import AuthContextDep, SessionDep @@ -13,12 +11,9 @@ from app.services.chatbot.config import resolve_chatbot_model_settings from app.utils import APIResponse, load_description -logger = logging.getLogger(__name__) - router = APIRouter(prefix="/chatbot", tags=["Chatbot"]) -# Synchronous by design (real-time request/response turn), not a Celery job. @router.post( "/message", description=load_description("chatbot/message.md"), @@ -52,10 +47,6 @@ async def send_chatbot_message( except ChatbotInputError as e: raise HTTPException(status_code=422, detail=str(e)) except ChatbotProviderError as e: - logger.warning( - f"[send_chatbot_message] Chatbot turn failed upstream | " - f"project_id: {auth_context.project_.id}" - ) raise HTTPException(status_code=502, detail=str(e)) messages: list[ChatbotMessage] = [] From 1b4f9ee19675b120f4c6b41c4605cd1e2218dbfb Mon Sep 17 00:00:00 2001 From: Ayush8923 <80516839+Ayush8923@users.noreply.github.com> Date: Tue, 20 Oct 2026 12:02:37 +0530 Subject: [PATCH 4/8] fix: remove the unwanted comments --- .../086_seed_anthropic_text_model_configs.py | 15 --------------- .../087_seed_anthropic_text_model_configs.py | 15 --------------- 2 files changed, 30 deletions(-) diff --git a/backend/app/alembic/versions/086_seed_anthropic_text_model_configs.py b/backend/app/alembic/versions/086_seed_anthropic_text_model_configs.py index 915218568..0fbcf76d3 100644 --- a/backend/app/alembic/versions/086_seed_anthropic_text_model_configs.py +++ b/backend/app/alembic/versions/086_seed_anthropic_text_model_configs.py @@ -3,21 +3,6 @@ Revision ID: 086 Revises: 085 Create Date: 2026-10-09 00:00:00.000000 - -`anthropic` has been a valid provider since 066 but had no model_config rows, -so it never showed up in /models/providers and config-version updates could -not tell its models are reasoning models. The `effort` key in `config` is what -`is_reasoning_model` keys on — it makes `_strip_unsupported_params` drop -`temperature`, which the Messages API rejects at non-default values. - -`effort.default` is "high" because that is what the Messages API applies when -the param is omitted. Sonnet 4.6 does not expose the "xhigh" level. - -claude-opus-5-5 pricing is left NULL until list prices are confirmed; cost -estimation returns None for NULL pricing rather than a wrong number. - -Downgrade deletes the two rows by key, so a row that already existed before -upgrade (ON CONFLICT DO NOTHING skipped it) is removed as well. """ from alembic import op diff --git a/backend/app/alembic/versions/087_seed_anthropic_text_model_configs.py b/backend/app/alembic/versions/087_seed_anthropic_text_model_configs.py index 86e0aff00..1d864a12f 100644 --- a/backend/app/alembic/versions/087_seed_anthropic_text_model_configs.py +++ b/backend/app/alembic/versions/087_seed_anthropic_text_model_configs.py @@ -3,21 +3,6 @@ Revision ID: 087 Revises: 086 Create Date: 2026-10-09 00:00:00.000000 - -`anthropic` has been a valid provider since 066 but had no model_config rows, -so it never showed up in /models/providers and config-version updates could -not tell its models are reasoning models. The `effort` key in `config` is what -`is_reasoning_model` keys on — it makes `_strip_unsupported_params` drop -`temperature`, which the Messages API rejects at non-default values. - -`effort.default` is "high" because that is what the Messages API applies when -the param is omitted. Sonnet 4.6 does not expose the "xhigh" level. - -claude-opus-5-5 pricing is left NULL until list prices are confirmed; cost -estimation returns None for NULL pricing rather than a wrong number. - -Downgrade deletes the two rows by key, so a row that already existed before -upgrade (ON CONFLICT DO NOTHING skipped it) is removed as well. """ from alembic import op From 671eed47cf0c230294f5ab291e5106467aa732e6 Mon Sep 17 00:00:00 2001 From: Ayush8923 <80516839+Ayush8923@users.noreply.github.com> Date: Tue, 20 Oct 2026 12:11:00 +0530 Subject: [PATCH 5/8] feat: added the implementation to save the chat history --- .../versions/088_add_chatbot_session.py | 162 ++++++++++++++ .../app/api/docs/chatbot/create_session.md | 5 + .../api/docs/chatbot/send_session_message.md | 5 + backend/app/api/routes/chatbot.py | 133 +++++++++++- backend/app/celery/tasks/job_execution.py | 30 ++- backend/app/celery/utils.py | 24 +++ backend/app/crud/chatbot.py | 95 ++++++++ backend/app/models/__init__.py | 7 + backend/app/models/chatbot.py | 186 +++++++++++++++- backend/app/services/chatbot/session.py | 202 ++++++++++++++++++ 10 files changed, 844 insertions(+), 5 deletions(-) create mode 100644 backend/app/alembic/versions/088_add_chatbot_session.py create mode 100644 backend/app/api/docs/chatbot/create_session.md create mode 100644 backend/app/api/docs/chatbot/send_session_message.md create mode 100644 backend/app/crud/chatbot.py create mode 100644 backend/app/services/chatbot/session.py diff --git a/backend/app/alembic/versions/088_add_chatbot_session.py b/backend/app/alembic/versions/088_add_chatbot_session.py new file mode 100644 index 000000000..9e5ec9f51 --- /dev/null +++ b/backend/app/alembic/versions/088_add_chatbot_session.py @@ -0,0 +1,162 @@ +"""add chatbot session and message tables + +Revision ID: 088 +Revises: 087 +Create Date: 2026-10-20 00:00:00.000000 +""" + +import sqlalchemy as sa +import sqlmodel.sql.sqltypes +from alembic import op +from sqlalchemy.dialects import postgresql + +revision = "088" +down_revision = "087" +branch_labels = None +depends_on = None + + +def upgrade(): + op.create_table( + "chatbot_session", + sa.Column( + "id", + sa.Uuid(), + nullable=False, + comment="Session identifier returned to the caller", + ), + sa.Column( + "contact_ref", + sqlmodel.sql.sqltypes.AutoString(length=500), + nullable=False, + comment="Caller-side identifier of the end user (e.g. a contact id); opaque to Kaapi", + ), + sa.Column( + "config_id", + sa.Uuid(), + nullable=False, + comment="Saved Anthropic text config that supplies the chat model", + ), + sa.Column( + "config_version", + sa.Integer(), + nullable=True, + comment="Pinned config version; NULL resolves to the latest version on every turn", + ), + sa.Column( + "system_prompt", + sqlmodel.sql.sqltypes.AutoString(), + nullable=False, + comment="Admin-authored flow prompt captured at session creation", + ), + sa.Column( + "status", + sa.Enum( + "in_progress", + "completed", + "abandoned", + name="chatbotsessionstatusenum", + ), + nullable=False, + comment="Conversation lifecycle: in_progress, completed, or abandoned", + ), + sa.Column( + "collected_fields", + postgresql.JSON(astext_type=sa.Text()), + nullable=False, + comment="Flat map of field name -> value gathered from the user so far", + ), + sa.Column( + "organization_id", + sa.Integer(), + nullable=False, + comment="Reference to the organization", + ), + sa.Column( + "project_id", + sa.Integer(), + nullable=False, + comment="Reference to the project", + ), + sa.Column( + "inserted_at", + sa.DateTime(), + nullable=False, + comment="Timestamp when the session was created", + ), + sa.Column( + "updated_at", + sa.DateTime(), + nullable=False, + comment="Timestamp when the session was last updated", + ), + sa.ForeignKeyConstraint(["config_id"], ["config.id"], ondelete="RESTRICT"), + sa.ForeignKeyConstraint( + ["organization_id"], ["organization.id"], ondelete="CASCADE" + ), + sa.ForeignKeyConstraint(["project_id"], ["project.id"], ondelete="CASCADE"), + sa.PrimaryKeyConstraint("id"), + ) + op.create_index( + op.f("ix_chatbot_session_config_id"), + "chatbot_session", + ["config_id"], + unique=False, + ) + op.create_index( + op.f("ix_chatbot_session_organization_id"), + "chatbot_session", + ["organization_id"], + unique=False, + ) + op.create_index( + op.f("ix_chatbot_session_project_id"), + "chatbot_session", + ["project_id"], + unique=False, + ) + + op.create_table( + "chatbot_session_message", + sa.Column("id", sa.Uuid(), nullable=False, comment="Unique identifier"), + sa.Column( + "session_id", + sa.Uuid(), + nullable=False, + comment="Reference to the owning chatbot session", + ), + sa.Column( + "role", + sa.Enum("system", "user", "assistant", name="chatbotmessageroleenum"), + nullable=False, + comment="Speaker: user or assistant (system is reserved; the prompt lives on the session)", + ), + sa.Column( + "content", + sqlmodel.sql.sqltypes.AutoString(), + nullable=False, + comment="Message text", + ), + sa.Column( + "inserted_at", + sa.DateTime(), + nullable=False, + comment="Timestamp when the message was stored; defines transcript order", + ), + sa.ForeignKeyConstraint( + ["session_id"], ["chatbot_session.id"], ondelete="CASCADE" + ), + sa.PrimaryKeyConstraint("id"), + ) + op.create_index( + op.f("ix_chatbot_session_message_session_id"), + "chatbot_session_message", + ["session_id"], + unique=False, + ) + + +def downgrade(): + raise NotImplementedError( + "not reversible: dropping chatbot_session tables discards stored conversations" + ) diff --git a/backend/app/api/docs/chatbot/create_session.md b/backend/app/api/docs/chatbot/create_session.md new file mode 100644 index 000000000..543966e2d --- /dev/null +++ b/backend/app/api/docs/chatbot/create_session.md @@ -0,0 +1,5 @@ +Start a server-side chatbot conversation and return its `session_id`. + +The `system_prompt` and the `config_id` / `config_version` pin are stored on the session, so later turns only send the new user message. `config_id` must be a config in the caller's project whose completion is `provider: "anthropic"`, `type: "text"` with `params.model` set; when `config_version` is omitted, each turn uses the config's latest version at that time. + +`contact_ref` is the caller's own identifier for the end user and is stored as-is. Returns 404 if the config or version isn't found in the project and 422 if it isn't a usable Anthropic text config. diff --git a/backend/app/api/docs/chatbot/send_session_message.md b/backend/app/api/docs/chatbot/send_session_message.md new file mode 100644 index 000000000..237e0fa97 --- /dev/null +++ b/backend/app/api/docs/chatbot/send_session_message.md @@ -0,0 +1,5 @@ +Queue one turn of a chatbot session; the bot reply is delivered asynchronously to `webhook_url`. + +The user `message` is stored immediately and the response is `202` with `status: "queued"`. Once the turn completes, Kaapi POSTs `{"success": true, "data": {"session_id", "reply", "status", "collected_fields"}}` to `webhook_url` (HMAC-signed when the project has a webhook secret). On a model or config failure it POSTs `{"success": false, "error": "...", "data": {"session_id"}}` instead. + +On the first call of a session, omit `message` to get the bot's opening greeting; after that `message` is required. `webhook_url` must be a public HTTPS URL. Returns 404 if the session isn't in the caller's project and 422 for an invalid `webhook_url` or a missing `message` on a started session. diff --git a/backend/app/api/routes/chatbot.py b/backend/app/api/routes/chatbot.py index fb10f91b7..e43eed46e 100644 --- a/backend/app/api/routes/chatbot.py +++ b/backend/app/api/routes/chatbot.py @@ -1,15 +1,40 @@ -from fastapi import APIRouter, Depends, HTTPException +import logging +from typing import Annotated +from uuid import UUID + +from asgi_correlation_id import correlation_id +from fastapi import APIRouter, Depends, HTTPException, Path from app.api.deps import AuthContextDep, SessionDep from app.api.permissions import Permission, require_permission -from app.models import ChatbotMessage, ChatbotTurnRequest, ChatbotTurnResponse +from app.celery.utils import start_chatbot_session_message +from app.crud.chatbot import ( + create_chatbot_session, + create_chatbot_session_message, + get_chatbot_session, + list_chatbot_session_messages, +) +from app.models import ( + ChatbotMessage, + ChatbotMessageRoleEnum, + ChatbotTurnRequest, + ChatbotTurnResponse, + CreateChatbotSessionRequest, + CreateChatbotSessionResponse, + SendChatbotSessionMessageRequest, + SendChatbotSessionMessageResponse, +) from app.services.chatbot.engine import ( ChatbotInputError, ChatbotProviderError, run_chatbot_turn, ) from app.services.chatbot.config import resolve_chatbot_model_settings -from app.utils import APIResponse, load_description +from app.utils import APIResponse, load_description, validate_callback_url + +logger = logging.getLogger(__name__) + +DEFAULT_TRACE_ID = "N/A" router = APIRouter(prefix="/chatbot", tags=["Chatbot"]) @@ -53,3 +78,105 @@ async def send_chatbot_message( for entry in transcript: messages.append(ChatbotMessage.model_validate(entry)) return APIResponse.success_response(ChatbotTurnResponse(messages=messages)) + + +@router.post( + "/sessions", + status_code=201, + description=load_description("chatbot/create_session.md"), + response_model=APIResponse[CreateChatbotSessionResponse], + dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))], +) +def start_chatbot_session( + request: CreateChatbotSessionRequest, + session: SessionDep, + auth_context: AuthContextDep, +) -> APIResponse[CreateChatbotSessionResponse]: + project_id = auth_context.project_.id + # Fail fast on an unusable config instead of on the first queued turn. + try: + resolve_chatbot_model_settings( + session=session, + project_id=project_id, + config_id=request.config_id, + config_version=request.config_version, + max_tokens=None, + history_token_limit=None, + ) + except ChatbotInputError as e: + raise HTTPException(status_code=422, detail=str(e)) + + chatbot_session = create_chatbot_session( + session, + organization_id=auth_context.organization_.id, + project_id=project_id, + contact_ref=request.contact_ref, + config_id=request.config_id, + config_version=request.config_version, + system_prompt=request.system_prompt, + ) + return APIResponse.success_response( + CreateChatbotSessionResponse(session_id=chatbot_session.id) + ) + + +@router.post( + "/sessions/{session_id}/message", + status_code=202, + description=load_description("chatbot/send_session_message.md"), + response_model=APIResponse[SendChatbotSessionMessageResponse], + dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))], +) +def send_chatbot_session_message( + session_id: Annotated[UUID, Path(description="Chatbot session identifier")], + request: SendChatbotSessionMessageRequest, + session: SessionDep, + auth_context: AuthContextDep, +) -> APIResponse[SendChatbotSessionMessageResponse]: + organization_id = auth_context.organization_.id + project_id = auth_context.project_.id + + # validate_callback_url signals rejection with ValueError, which has no + # global handler and would otherwise surface as a 500. + try: + validate_callback_url(request.webhook_url) + except ValueError as e: + raise HTTPException(status_code=422, detail=f"Invalid webhook_url: {e}") + + chatbot_session = get_chatbot_session( + session, + session_id=session_id, + organization_id=organization_id, + project_id=project_id, + ) + if chatbot_session is None: + raise HTTPException(status_code=404, detail="Chatbot session not found") + + if request.message is None: + # Only the opening greeting may omit `message`; reject here rather than + # letting the worker fail and report it via webhook. + if list_chatbot_session_messages(session, session_id=session_id): + raise HTTPException( + status_code=422, + detail="`message` is required once the session has started; omit it only on the first call.", + ) + else: + create_chatbot_session_message( + session, + session_id=session_id, + role=ChatbotMessageRoleEnum.USER, + content=request.message, + ) + + task_id = start_chatbot_session_message( + session_id=str(session_id), + organization_id=organization_id, + project_id=project_id, + webhook_url=request.webhook_url, + trace_id=correlation_id.get() or DEFAULT_TRACE_ID, + ) + logger.info( + f"[send_chatbot_session_message] Turn queued | session_id: {session_id}, " + f"project_id: {project_id}, task_id: {task_id}, has_message: {request.message is not None}" + ) + return APIResponse.success_response(SendChatbotSessionMessageResponse()) diff --git a/backend/app/celery/tasks/job_execution.py b/backend/app/celery/tasks/job_execution.py index 483384364..e22aa3088 100644 --- a/backend/app/celery/tasks/job_execution.py +++ b/backend/app/celery/tasks/job_execution.py @@ -3,7 +3,8 @@ All tasks share one queue (`default`, declared with `x-max-priority=10`) and are ordered by the per-task `priority`: - 9 LLM call + LLM chain (run_llm_job, run_llm_chain_job, run_response_job) + 9 LLM call + LLM chain (run_llm_job, run_llm_chain_job, run_response_job, + run_chatbot_session_message) 6 Fast evaluation (run_evaluation_fast_chunk, run_evaluation_fast_aggregate, run_prompt_improvement, run_evaluation_iteration_graph_step) 2 Everything else (doctransform, collections, STT/TTS evaluation, assessment) @@ -15,6 +16,7 @@ import logging from collections.abc import Callable from typing import TYPE_CHECKING, TypeVar +from uuid import UUID from asgi_correlation_id import correlation_id from celery import Task, current_task @@ -561,3 +563,29 @@ def send_eval_completion_callback( ) return execute_eval_completion_callback(evaluation_id=evaluation_id) + + +@celery_app.task(bind=True, queue="default", priority=9) +@gevent_timeout(settings.CELERY_TASK_SOFT_TIME_LIMIT, "run_chatbot_session_message") +def run_chatbot_session_message( + self: Task, + session_id: str, + organization_id: int, + project_id: int, + webhook_url: str, + trace_id: str, +) -> None: + """Idempotency: the service skips the turn if the transcript already ends + on an assistant reply, so a redelivery doesn't re-bill or double-reply.""" + from app.services.chatbot.session import process_chatbot_session_message + + _set_trace(trace_id) + return _run_with_otel_parent( + self, + lambda: process_chatbot_session_message( + session_id=UUID(session_id), + organization_id=organization_id, + project_id=project_id, + webhook_url=webhook_url, + ), + ) diff --git a/backend/app/celery/utils.py b/backend/app/celery/utils.py index 3bd205d22..88285c0bb 100644 --- a/backend/app/celery/utils.py +++ b/backend/app/celery/utils.py @@ -337,6 +337,30 @@ def start_evaluation_iteration_round( return task_id +def start_chatbot_session_message( + session_id: str, + organization_id: int, + project_id: int, + webhook_url: str, + trace_id: str = "N/A", +) -> str: + from app.celery.tasks.job_execution import run_chatbot_session_message + + task_id = _enqueue_with_trace_context( + run_chatbot_session_message, + session_id=session_id, + organization_id=organization_id, + project_id=project_id, + webhook_url=webhook_url, + trace_id=trace_id, + ) + logger.info( + f"[start_chatbot_session_message] Enqueued chatbot turn | " + f"session_id: {session_id}, task_id: {task_id}" + ) + return task_id + + def get_task_status(task_id: str) -> Dict[str, Any]: result = AsyncResult(task_id) return { diff --git a/backend/app/crud/chatbot.py b/backend/app/crud/chatbot.py new file mode 100644 index 000000000..058277153 --- /dev/null +++ b/backend/app/crud/chatbot.py @@ -0,0 +1,95 @@ +import logging +from uuid import UUID + +from sqlmodel import Session, col, select + +from app.core.util import now +from app.models import ( + ChatbotMessageRoleEnum, + ChatbotSession, + ChatbotSessionMessage, +) + +logger = logging.getLogger(__name__) + + +def create_chatbot_session( + session: Session, + *, + organization_id: int, + project_id: int, + contact_ref: str, + config_id: UUID, + config_version: int | None, + system_prompt: str, +) -> ChatbotSession: + timestamp = now() + chatbot_session = ChatbotSession( + organization_id=organization_id, + project_id=project_id, + contact_ref=contact_ref, + config_id=config_id, + config_version=config_version, + system_prompt=system_prompt, + inserted_at=timestamp, + updated_at=timestamp, + ) + session.add(chatbot_session) + session.commit() + session.refresh(chatbot_session) + logger.info( + f"[create_chatbot_session] Chatbot session created | " + f"session_id: {chatbot_session.id}, project_id: {project_id}, config_id: {config_id}" + ) + return chatbot_session + + +def get_chatbot_session( + session: Session, + *, + session_id: UUID, + organization_id: int, + project_id: int, +) -> ChatbotSession | None: + statement = select(ChatbotSession).where( + ChatbotSession.id == session_id, + ChatbotSession.organization_id == organization_id, + ChatbotSession.project_id == project_id, + ) + return session.exec(statement).first() + + +def create_chatbot_session_message( + session: Session, + *, + session_id: UUID, + role: ChatbotMessageRoleEnum, + content: str, +) -> ChatbotSessionMessage: + message = ChatbotSessionMessage( + session_id=session_id, + role=role, + content=content, + inserted_at=now(), + ) + session.add(message) + session.commit() + session.refresh(message) + logger.info( + f"[create_chatbot_session_message] Chatbot message stored | " + f"session_id: {session_id}, role: {role.value}, message_id: {message.id}" + ) + return message + + +def list_chatbot_session_messages( + session: Session, *, session_id: UUID +) -> list[ChatbotSessionMessage]: + # Unpaginated on purpose: the engine needs the whole transcript each turn + # and summarizes long histories itself. + statement = ( + select(ChatbotSessionMessage) + .where(ChatbotSessionMessage.session_id == session_id) + .order_by(col(ChatbotSessionMessage.inserted_at).asc()) + ) + return list(session.exec(statement).all()) diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py index e13fe062a..8ac2eb18f 100644 --- a/backend/app/models/__init__.py +++ b/backend/app/models/__init__.py @@ -38,8 +38,15 @@ from .chatbot import ( ChatbotMessage, ChatbotMessageRoleEnum, + ChatbotSession, + ChatbotSessionMessage, + ChatbotSessionStatusEnum, ChatbotTurnRequest, ChatbotTurnResponse, + CreateChatbotSessionRequest, + CreateChatbotSessionResponse, + SendChatbotSessionMessageRequest, + SendChatbotSessionMessageResponse, ) from .collection import ( Collection, diff --git a/backend/app/models/chatbot.py b/backend/app/models/chatbot.py index c06a6540b..4b2412451 100644 --- a/backend/app/models/chatbot.py +++ b/backend/app/models/chatbot.py @@ -1,8 +1,14 @@ +from datetime import datetime from enum import StrEnum -from uuid import UUID +from typing import Any +from uuid import UUID, uuid4 +from sqlalchemy import JSON, Column +from sqlalchemy.dialects.postgresql import ENUM from sqlmodel import Field, SQLModel +from app.core.util import now + class ChatbotMessageRoleEnum(StrEnum): SYSTEM = "system" @@ -54,3 +60,181 @@ class ChatbotTurnResponse(SQLModel): messages: list[ChatbotMessage] = Field( description="Full updated transcript (system prompt + every turn, including the new reply); resend it as `history` next call.", ) + + +class ChatbotSessionStatusEnum(StrEnum): + IN_PROGRESS = "in_progress" + COMPLETED = "completed" + ABANDONED = "abandoned" + + +# values_callable stores the lowercase member values the migration created the +# Postgres enum types with; SQLAlchemy's default would store member names. +_SESSION_STATUS_PG_ENUM = ENUM( + ChatbotSessionStatusEnum, + name="chatbotsessionstatusenum", + values_callable=lambda enum_cls: [member.value for member in enum_cls], + create_type=False, +) +_MESSAGE_ROLE_PG_ENUM = ENUM( + ChatbotMessageRoleEnum, + name="chatbotmessageroleenum", + values_callable=lambda enum_cls: [member.value for member in enum_cls], + create_type=False, +) + +CONTACT_REF_MAX_LENGTH = 500 + + +class ChatbotSession(SQLModel, table=True): + __tablename__ = "chatbot_session" + + id: UUID = Field( + default_factory=uuid4, + primary_key=True, + sa_column_kwargs={"comment": "Session identifier returned to the caller"}, + ) + contact_ref: str = Field( + max_length=CONTACT_REF_MAX_LENGTH, + sa_column_kwargs={ + "comment": "Caller-side identifier of the end user (e.g. a Glific contact id); opaque to Kaapi" + }, + ) + config_id: UUID = Field( + foreign_key="config.id", + nullable=False, + index=True, + ondelete="RESTRICT", + sa_column_kwargs={ + "comment": "Saved Anthropic text config that supplies the chat model" + }, + ) + config_version: int | None = Field( + default=None, + ge=1, + sa_column_kwargs={ + "comment": "Pinned config version; NULL resolves to the latest version on every turn" + }, + ) + system_prompt: str = Field( + sa_column_kwargs={ + "comment": "Admin-authored flow prompt captured at session creation" + }, + ) + status: ChatbotSessionStatusEnum = Field( + default=ChatbotSessionStatusEnum.IN_PROGRESS, + sa_column=Column( + _SESSION_STATUS_PG_ENUM, + nullable=False, + comment="Conversation lifecycle: in_progress, completed, or abandoned", + ), + ) + collected_fields: dict[str, Any] = Field( + default_factory=dict, + sa_column=Column( + JSON, + nullable=False, + comment="Flat map of field name -> value gathered from the user so far", + ), + ) + organization_id: int = Field( + foreign_key="organization.id", + nullable=False, + index=True, + ondelete="CASCADE", + sa_column_kwargs={"comment": "Reference to the organization"}, + ) + project_id: int = Field( + foreign_key="project.id", + nullable=False, + index=True, + ondelete="CASCADE", + sa_column_kwargs={"comment": "Reference to the project"}, + ) + inserted_at: datetime = Field( + default_factory=now, + nullable=False, + sa_column_kwargs={"comment": "Timestamp when the session was created"}, + ) + updated_at: datetime = Field( + default_factory=now, + nullable=False, + sa_column_kwargs={ + "comment": "Timestamp when the session was last updated", + "onupdate": now, + }, + ) + + +class ChatbotSessionMessage(SQLModel, table=True): + __tablename__ = "chatbot_session_message" + + id: UUID = Field( + default_factory=uuid4, + primary_key=True, + sa_column_kwargs={"comment": "Unique identifier"}, + ) + session_id: UUID = Field( + foreign_key="chatbot_session.id", + nullable=False, + index=True, + ondelete="CASCADE", + sa_column_kwargs={"comment": "Reference to the owning chatbot session"}, + ) + role: ChatbotMessageRoleEnum = Field( + sa_column=Column( + _MESSAGE_ROLE_PG_ENUM, + nullable=False, + comment="Speaker: user or assistant (system is reserved; the prompt lives on the session)", + ), + ) + content: str = Field( + sa_column_kwargs={"comment": "Message text"}, + ) + inserted_at: datetime = Field( + default_factory=now, + nullable=False, + sa_column_kwargs={ + "comment": "Timestamp when the message was stored; defines transcript order" + }, + ) + + +class CreateChatbotSessionRequest(SQLModel): + config_id: UUID = Field( + description="Saved Kaapi config (Anthropic text completion) that supplies the model and reasoning settings.", + ) + config_version: int | None = Field( + default=None, + ge=1, + description="Version of `config_id` to pin; omit to use the latest version on every turn.", + ) + contact_ref: str = Field( + min_length=1, + max_length=CONTACT_REF_MAX_LENGTH, + description="Caller-side identifier of the end user this conversation is with.", + ) + system_prompt: str = Field( + min_length=1, + description="Admin-authored flow prompt (goal, fields to collect, rules); stored for the session's lifetime.", + ) + + +class CreateChatbotSessionResponse(SQLModel): + session_id: UUID + + +class SendChatbotSessionMessageRequest(SQLModel): + message: str | None = Field( + default=None, + min_length=1, + description="The new user message; omit only on the first call to get the opening greeting.", + ) + webhook_url: str = Field( + min_length=1, + description="HTTPS URL the bot reply is POSTed to once the turn completes.", + ) + + +class SendChatbotSessionMessageResponse(SQLModel): + status: str = "queued" diff --git a/backend/app/services/chatbot/session.py b/backend/app/services/chatbot/session.py new file mode 100644 index 000000000..a2791b46c --- /dev/null +++ b/backend/app/services/chatbot/session.py @@ -0,0 +1,202 @@ +import asyncio +import logging +from typing import Any +from uuid import UUID + +from fastapi import HTTPException +from sqlmodel import Session + +from app.core.db import engine +from app.crud.chatbot import ( + create_chatbot_session_message, + get_chatbot_session, + list_chatbot_session_messages, +) +from app.models import ChatbotMessageRoleEnum, ChatbotSessionMessage +from app.services.chatbot.config import resolve_chatbot_model_settings +from app.services.chatbot.engine import ( + ChatbotInputError, + ChatbotMessageDict, + ChatbotProviderError, + run_chatbot_turn, +) +from app.services.chatbot.utils import ChatbotModelSettings +from app.utils import get_webhook_secret, send_callback + +logger = logging.getLogger(__name__) + + +def _split_pending_turn( + stored_messages: list[ChatbotSessionMessage], +) -> tuple[list[ChatbotMessageDict], str | None]: + """Split the stored transcript into (prior history, pending user message). + + The route persists the user's message before enqueueing, so it is the last + stored row; the engine wants it separately from the history before it. + """ + history: list[ChatbotMessageDict] = [] + for stored in stored_messages: + # The system prompt lives on the session row and is passed separately. + if stored.role == ChatbotMessageRoleEnum.SYSTEM: + continue + history.append({"role": stored.role.value, "content": stored.content}) + + if not history: + return history, None + if history[-1]["role"] != ChatbotMessageRoleEnum.USER: + # No pending user turn; the engine rejects this with ChatbotInputError. + return history, None + pending = history.pop() + return history, pending["content"] + + +def _extract_reply(transcript: list[ChatbotMessageDict]) -> str: + for entry in reversed(transcript): + if entry["role"] == ChatbotMessageRoleEnum.ASSISTANT: + return entry["content"] + raise ChatbotInputError("[KAAPI] Chat model returned no assistant reply.") + + +def _send_failure_webhook( + *, + session_id: UUID, + webhook_url: str, + webhook_secret: str | None, + error: str, +) -> None: + payload: dict[str, Any] = { + "success": False, + "error": error, + "data": {"session_id": str(session_id)}, + } + delivered = send_callback(webhook_url, payload, webhook_secret) + logger.info( + f"[_send_failure_webhook] Failure webhook dispatched | " + f"session_id: {session_id}, delivered: {delivered}" + ) + + +def process_chatbot_session_message( + *, + session_id: UUID, + organization_id: int, + project_id: int, + webhook_url: str, +) -> None: + """Run the pending chatbot turn for a session and POST the reply to `webhook_url`. + + Idempotent under Celery redelivery: if the transcript already ends on an + assistant turn, the pending turn was answered and nothing is re-run. + """ + webhook_secret = get_webhook_secret(project_id, organization_id) + + # The DB session is closed before the LLM call so a slow provider doesn't + # pin a pooled connection for the whole turn. + with Session(engine) as session: + chatbot_session = get_chatbot_session( + session, + session_id=session_id, + organization_id=organization_id, + project_id=project_id, + ) + if chatbot_session is None: + logger.error( + f"[process_chatbot_session_message] Chatbot session not found | " + f"session_id: {session_id}, project_id: {project_id}" + ) + return + + stored_messages = list_chatbot_session_messages(session, session_id=session_id) + if ( + stored_messages + and stored_messages[-1].role == ChatbotMessageRoleEnum.ASSISTANT + ): + logger.warning( + f"[process_chatbot_session_message] Turn already answered, skipping | " + f"session_id: {session_id}" + ) + return + + system_prompt = chatbot_session.system_prompt + session_status = chatbot_session.status.value + collected_fields = dict(chatbot_session.collected_fields) + + try: + model_settings: ChatbotModelSettings = resolve_chatbot_model_settings( + session=session, + project_id=project_id, + config_id=chatbot_session.config_id, + config_version=chatbot_session.config_version, + max_tokens=None, + history_token_limit=None, + ) + except HTTPException as e: + # The config was resolvable at session creation; it has since been + # deleted or lost its version, and the caller only hears via webhook. + logger.warning( + f"[process_chatbot_session_message] Config no longer resolvable | " + f"session_id: {session_id}, detail: {e.detail}" + ) + _send_failure_webhook( + session_id=session_id, + webhook_url=webhook_url, + webhook_secret=webhook_secret, + error=str(e.detail), + ) + return + except ChatbotInputError as e: + _send_failure_webhook( + session_id=session_id, + webhook_url=webhook_url, + webhook_secret=webhook_secret, + error=str(e), + ) + return + + history, user_message = _split_pending_turn(stored_messages) + logger.info( + f"[process_chatbot_session_message] Running turn | session_id: {session_id}, " + f"history_count: {len(history)}, has_user_message: {user_message is not None}" + ) + + try: + transcript = asyncio.run( + run_chatbot_turn( + system_prompt=system_prompt, + history=history, + user_message=user_message, + model_settings=model_settings, + ) + ) + reply = _extract_reply(transcript) + except (ChatbotInputError, ChatbotProviderError) as e: + _send_failure_webhook( + session_id=session_id, + webhook_url=webhook_url, + webhook_secret=webhook_secret, + error=str(e), + ) + return + + with Session(engine) as session: + create_chatbot_session_message( + session, + session_id=session_id, + role=ChatbotMessageRoleEnum.ASSISTANT, + content=reply, + ) + + payload: dict[str, Any] = { + "success": True, + "data": { + "session_id": str(session_id), + "reply": reply, + "status": session_status, + "collected_fields": collected_fields, + }, + } + delivered = send_callback(webhook_url, payload, webhook_secret) + logger.info( + f"[process_chatbot_session_message] Turn completed | session_id: {session_id}, " + f"reply_length: {len(reply)}, webhook_delivered: {delivered}" + ) From ef7202ca3994b0e8dc41cede67c24cdfcb5ec7b8 Mon Sep 17 00:00:00 2001 From: Ayush8923 <80516839+Ayush8923@users.noreply.github.com> Date: Tue, 20 Oct 2026 12:25:29 +0530 Subject: [PATCH 6/8] chore: cleanups --- backend/app/api/routes/chatbot/__init__.py | 6 ++ .../routes/{chatbot.py => chatbot/message.py} | 9 +- backend/app/models/chatbot.py | 1 - backend/app/services/chatbot/config.py | 31 +----- backend/app/services/chatbot/engine.py | 97 +------------------ backend/app/services/chatbot/exceptions.py | 6 ++ backend/app/services/chatbot/types.py | 10 ++ backend/app/services/chatbot/utils.py | 13 +-- 8 files changed, 31 insertions(+), 142 deletions(-) create mode 100644 backend/app/api/routes/chatbot/__init__.py rename backend/app/api/routes/{chatbot.py => chatbot/message.py} (91%) create mode 100644 backend/app/services/chatbot/exceptions.py create mode 100644 backend/app/services/chatbot/types.py diff --git a/backend/app/api/routes/chatbot/__init__.py b/backend/app/api/routes/chatbot/__init__.py new file mode 100644 index 000000000..d427b0256 --- /dev/null +++ b/backend/app/api/routes/chatbot/__init__.py @@ -0,0 +1,6 @@ +from fastapi import APIRouter + +from app.api.routes.chatbot.message import router as message_router + +router = APIRouter(prefix="/chatbot", tags=["Chatbot"]) +router.include_router(message_router) diff --git a/backend/app/api/routes/chatbot.py b/backend/app/api/routes/chatbot/message.py similarity index 91% rename from backend/app/api/routes/chatbot.py rename to backend/app/api/routes/chatbot/message.py index fb10f91b7..9a5368258 100644 --- a/backend/app/api/routes/chatbot.py +++ b/backend/app/api/routes/chatbot/message.py @@ -3,15 +3,12 @@ from app.api.deps import AuthContextDep, SessionDep from app.api.permissions import Permission, require_permission from app.models import ChatbotMessage, ChatbotTurnRequest, ChatbotTurnResponse -from app.services.chatbot.engine import ( - ChatbotInputError, - ChatbotProviderError, - run_chatbot_turn, -) from app.services.chatbot.config import resolve_chatbot_model_settings +from app.services.chatbot.engine import run_chatbot_turn +from app.services.chatbot.exceptions import ChatbotInputError, ChatbotProviderError from app.utils import APIResponse, load_description -router = APIRouter(prefix="/chatbot", tags=["Chatbot"]) +router = APIRouter() @router.post( diff --git a/backend/app/models/chatbot.py b/backend/app/models/chatbot.py index c06a6540b..3797fe43e 100644 --- a/backend/app/models/chatbot.py +++ b/backend/app/models/chatbot.py @@ -34,7 +34,6 @@ class ChatbotTurnRequest(SQLModel): gt=0, description="Token size of the history above which older turns are summarized; omit for the server default.", ) - # Required every call in v0: there is no server-side storage of the flow prompt yet. system_prompt: str = Field( min_length=1, description="Admin-authored flow prompt (goal, fields to collect, rules).", diff --git a/backend/app/services/chatbot/config.py b/backend/app/services/chatbot/config.py index 9f3d4fc0f..45553fbd5 100644 --- a/backend/app/services/chatbot/config.py +++ b/backend/app/services/chatbot/config.py @@ -10,7 +10,7 @@ from app.models import ConfigVersion from app.models.llm.constants import Provider from app.models.llm.request import ConfigBlob, KaapiTextCompletionConfig -from app.services.chatbot.engine import ChatbotInputError +from app.services.chatbot.exceptions import ChatbotInputError from app.services.chatbot.utils import ( DEFAULT_HISTORY_TOKEN_LIMIT, DEFAULT_MAX_OUTPUT_TOKENS, @@ -19,16 +19,12 @@ default_thinking, ) -logger = logging.getLogger(__name__) - _ANTHROPIC_EFFORT_LEVELS: tuple[AnthropicEffort, ...] = get_args(AnthropicEffort) def _get_config_version( *, session: Session, project_id: int, config_id: UUID, config_version: int | None ) -> ConfigVersion: - # The crud constructor and `exists_or_raise` already 404 when the config or - # version is outside this project, so ownership is enforced here. version_crud = ConfigVersionCrud( session=session, config_id=config_id, project_id=project_id ) @@ -37,10 +33,6 @@ def _get_config_version( latest = version_crud.read_latest() if latest is None: - logger.warning( - f"[_get_config_version] Config has no versions | " - f"config_id: {config_id}, project_id: {project_id}" - ) raise HTTPException( status_code=404, detail=f"No version found for config '{config_id}'", @@ -54,8 +46,6 @@ def _to_anthropic_effort(effort: str | None) -> AnthropicEffort | None: for level in _ANTHROPIC_EFFORT_LEVELS: if level == effort: return level - # Kaapi's "none"/"minimal" have no Anthropic equivalent; dropping them - # silently would let the provider default (often higher) take over. raise ChatbotInputError( f"[KAAPI] Config param 'effort' value '{effort}' is not an Anthropic effort " f"level ({', '.join(_ANTHROPIC_EFFORT_LEVELS)}); update the config." @@ -86,11 +76,6 @@ def resolve_chatbot_model_settings( try: blob = ConfigBlob.model_validate(version_row.config_blob) except ValidationError as e: - logger.warning( - f"[resolve_chatbot_model_settings] [KAAPI] Stored config blob is invalid | " - f"config_id: {config_id}, version: {version_row.version}", - exc_info=True, - ) raise ChatbotInputError( f"[KAAPI] Stored configuration blob is invalid: {e}" ) from e @@ -100,11 +85,6 @@ def resolve_chatbot_model_settings( not isinstance(completion, KaapiTextCompletionConfig) or completion.provider != Provider.ANTHROPIC ): - logger.warning( - f"[resolve_chatbot_model_settings] [KAAPI] Unsupported config for chatbot | " - f"config_id: {config_id}, version: {version_row.version}, " - f"provider: {completion.provider}, type: {completion.type}" - ) raise ChatbotInputError( "[KAAPI] Chatbot only supports configs with completion provider " f"'{Provider.ANTHROPIC.value}' and type 'text'; got provider " @@ -113,10 +93,6 @@ def resolve_chatbot_model_settings( params = completion.params if not params.model: - logger.warning( - f"[resolve_chatbot_model_settings] [KAAPI] Config has no model | " - f"config_id: {config_id}, version: {version_row.version}" - ) raise ChatbotInputError( "[KAAPI] Config is missing completion.params.model; set a model on the config." ) @@ -133,9 +109,4 @@ def resolve_chatbot_model_settings( else DEFAULT_HISTORY_TOKEN_LIMIT ), ) - logger.info( - f"[resolve_chatbot_model_settings] Resolved chatbot model settings | " - f"config_id: {config_id}, version: {version_row.version}, " - f"model: {model_settings.model}, effort: {model_settings.reasoning_effort}" - ) return model_settings diff --git a/backend/app/services/chatbot/engine.py b/backend/app/services/chatbot/engine.py index 380bf3eb0..17aeb6ca2 100644 --- a/backend/app/services/chatbot/engine.py +++ b/backend/app/services/chatbot/engine.py @@ -1,40 +1,22 @@ -"""v0 chatbot: a single LangGraph node wrapping a LangChain chat model. - -Unlike a field-by-field collector, this mirrors OCS's own approach: the -admin supplies the full prompt (goal + fields + rules, written as free text -- -the same shape as OCS's `prompt` field) and the model manages the conversation -itself, reading the full message history every turn. There is no field-by-field -state machine in code here. - -No tools in v0 -- OCS's node also lets the admin attach tools (e.g. -set-session-state); that is deliberately left out here and is the natural next -step once this shape is proven. - -No checkpointer: like OCS, there is no LangGraph-level pause/resume. The caller -keeps the running message list itself and passes the full history into -`graph.invoke(...)` on every turn -- a fresh, complete run each time. -""" +"""v0 chatbot: a single LangGraph node wrapping a LangChain chat model.""" import asyncio -import logging -from typing import Annotated, TypedDict import anthropic from langchain_core.language_models.chat_models import BaseChatModel from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, SystemMessage from langgraph.graph import END, START, StateGraph -from langgraph.graph.message import add_messages from langgraph.graph.state import CompiledStateGraph from app.models.chatbot import ChatbotMessageRoleEnum +from app.services.chatbot.exceptions import ChatbotInputError, ChatbotProviderError +from app.services.chatbot.types import ChatbotMessageDict, ChatbotState from app.services.chatbot.utils import ( FLOW_KEEP_RECENT_MESSAGES, ChatbotModelSettings, get_chat_model, ) -logger = logging.getLogger(__name__) - CHATBOT_NODE = "chatbot_node" _SUMMARY_NOTE_PREFIX = "[Earlier conversation summary] " @@ -43,31 +25,9 @@ "user has already given -- this note replaces the original messages." ) -# Anthropic rejects a request whose first non-system turn isn't a user turn, so -# the opening greeting (and every later call, whose history starts with that -# greeting) needs a synthetic user turn in front. It's stripped from the -# returned transcript by this fixed id, so callers never see it. _KICKOFF_MESSAGE_ID = "chatbot-kickoff" _KICKOFF_MESSAGE_CONTENT = "Begin the conversation." -ChatbotMessageDict = dict[str, str] - - -class ChatbotState(TypedDict): - # `add_messages` is LangGraph's prebuilt reducer for LangChain message - # lists: it appends new messages and merges by `.id` instead of naively - # concatenating, which is what lets callers keep re-sending the running - # history without duplicating turns. - messages: Annotated[list[BaseMessage], add_messages] - - -class ChatbotInputError(ValueError): - """The turn request can't produce a valid model call (caller's fault).""" - - -class ChatbotProviderError(Exception): - """The chat-model provider failed or was unreachable.""" - def _summarize_if_needed( chat_model: BaseChatModel, @@ -75,14 +35,7 @@ def _summarize_if_needed( *, history_token_limit: int, ) -> list[BaseMessage]: - """Trim the view sent to the model once history crosses the token budget. - - Simplification: this only shrinks what THIS call sends to Anthropic: the - caller's own running history keeps growing untouched, so a long-enough - conversation re-summarizes from scratch each turn rather than compacting - state permanently. OCS's real history middleware persists the compression - point instead -- worth doing if this gets reused past v0. - """ + """Trim the view sent to the model once history crosses the token budget.""" if len(messages) <= FLOW_KEEP_RECENT_MESSAGES + 1: # +1 for the system message return messages if chat_model.get_num_tokens_from_messages(messages) <= history_token_limit: @@ -93,11 +46,6 @@ def _summarize_if_needed( rest[:-FLOW_KEEP_RECENT_MESSAGES], rest[-FLOW_KEEP_RECENT_MESSAGES:], ) - # Anthropic requires the first non-system turn to be a user turn. `rest` - # always ends on this turn's unanswered human message, so it has odd - # length; cutting an even-sized window from its tail always lands one - # message short, opening on an assistant turn instead. Shift the boundary - # back until `recent` starts on a human message. while recent and to_summarize and not isinstance(recent[0], HumanMessage): recent.insert(0, to_summarize.pop()) if not to_summarize: @@ -106,10 +54,6 @@ def _summarize_if_needed( summary = chat_model.invoke( [SystemMessage(content=_SUMMARIZE_INSTRUCTION), *to_summarize] ) - logger.info( - f"[_summarize_if_needed] Compressed history | " - f"from: {len(to_summarize)} messages, to: 1 summary note" - ) summary_note = SystemMessage(content=f"{_SUMMARY_NOTE_PREFIX}{summary.text}") return [system_message, summary_note, *recent] @@ -136,9 +80,6 @@ def chatbot_node(state: ChatbotState) -> dict[str, list[BaseMessage]]: def _to_langchain_messages( *, system_prompt: str, history: list[ChatbotMessageDict], user_message: str | None ) -> list[BaseMessage]: - # `system_prompt` is the single source of the system turn; any system entry - # echoed back in `history` (the previous response includes it) is dropped - # so it isn't sent twice. conversation: list[BaseMessage] = [] for entry in history: role = entry["role"] @@ -175,7 +116,6 @@ def _to_message_dicts( role = ChatbotMessageRoleEnum.ASSISTANT else: continue - # `.text` drops thinking/tool blocks; the wire shape carries text only. transcript.append({"role": role.value, "content": message.text}) return transcript @@ -193,10 +133,6 @@ async def run_chatbot_turn( which yields the bot's opening greeting. """ if user_message is None and history: - logger.warning( - f"[run_chatbot_turn] [KAAPI] Missing user message on a non-initial turn | " - f"history_count: {len(history)}" - ) raise ChatbotInputError( "[KAAPI] `message` is required once `history` is non-empty; omit it only " "on the first call to get the opening greeting." @@ -205,10 +141,6 @@ async def run_chatbot_turn( messages = _to_langchain_messages( system_prompt=system_prompt, history=history, user_message=user_message ) - logger.info( - f"[run_chatbot_turn] Starting turn | history_count: {len(history)}, " - f"has_user_message: {user_message is not None}, model: {model_settings.model}" - ) graph = build_chatbot_graph( get_chat_model(model_settings), @@ -218,33 +150,16 @@ async def run_chatbot_turn( # ChatAnthropic.invoke is sync; keep it off the event loop. result = await asyncio.to_thread(graph.invoke, {"messages": messages}) except anthropic.APITimeoutError as e: - logger.error( - f"[run_chatbot_turn] [KAAPI] Request to Anthropic timed out (code: APITimeoutError) | " - f"provider=anthropic, model={model_settings.model}", - exc_info=True, - ) raise ChatbotProviderError( "[KAAPI] Request timed out — retry smaller. If persistent, contact Kaapi. " "(code: APITimeoutError)" ) from e except anthropic.APIConnectionError as e: - logger.error( - f"[run_chatbot_turn] [KAAPI] Could not reach Anthropic (code: APIConnectionError) | " - f"provider=anthropic, model={model_settings.model}", - exc_info=True, - ) raise ChatbotProviderError( "[KAAPI] Network/DNS issue reaching provider — check connectivity. " "If persistent, contact Kaapi. (code: APIConnectionError)" ) from e except anthropic.APIStatusError as e: - # 5xx is provider-side (alert-worthy); 4xx is caller's fault (noise if alerted) - log = logger.error if e.status_code >= 500 else logger.warning - log( - f"[run_chatbot_turn] [ANTHROPIC] {e.message} (code: {e.status_code}) | " - f"provider=anthropic, model={model_settings.model}, request_id={e.request_id}", - exc_info=True, - ) raise ChatbotProviderError( f"[ANTHROPIC] Chat model call failed: {e.message} (code: {e.status_code}, " f"request_id: {e.request_id})" @@ -253,8 +168,4 @@ async def run_chatbot_turn( transcript = _to_message_dicts( system_prompt=system_prompt, messages=result["messages"] ) - logger.info( - f"[run_chatbot_turn] Turn completed | transcript_count: {len(transcript)}, " - f"reply_length: {len(transcript[-1]['content'])}" - ) return transcript diff --git a/backend/app/services/chatbot/exceptions.py b/backend/app/services/chatbot/exceptions.py new file mode 100644 index 000000000..aac653752 --- /dev/null +++ b/backend/app/services/chatbot/exceptions.py @@ -0,0 +1,6 @@ +class ChatbotInputError(ValueError): + """The turn request can't produce a valid model call (caller's fault).""" + + +class ChatbotProviderError(Exception): + """The chat-model provider failed or was unreachable.""" diff --git a/backend/app/services/chatbot/types.py b/backend/app/services/chatbot/types.py new file mode 100644 index 000000000..7746f215d --- /dev/null +++ b/backend/app/services/chatbot/types.py @@ -0,0 +1,10 @@ +from typing import Annotated, TypedDict + +from langchain_core.messages import BaseMessage +from langgraph.graph.message import add_messages + +ChatbotMessageDict = dict[str, str] + + +class ChatbotState(TypedDict): + messages: Annotated[list[BaseMessage], add_messages] diff --git a/backend/app/services/chatbot/utils.py b/backend/app/services/chatbot/utils.py index 2ec9571a1..d4831b46f 100644 --- a/backend/app/services/chatbot/utils.py +++ b/backend/app/services/chatbot/utils.py @@ -1,10 +1,4 @@ -"""Model/runtime settings for the v0 LangGraph + LangChain chatbot node. - -Like OCS's `LLMResponseWithPrompt` node, the model and reasoning settings come -from per-request input -- here a saved Kaapi config (see -`services/chatbot/config.py`) plus optional token overrides on the request. -Only Anthropic is wired up, since the node's chat model is `ChatAnthropic`. -""" +"""Model/runtime settings for the v0 LangGraph + LangChain chatbot node.""" from dataclasses import dataclass, field from typing import Any, Literal @@ -18,15 +12,11 @@ DEFAULT_MAX_OUTPUT_TOKENS = 1024 DEFAULT_THINKING: dict[str, Any] = {"type": "adaptive"} -# OCS's `history_mode=summarize`, simplified: once the running history crosses -# this many tokens, everything except the system prompt and the most recent -# turns is summarized into one note before the next model call. DEFAULT_HISTORY_TOKEN_LIMIT = 4000 FLOW_KEEP_RECENT_MESSAGES = 6 def default_thinking() -> dict[str, Any]: - # Fresh copy so one request can't mutate the module-level default. return dict(DEFAULT_THINKING) @@ -34,7 +24,6 @@ def default_thinking() -> dict[str, Any]: class ChatbotModelSettings: model: str max_tokens: int = DEFAULT_MAX_OUTPUT_TOKENS - # None lets the provider pick its own default effort. reasoning_effort: AnthropicEffort | None = None thinking: dict[str, Any] = field(default_factory=default_thinking) history_token_limit: int = DEFAULT_HISTORY_TOKEN_LIMIT From 6e162a009179c2e434b35b3e6fbf6c8963bbd624 Mon Sep 17 00:00:00 2001 From: Ayush8923 <80516839+Ayush8923@users.noreply.github.com> Date: Tue, 20 Oct 2026 13:32:42 +0530 Subject: [PATCH 7/8] fix: cleanups --- backend/app/services/chatbot/config.py | 1 - 1 file changed, 1 deletion(-) diff --git a/backend/app/services/chatbot/config.py b/backend/app/services/chatbot/config.py index 45553fbd5..e8f09c666 100644 --- a/backend/app/services/chatbot/config.py +++ b/backend/app/services/chatbot/config.py @@ -1,4 +1,3 @@ -import logging from typing import get_args from uuid import UUID From 0f4ef22927df2508a5a213e5e611015b99e7f879 Mon Sep 17 00:00:00 2001 From: Ayush8923 <80516839+Ayush8923@users.noreply.github.com> Date: Wed, 21 Oct 2026 14:18:09 +0530 Subject: [PATCH 8/8] fix: added the get endpoints and status updates --- .../versions/088_add_chatbot_session.py | 7 ++- backend/app/api/docs/chatbot/list_sessions.md | 3 ++ backend/app/api/routes/chatbot/session.py | 45 ++++++++++++++++++- backend/app/crud/chatbot.py | 19 ++++++++ backend/app/models/__init__.py | 2 + backend/app/models/chatbot.py | 22 ++++++--- docs/wiki/modules/chatbot.md | 2 + 7 files changed, 88 insertions(+), 12 deletions(-) create mode 100644 backend/app/api/docs/chatbot/list_sessions.md diff --git a/backend/app/alembic/versions/088_add_chatbot_session.py b/backend/app/alembic/versions/088_add_chatbot_session.py index 9e5ec9f51..367a924ce 100644 --- a/backend/app/alembic/versions/088_add_chatbot_session.py +++ b/backend/app/alembic/versions/088_add_chatbot_session.py @@ -52,13 +52,12 @@ def upgrade(): sa.Column( "status", sa.Enum( - "in_progress", - "completed", - "abandoned", + "active", + "inactive", name="chatbotsessionstatusenum", ), nullable=False, - comment="Conversation lifecycle: in_progress, completed, or abandoned", + comment="Conversation lifecycle: active or inactive", ), sa.Column( "collected_fields", diff --git a/backend/app/api/docs/chatbot/list_sessions.md b/backend/app/api/docs/chatbot/list_sessions.md new file mode 100644 index 000000000..202480359 --- /dev/null +++ b/backend/app/api/docs/chatbot/list_sessions.md @@ -0,0 +1,3 @@ +List every chatbot session for the given `contact_ref` in the caller's project, most recent first. + +`contact_ref` is matched exactly against the value supplied when the session was created. Each entry carries the session's current `status` and the `collected_fields` gathered so far. Returns an empty list when the contact has no sessions in this project. diff --git a/backend/app/api/routes/chatbot/session.py b/backend/app/api/routes/chatbot/session.py index be47eae34..0ea7d60f1 100644 --- a/backend/app/api/routes/chatbot/session.py +++ b/backend/app/api/routes/chatbot/session.py @@ -2,7 +2,7 @@ from uuid import UUID from asgi_correlation_id import correlation_id -from fastapi import APIRouter, Depends, HTTPException, Path +from fastapi import APIRouter, Depends, HTTPException, Path, Query from app.api.deps import AuthContextDep, SessionDep from app.api.permissions import Permission, require_permission @@ -12,9 +12,12 @@ create_chatbot_session_message, get_chatbot_session, list_chatbot_session_messages, + list_chatbot_sessions_by_contact_ref, ) from app.models import ( + CONTACT_REF_MAX_LENGTH, ChatbotMessageRoleEnum, + ChatbotSessionSummary, CreateChatbotSessionRequest, CreateChatbotSessionResponse, SendChatbotSessionMessageRequest, @@ -68,6 +71,46 @@ def start_chatbot_session( ) +@router.get( + "/sessions", + description=load_description("chatbot/list_sessions.md"), + response_model=APIResponse[list[ChatbotSessionSummary]], + dependencies=[Depends(require_permission(Permission.REQUIRE_PROJECT))], +) +def list_chatbot_sessions( + contact_ref: Annotated[ + str, + Query( + min_length=1, + max_length=CONTACT_REF_MAX_LENGTH, + description="Caller-side identifier of the end user whose sessions to list", + ), + ], + session: SessionDep, + auth_context: AuthContextDep, +) -> APIResponse[list[ChatbotSessionSummary]]: + chatbot_sessions = list_chatbot_sessions_by_contact_ref( + session, + contact_ref=contact_ref, + organization_id=auth_context.organization_.id, + project_id=auth_context.project_.id, + ) + summaries: list[ChatbotSessionSummary] = [] + for chatbot_session in chatbot_sessions: + summary = ChatbotSessionSummary( + session_id=chatbot_session.id, + contact_ref=chatbot_session.contact_ref, + status=chatbot_session.status, + collected_fields=chatbot_session.collected_fields, + config_id=chatbot_session.config_id, + config_version=chatbot_session.config_version, + inserted_at=chatbot_session.inserted_at, + updated_at=chatbot_session.updated_at, + ) + summaries.append(summary) + return APIResponse.success_response(summaries) + + @router.post( "/sessions/{session_id}/message", status_code=202, diff --git a/backend/app/crud/chatbot.py b/backend/app/crud/chatbot.py index 058277153..3b1d10304 100644 --- a/backend/app/crud/chatbot.py +++ b/backend/app/crud/chatbot.py @@ -93,3 +93,22 @@ def list_chatbot_session_messages( .order_by(col(ChatbotSessionMessage.inserted_at).asc()) ) return list(session.exec(statement).all()) + + +def list_chatbot_sessions_by_contact_ref( + session: Session, + *, + contact_ref: str, + organization_id: int, + project_id: int, +) -> list[ChatbotSession]: + statement = ( + select(ChatbotSession) + .where( + ChatbotSession.contact_ref == contact_ref, + ChatbotSession.organization_id == organization_id, + ChatbotSession.project_id == project_id, + ) + .order_by(col(ChatbotSession.inserted_at).desc()) + ) + return list(session.exec(statement).all()) diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py index 8ac2eb18f..dc7f2e3be 100644 --- a/backend/app/models/__init__.py +++ b/backend/app/models/__init__.py @@ -36,11 +36,13 @@ BatchJobUpdate, ) from .chatbot import ( + CONTACT_REF_MAX_LENGTH, ChatbotMessage, ChatbotMessageRoleEnum, ChatbotSession, ChatbotSessionMessage, ChatbotSessionStatusEnum, + ChatbotSessionSummary, ChatbotTurnRequest, ChatbotTurnResponse, CreateChatbotSessionRequest, diff --git a/backend/app/models/chatbot.py b/backend/app/models/chatbot.py index 2e6aae1e5..a5cfe381b 100644 --- a/backend/app/models/chatbot.py +++ b/backend/app/models/chatbot.py @@ -62,13 +62,10 @@ class ChatbotTurnResponse(SQLModel): class ChatbotSessionStatusEnum(StrEnum): - IN_PROGRESS = "in_progress" - COMPLETED = "completed" - ABANDONED = "abandoned" + ACTIVE = "active" + INACTIVE = "inactive" -# values_callable stores the lowercase member values the migration created the -# Postgres enum types with; SQLAlchemy's default would store member names. _SESSION_STATUS_PG_ENUM = ENUM( ChatbotSessionStatusEnum, name="chatbotsessionstatusenum", @@ -121,11 +118,11 @@ class ChatbotSession(SQLModel, table=True): }, ) status: ChatbotSessionStatusEnum = Field( - default=ChatbotSessionStatusEnum.IN_PROGRESS, + default=ChatbotSessionStatusEnum.ACTIVE, sa_column=Column( _SESSION_STATUS_PG_ENUM, nullable=False, - comment="Conversation lifecycle: in_progress, completed, or abandoned", + comment="Conversation lifecycle: active or inactive", ), ) collected_fields: dict[str, Any] = Field( @@ -223,6 +220,17 @@ class CreateChatbotSessionResponse(SQLModel): session_id: UUID +class ChatbotSessionSummary(SQLModel): + session_id: UUID + contact_ref: str + status: ChatbotSessionStatusEnum + collected_fields: dict[str, Any] + config_id: UUID + config_version: int | None + inserted_at: datetime + updated_at: datetime + + class SendChatbotSessionMessageRequest(SQLModel): message: str | None = Field( default=None, diff --git a/docs/wiki/modules/chatbot.md b/docs/wiki/modules/chatbot.md index 261046755..8023c2521 100644 --- a/docs/wiki/modules/chatbot.md +++ b/docs/wiki/modules/chatbot.md @@ -6,6 +6,7 @@ All paths relative to `backend/app/`. ## Routes - `api/routes/chatbot.py` — `POST /chatbot/message` (one synchronous turn; requires project scope) +- `api/routes/chatbot/session.py` — `GET /chatbot/sessions?contact_ref=` (all sessions for a contact in the caller's project, newest first → `list[ChatbotSessionSummary]`) ## Tables (SQLModel) None of its own. Request/response shapes only: `models/chatbot.py` (`ChatbotMessage`, `ChatbotMessageRoleEnum`, `ChatbotTurnRequest`, `ChatbotTurnResponse`). Reads `config` / `config_version` (see the config module) to resolve the model. @@ -14,6 +15,7 @@ None of its own. Request/response shapes only: `models/chatbot.py` (`ChatbotMess - `services/chatbot/config.py` — `resolve_chatbot_model_settings` (saved config + request overrides → `ChatbotModelSettings`; 404 via `ConfigVersionCrud`, 422 for non-Anthropic/non-text/no-model configs) - `services/chatbot/engine.py` — `run_chatbot_turn` (dict <-> LangChain message conversion, error mapping), `build_chatbot_graph`, history summarization - `services/chatbot/utils.py` — `ChatbotModelSettings`, defaults (`DEFAULT_MAX_OUTPUT_TOKENS`, `DEFAULT_HISTORY_TOKEN_LIMIT`, `FLOW_KEEP_RECENT_MESSAGES`), `get_chat_model` +- `crud/chatbot.py` — `list_chatbot_sessions_by_contact_ref` (org + project scoped, `inserted_at` desc, unpaginated) - `crud/config/version.py` — `ConfigVersionCrud.read_latest` (used when `config_version` is omitted) ## Async