feat:Unify and simplify Cohere API schema definitions and update code examples #209
Conversation
WalkthroughThe OpenAPI specification for the Cohere API was updated to unify and simplify schema definitions by removing V2-specific suffixes from message and content types. Multiple schemas were renamed, new schemas were introduced, and example code snippets for Go and Java were updated to use the new types. Streaming response schemas and documentation were also refined. Changes
Poem
✨ Finishing Touches🧪 Generate Unit Tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
coderabbitai
bot
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
src/libs/Cohere/openapi.yaml (1)
16947-16957: Add description toToolSource.
ToolSourcecurrently lacks a schema‐leveldescription. Please add a description explaining its purpose and structure.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (79)
src/libs/Cohere/Generated/Cohere..JsonSerializerContext.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Chat.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Chatv2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Embed.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Embedv2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Rerank.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.CohereClient.Rerankv2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Chat.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Chatv2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Embed.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Embedv2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Rerank.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.ICohereClient.Rerankv2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ChatMessageV2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.Content2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ContentDiscriminatorType.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ContentDiscriminatorTypeNullable.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ContentItem.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ContentVariant2Item.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ContentVariant2Item2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.Message.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ResponseFormat.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ResponseFormatV2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.Source.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.SystemMessageContentVariant2ItemDiscriminatorType.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.SystemMessageContentVariant2ItemDiscriminatorTypeNullable.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.SystemMessageRole.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.SystemMessageRoleNullable.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.TextContentType.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.TextContentTypeNullable.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.ToolContent.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.UserMessageRole.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonConverters.UserMessageRoleNullable.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.JsonSerializerContextTypes.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ChatDocumentSourceDocument.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ChatMessageV2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ChatTextResponseFormatV2.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ChatToolSourceToolOutput.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.Content2.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.Content2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ContentDiscriminator.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ContentDiscriminator.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ContentDiscriminatorType.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ContentItem.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ContentVariant2Item.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ContentVariant2Item2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.DocumentSource.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.DocumentSource.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.DocumentSourceDocument.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.DocumentSourceDocument.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.EmbedByTypeResponse.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.Message.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.MessageContentDiscriminator.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ResponseFormat.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ResponseFormatV2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.Source.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.SystemMessage.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.SystemMessage.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.SystemMessageContentVariant2ItemDiscriminator.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.SystemMessageContentVariant2ItemDiscriminator.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.SystemMessageContentVariant2ItemDiscriminatorType.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.SystemMessageRole.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.TextContent.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.TextContent.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.TextContentType.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.TextResponseFormat.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.TextResponseFormat.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.TextResponseFormatV2.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.TextResponseFormatV2.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ToolContent.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ToolMessage.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ToolMessage.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ToolSource.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ToolSource.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ToolSourceToolOutput.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.ToolSourceToolOutput.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.UserMessage.Json.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.UserMessage.g.csis excluded by!**/generated/**src/libs/Cohere/Generated/Cohere.Models.UserMessageRole.g.csis excluded by!**/generated/**
📒 Files selected for processing (1)
src/libs/Cohere/openapi.yaml(25 hunks)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Test / Build, test and publish
🔇 Additional comments (23)
src/libs/Cohere/openapi.yaml (23)
20-20: Include version in summary.
Thesummaryis appropriately updated to "Chat V1 API" to reflect the endpoint version.
2148-2148: Include version in summary.
Thesummaryis updated to "Embed V1 API", aligning with the V1 endpoint naming convention.
6856-6856: Include version in summary.
Thesummaryis updated to "Rerank V1 API", consistent with the other V1 endpoint summaries.
7382-7382: Include version in summary.
Thesummaryis updated to "Chat V2 API", clearly indicating the V2 endpoint.
7558-7561: Updated V2 chat examples with new types.
The Go and Java code snippets now correctly referenceUserMessageandUserMessageContentinstead of V2-specific variants, matching the schema renames.
7596-7601: Updated Documents examples with new types.
The Java and Go samples correctly useV2ChatRequestDocumentsItemand the unifiedUserMessagetype, aligning with the updated request schemas.
7738-7744: Updated streaming examples with new types.
Java and Go streaming code samples now referenceUserMessage,UserMessageContent,ChatContentDeltaEvent, and related classes without V2 suffixes.
7938-7955: Detailed streaming response schema added.
The new properties (id,finish_reason,logprobs,message,usage), required fields, response‐stream discriminator mapping,stream-condition, andstream-descriptioncomprehensively define the v2 streaming contract.Also applies to: 7957-7985
11275-11275: Include version in summary.
Thesummaryis updated to "Rerank V2 API", matching the V2 endpoint naming.
11535-11539: Updated content mapping toTextContent.
TheoneOfand discriminator now referenceTextContentinstead of legacy types.
11566-11570: Updated content mapping toTextContent.
The array items and discriminator mappings now point toTextContentfor consistency.
11905-11907: Renamed ChatMessageV2 mappings.
ChatMessageV2now referencesUserMessage,AssistantMessage, andSystemMessage, and maps tools toToolMessageV2, removing the old Chat* prefixes.Also applies to: 11914-11916
12549-12560: AddedContentschema.
A newContentoneOf block with a discriminator unifiesTextContentandImageContentinto a single type.
12988-12998: RenamedChatDocumentSourcetoDocumentSource.
TheDocumentSourceschema is defined withidanddocumentproperties, replacing the v2-specific type.
16314-16320: Updated genericMessagemapping for tools.
TheMessageschema now referencesToolMessageinstead of the deprecatedChatToolMessage.
16498-16500: UpdatedResponseFormatdiscriminator.
The discriminator mapping now includestext: TextResponseFormat, aligning with the renamed schema.
16527-16529: UpdatedResponseFormatV2discriminator.
Thetextmapping now points toTextResponseFormatV2alongsidejson_object.
16626-16627: RenamedSourceoneOf mappings.
Sourcenow includesToolSourceandDocumentSourceinstead of the old Chat* variants.
16711-16714: AddedSystemMessageschema stub.
SystemMessageis introduced withroleas a required field, laying the groundwork for unified message types.
16724-16769: DefinedSystemMessage,TextContent, and response formats.
TheSystemMessagetype is declared and theTextContent,TextResponseFormat, andTextResponseFormatV2schemas are defined with the proper properties, discriminators, and audience tags.
16887-16894: AddedToolContentschema.
ToolContentcorrectly uses a discriminator ontypeto distinguish betweenTextContentandDocumentContent.
17145-17148: DefinedUserMessageschema stub.
UserMessageis introduced withroleas a required field, standardizing the user message type.
17157-17164: Referenced unifiedContentinUserMessage.
Thecontentproperty now uses theContentoneOf schema, supporting both text and block content.
| - code: "package main\n\nimport (\n\t\"context\"\n\t\"log\"\n\t\"os\"\n\n\tcohere \"github.com/cohere-ai/cohere-go/v2\"\n\tclient \"github.com/cohere-ai/cohere-go/v2/client\"\n)\n\nfunc main() {\n\tco := client.NewClient(client.WithToken(os.Getenv(\"CO_API_KEY\")))\n\n\tresp, err := co.V2.Chat(\n\t\tcontext.TODO(),\n\t\t&cohere.V2ChatRequest{\n\t\t\tModel: \"command-a-03-2025\",\n\t\t\tTools: []*cohere.ToolV2{\n\t\t\t\t{\n\t\t\t\t\tType: cohere.String(\"function\"),\n\t\t\t\t\tFunction: &cohere.ToolV2Function{\n\t\t\t\t\t\tName: \"query_daily_sales_report\",\n\t\t\t\t\t\tDescription: cohere.String(\"Connects to a database to retrieve overall sales volumes and sales information for a given day.\"),\n\t\t\t\t\t\tParameters: map[string]interface{}{\n\t\t\t\t\t\t\t\"type\": \"object\",\n\t\t\t\t\t\t\t\"properties\": map[string]interface{}{\n\t\t\t\t\t\t\t\t\"date\": map[string]interface{}{\n\t\t\t\t\t\t\t\t\t\"type\": \"string\",\n\t\t\t\t\t\t\t\t\t\"description\": \"Retrieves sales data from this day, formatted as YYYY-MM-DD\",\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\"required\": []string{\"date\"},\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\tType: cohere.String(\"function\"),\n\t\t\t\t\tFunction: &cohere.ToolV2Function{\n\t\t\t\t\t\tName: \"query_product_catalog\",\n\t\t\t\t\t\tDescription: cohere.String(\"Connects to a a product catalog with information about all the products being sold, including categories, prices, and stock levels.\"),\n\t\t\t\t\t\tParameters: map[string]interface{}{\n\t\t\t\t\t\t\t\"type\": \"object\",\n\t\t\t\t\t\t\t\"properties\": map[string]interface{}{\n\t\t\t\t\t\t\t\t\"category\": map[string]interface{}{\n\t\t\t\t\t\t\t\t\t\"type\": \"string\",\n\t\t\t\t\t\t\t\t\t\"description\": \"Retrieves product information data for all products in this category.\",\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\"required\": []string{\"category\"},\n\t\t\t\t\t\t},\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t\tMessages: cohere.ChatMessages{\n\t\t\t\t{\n\t\t\t\t\tRole: \"user\",\n\t\t\t\t\tUser: &cohere.UserMessage{Content: &cohere.UserMessageContent{\n\t\t\t\t\t\tString: \"Can you provide a sales summary for 29th September 2023, and also give me some details about the products in the 'Electronics' category, for example their prices and stock levels?\",\n\t\t\t\t\t}},\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t)\n\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tlog.Printf(\"%+v\", resp)\n}\n" | ||
| name: Tools | ||
| sdk: go | ||
| - code: "curl --request POST \\\n --url https://api.cohere.com/v2/chat \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --header \"Authorization: bearer $CO_API_KEY\" \\\n --data '{\n \"model\": \"command-a-03-2025\",\n \"tools\": [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"query_daily_sales_report\",\n \"description\": \"Connects to a database to retrieve overall sales volumes and sales information for a given day.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"day\": {\n \"description\": \"Retrieves sales data for this day, formatted as YYYY-MM-DD.\",\n \"type\": \"string\"\n }\n }\n }\n }\n },\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"query_product_catalog\",\n \"description\": \"Connects to a a product catalog with information about all the products being sold, including categories, prices, and stock levels.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"category\": {\n \"description\": \"Retrieves product information data for all products in this category.\",\n \"type\": \"string\"\n }\n }\n }\n }\n }\n ],\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Can you provide a sales summary for 29th September 2023, and also give me some details about the products in the 'Electronics' category, for example their prices and stock levels?\"\n }\n ]\n }'\n" |
There was a problem hiding this comment.
Inconsistent parameter key in Go Tools example.
The Go snippet defines the daily report tool’s parameter as "date" while the Java example uses "day". Align the property name across examples (e.g., use "day" in Go).
Apply this diff:
- "properties": map[string]interface{}{
- "date": map[string]interface{}{
+ "properties": map[string]interface{}{
+ "day": map[string]interface{}{
...
- "required": []string{"date"},
+ "required": []string{"day"},🤖 Prompt for AI Agents
In src/libs/Cohere/openapi.yaml around lines 7869 to 7872, the Go example for
the daily sales report tool uses the parameter key "date" while the Java example
uses "day". To fix this inconsistency, rename the "date" parameter key to "day"
in the Go example's tool definition so it matches the Java example, ensuring
uniformity across SDK examples.
Summary by CodeRabbit
Documentation
New Features
Refactor