dapr / dapr/js-sdk

feat(conversation): Conversation API alpha2

Open
#804 0 comments 0 reactions 0 assignees View on GitHub
area/conversation enhancement sdk-parity
Dominant language
JavaScript
Stars
217
Forks
104
PR merge metrics
No merged PRs in 30d

Description

## Description

The Dapr runtime exposes a `ConverseAlpha2` gRPC method (and corresponding HTTP endpoint `POST /v1.0-alpha2/conversation/{name}/converse`) that replaces the now-deprecated Alpha1 Conversation API. The JS SDK should add first-class support for this new API surface.

The proto definitions (`src/proto/dapr/proto/runtime/v1/ai.proto`) and generated bindings are already present in the repository, but no high-level client method is exposed.

## Background

Alpha2 is a significant redesign over Alpha1. Key differences:

| Feature | Alpha1 (deprecated) | Alpha2 |
|---------|---------------------|--------|
| Input format | Flat `string content` + optional `role` | Structured typed messages (`developer`, `system`, `user`, `assistant`, `tool`) via `ConversationMessage` oneof |
| Tool support | None | `ConversationTools` with function definitions, `tool_choice`, tool call results in responses |
| Response format | Simple `string result` | `ConversationResultAlpha2` with `choices[]`, `finish_reason`, `tool_calls`, `model`, token `usage` stats |
| Structured output | None | `response_format` (JSON Schema via `google.protobuf.Struct`) |
| Prompt caching | None | `prompt_cache_retention` (`google.protobuf.Duration`) |
| Token usage | None | `CompletionUsage` with completion/prompt token breakdowns |

## Scope

1. **TypeScript types** (`src/types/conversation/`) — User-facing interfaces for:
- `ConversationRequestAlpha2` (name, contextId, inputs, metadata, temperature, scrubPii, tools, toolChoice, responseFormat, promptCacheRetention)
- `ConversationInputAlpha2` (messages, scrubPii)
- `ConversationMessage` — discriminated union for developer/system/user/assistant/tool message types
- `ConversationMessageContent` (text)
- `ConversationTools` / `ConversationToolsFunction` — function tool definitions with JSON Schema parameters
- `ConversationToolCalls` / `ConversationToolCallsOfFunction` — tool call results from LLM
- `ConversationResponseAlpha2` (contextId, outputs)
- `ConversationResultAlpha2` (choices, model, usage)
- `ConversationResultChoices` (finishReason, index, message)
- `ConversationResultMessage` (content, toolCalls)
- Usage types (completionTokens, promptTokens, totalTokens, details breakdowns)

2. **Client interface** (`src/interfaces/Client/IClientConversation.ts`) — e.g.:
```ts
converse(request: ConversationRequestAlpha2): Promise
```
3. gRPC imlpementation (`src/implementation/Client/GRPCClient/conversation.ts`) — Map user-facing types ↔ proto schemas, call `client.converseAlpha2()`
4. HTTP implementation (`src/implementation/Client/HTTPClient/conversation.ts`) — `POST /v1.0-alpha2/conversation/{name}/converse`
5. DaprClient integration — Add `conversation` property to `DaprClient`
6. Exports — Export all new types/interfaces from `src/index.ts`
7. Tests — Unit tests for type mapping; E2E test if a conversation component is available in testcontainers

## Target Usage
```ts
const response = await client.conversation.converse({
name: "my-llm",
inputs: [{
messages: [
{ ofUser: { content: [{ text: "What is Dapr?" }] } }
]
}],
tools: [{
function: { name: "search", description: "Search the docs", parameters: { type: "object", properties: {} } }
}],
toolChoice: "auto",
temperature: 0.7,
});

// response.outputs[0].choices[0].message.content
// response.outputs[0].choices[0].message.toolCalls
// response.outputs[0].choices[0].finishReason
// response.outputs[0].usage.totalTokens
```

## References
- Proto source: `src/proto/dapr/proto/runtime/v1/ai.proto` (messages) + `dapr.proto` line 252 (rpc definition)
- ConnectRPC binding: `src/proto/dapr/proto/runtime/v1/dapr_connect.{js,d.ts}` — `ConverseAlpha2` service method
- OpenAI reference: [openai-go chatcompletion.go](https://github.com/openai/openai-go/blob/main/chatcompletion.go)
- Dapr runtime API docs for Conversation Alpha2

## Acceptance Criteria
- [ ] `DaprClient` exposes a `conversation.converse()` method for both gRPC and HTTP protocols
- [ ] All Alpha2 proto fields are represented in user-facing TypeScript types
- [ ] Tool calling round-trip works (send tools → receive tool_calls → send tool results)
- [ ] Deprecated Alpha1 types/methods are NOT added
- [ ] Unit tests cover type mapping between user types and proto schemas
- [ ] Types are exported from the package index

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.