diff --git a/docs/devel_doc/openapi.json b/docs/devel_doc/openapi.json index af5a5fbdc..0cf9ba82d 100644 --- a/docs/devel_doc/openapi.json +++ b/docs/devel_doc/openapi.json @@ -8490,7 +8490,8 @@ } } } - } + }, + "deprecated": true } }, "/v1/conversations/{conversation_id}": { @@ -8501,6 +8502,7 @@ "summary": "Conversation Get Endpoint Handler V1", "description": "Handle request to retrieve a conversation identified by ID using Conversations API.\n\nRetrieve a conversation's chat history by its ID using the OGX\nConversations API. This endpoint fetches the conversation items from\nthe backend, simplifies them to essential chat history, and returns\nthem in a structured response. Raises HTTP 400 for invalid IDs, 404\nif not found, 503 if the backend is unavailable, and 500 for\nunexpected errors.\n\nArgs:\n request: The FastAPI request object\n conversation_id: Unique identifier of the conversation to retrieve\n auth: Authentication tuple from dependency\n\nReturns:\n ConversationResponse: Structured response containing the conversation\n ID and simplified chat history", "operationId": "get_conversation_endpoint_handler_v1_conversations__conversation_id__get", + "deprecated": true, "parameters": [ { "name": "conversation_id", @@ -8765,6 +8767,7 @@ "summary": "Conversation Delete Endpoint Handler V1", "description": "Handle request to delete a conversation by ID using Conversations API.\n\nValidates the conversation ID format and attempts to delete the\nconversation from the OGX backend using the Conversations API.\nRaises HTTP errors for invalid IDs, not found conversations, connection\nissues, or unexpected failures.\n\nArgs:\n request: The FastAPI request object\n conversation_id: Unique identifier of the conversation to delete\n auth: Authentication tuple from dependency\n\nReturns:\n ConversationDeleteResponse: Response indicating the result of the deletion operation", "operationId": "delete_conversation_endpoint_handler_v1_conversations__conversation_id__delete", + "deprecated": true, "parameters": [ { "name": "conversation_id", @@ -9002,6 +9005,7 @@ "summary": "Conversation Update Endpoint Handler V1", "description": "Handle request to update a conversation metadata using Conversations API.\n\nUpdates the conversation metadata (including topic summary) in both the\nOGX backend using the Conversations API and the local database.\n\nArgs:\n request: The FastAPI request object\n conversation_id: Unique identifier of the conversation to update\n update_request: Request containing the topic summary to update\n auth: Authentication tuple from dependency\n\nReturns:\n ConversationUpdateResponse: Response indicating the result of the update operation", "operationId": "update_conversation_endpoint_handler_v1_conversations__conversation_id__put", + "deprecated": true, "parameters": [ { "name": "conversation_id", @@ -23693,7 +23697,7 @@ }, { "name": "conversations_v1", - "description": "Conversations API v1." + "description": "Conversations API v1 (OGX-backed). Deprecated: use /v2/conversations; scheduled for removal when OGX is dropped." }, { "name": "conversations_v2", diff --git a/docs/migrations/index.md b/docs/migrations/index.md index 6e0c141f1..a8c7882ff 100644 --- a/docs/migrations/index.md +++ b/docs/migrations/index.md @@ -5,4 +5,4 @@ release that includes breaking or notable configuration changes. | Version | Description | |---------|-------------| -| [v0.7.0](v0.7.0.md) | RAG configuration restructured; `ogx` naming with optional deprecated `llama_stack` alias | +| [v0.7.0](v0.7.0.md) | RAG configuration restructured; `ogx` naming; `/v1/vector-stores` and `/v1/conversations` deprecated | diff --git a/docs/migrations/v0.7.0.md b/docs/migrations/v0.7.0.md index d2a26e0d2..f0d7e9a58 100644 --- a/docs/migrations/v0.7.0.md +++ b/docs/migrations/v0.7.0.md @@ -5,6 +5,7 @@ * [RAG Configuration](#rag-configuration) * [OGX naming (`llama_stack` → `ogx`)](#ogx-naming-llama_stack--ogx) * [Vector stores API deprecation](#vector-stores-api-deprecation) +* [Conversations API v1 deprecation](#conversations-api-v1-deprecation) --- @@ -194,3 +195,16 @@ OGX is dropped from Lightspeed Core Stack. Migrate to [BYOK RAG](../user_doc/byok_guide.md) for document retrieval. The OpenAPI schema marks these operations as `deprecated`. + +--- + +## Conversations API v1 deprecation + +The `/v1/conversations` routes use OGX Conversations persistence. They are +**deprecated in v0.7.0** and will be **removed in a later release** when OGX +is dropped from Lightspeed Core Stack. + +Migrate to `/v2/conversations`, which uses LCORE-owned storage. After OGX +removal, keeping both surfaces would duplicate the same CRUD API, so v2 remains +the sole conversations API. The OpenAPI schema marks the v1 operations as +`deprecated`. diff --git a/src/app/endpoints/README.md b/src/app/endpoints/README.md index b28d58fdb..0cbf00c96 100644 --- a/src/app/endpoints/README.md +++ b/src/app/endpoints/README.md @@ -22,7 +22,8 @@ Handler for REST API call to retrieve service configuration. ## [conversations_v1.py](conversations_v1.py) -Handler for REST API calls to manage conversation history using Conversations API. +Handler for REST API calls to manage conversation history using Conversations API +(deprecated; use `conversations_v2.py` / `/v2/conversations`). ## [conversations_v2.py](conversations_v2.py) diff --git a/src/app/endpoints/conversations_v1.py b/src/app/endpoints/conversations_v1.py index d744db5f4..3c4f823b5 100644 --- a/src/app/endpoints/conversations_v1.py +++ b/src/app/endpoints/conversations_v1.py @@ -1,4 +1,14 @@ -"""Handler for REST API calls to manage conversation history using Conversations API.""" +"""Handler for REST API calls to manage conversation history using Conversations API. + +These routes use OGX Conversations persistence. They are deprecated and will be +removed in a later LCS release when OGX is dropped from the stack. Use +``/v2/conversations`` instead (LCORE-owned storage). +""" + +CONVERSATIONS_V1_DEPRECATED_REASON: str = ( + "OGX-backed Conversations API; deprecated and scheduled for removal. " + "Use /v2/conversations instead." +) from typing import Any @@ -7,6 +17,7 @@ from ogx_client import ApiException from opentelemetry import trace from sqlalchemy.exc import SQLAlchemyError +from typing_extensions import deprecated from app.database import get_session from authentication import get_auth_dependency @@ -56,7 +67,10 @@ logger = get_logger(__name__) tracer = trace.get_tracer(__name__) -router = APIRouter(tags=["conversations_v1"]) +router = APIRouter( + tags=["conversations_v1"], + deprecated=True, +) conversation_get_responses: Responses = { 200: ConversationResponse.openapi_response(), @@ -120,6 +134,7 @@ summary="Conversations List Endpoint Handler V1", ) @authorize(Action.LIST_CONVERSATIONS) +@deprecated(CONVERSATIONS_V1_DEPRECATED_REASON) async def get_conversations_list_endpoint_handler( request: Request, auth: Any = Depends(get_auth_dependency()), @@ -186,6 +201,7 @@ async def get_conversations_list_endpoint_handler( summary="Conversation Get Endpoint Handler V1", ) @authorize(Action.GET_CONVERSATION) +@deprecated(CONVERSATIONS_V1_DEPRECATED_REASON) async def get_conversation_endpoint_handler( # pylint: disable=too-many-locals,too-many-statements request: Request, conversation_id: str, @@ -308,6 +324,7 @@ async def get_conversation_endpoint_handler( # pylint: disable=too-many-locals, summary="Conversation Delete Endpoint Handler V1", ) @authorize(Action.DELETE_CONVERSATION) +@deprecated(CONVERSATIONS_V1_DEPRECATED_REASON) async def delete_conversation_endpoint_handler( request: Request, conversation_id: str, @@ -428,6 +445,7 @@ async def delete_conversation_endpoint_handler( summary="Conversation Update Endpoint Handler V1", ) @authorize(Action.UPDATE_CONVERSATION) +@deprecated(CONVERSATIONS_V1_DEPRECATED_REASON) async def update_conversation_endpoint_handler( # pylint: disable=too-many-statements request: Request, conversation_id: str, diff --git a/src/app/main.py b/src/app/main.py index b5970e45a..6b8a13632 100644 --- a/src/app/main.py +++ b/src/app/main.py @@ -42,7 +42,13 @@ {"name": "a2a", "description": "Agent-to-Agent (A2A) protocol."}, {"name": "authorized", "description": "Authorization probe."}, {"name": "config", "description": "Service configuration."}, - {"name": "conversations_v1", "description": "Conversations API v1."}, + { + "name": "conversations_v1", + "description": ( + "Conversations API v1 (OGX-backed). Deprecated: use /v2/conversations; " + "scheduled for removal when OGX is dropped." + ), + }, {"name": "conversations_v2", "description": "Conversations API v2."}, {"name": "feedback", "description": "User feedback."}, {"name": "health", "description": "Health and readiness probes."},