tkmind/tkmind_go
1
0
Fork 0
Code Issues Pull Requests Actions 34 Packages Projects Releases Wiki Activity

docs: add SDK API reference for Rust, Python, and Kotlin (#11251)

Browse Source
This commit is contained in:
Alex Hancock
2026-08-24 20:07:29 +00:00
committed by GitHub
parent 4db9e21b98
commit f9ac24cbfc
33 changed files with 2606 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/docs/gdk/_category_.json
+8
View File
@@ -0,0 +1,8 @@
{
"label": "GDK",
"position": 3,
"link": {
"type": "doc",
"id": "gdk/index"
}
}
documentation/docs/gdk/api-reference.mdx
+18
View File
@@ -0,0 +1,18 @@
---
sidebar_position: 2
title: API Reference
sidebar_label: API Reference
description: Complete goose GDK API reference for Rust, Python, and Kotlin.
---
import GdkApiReference from '@site/src/components/GdkApiReference';
# API Reference
The complete GDK surface. Use the toggles to switch language and GDK
version — names and types are shown using each language's own conventions.
New to the GDK? Start with the [GDK overview](/docs/gdk) for installation and
runnable examples.
<GdkApiReference />
documentation/docs/gdk/index.md
+239
View File
@@ -0,0 +1,239 @@
---
sidebar_position: 1
title: GDK Overview
sidebar_label: Overview
description: Build with goose providers in Rust, Python, and Kotlin.
---
# GDK
The goose Development Kit (GDK) exposes goose's provider layer as a library so you
can call models, stream completions, and compact conversations from your own
application.
One Rust crate, `goose-sdk`, is the source of every language binding. Python and
Kotlin are generated from it with [UniFFI](https://github.com/mozilla/uniffi-rs),
so all three languages share the same types, behavior, and version number.
See the [API Reference](/docs/gdk/api-reference) for the complete surface in your
language of choice.
:::info Alpha
The GDK is in alpha. The surface may change between `0.x` releases. Pin an exact
version and check the API reference version selector when upgrading.
:::
## What you can do
- Construct providers for OpenAI, Anthropic, Groq, Databricks, or any
[declarative provider](#declarative-providers) defined in JSON
- Stream a completion chunk by chunk, including tool calls and reasoning output
- Request a single non-streaming completion
- Compact a long conversation into a summary so it can continue past the
model's context window
- Capture provider request logs as JSONL
## Install
<!-- prettier-ignore-start -->
### Rust
```bash
cargo add goose-sdk
```
By default the crate re-exports the Agent Client Protocol (ACP) wire types for
talking to `goose acp` over stdio. Enable the `uniffi` feature for the
in-process provider API documented in the reference:
```bash
cargo add goose-sdk --features uniffi
```
### Python
```bash
pip install goose-sdk
```
The package installs as `goose-sdk` and imports as `goose`. Wheels bundle the
native library, so there is nothing else to build. Requires Python 3.9+.
```python
import goose
```
### Kotlin / JVM
```kotlin
dependencies {
implementation("io.github.aaif-goose:gdk:<version>")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
}
```
The artifact version matches the Rust crate version. Classes live in the
`io.github.aaif_goose` package. The jar bundles native libraries for
macOS (arm64, x86-64), Linux (arm64, x86-64), and Windows (x86-64).
On JDK 24+, add `--enable-native-access=ALL-UNNAMED` because the GDK loads its
native library through JNA.
<!-- prettier-ignore-end -->
## Quickstart
Each example builds a provider, sends one message, and prints the streamed
response.
### Python
```python
import asyncio
from goose import (
MessageContent,
MessageRole,
ProviderMessage,
ProviderModelConfig,
StreamChunk,
openai_default_model,
openai_provider,
)
async def main() -> None:
provider = openai_provider(api_key="...")
model = ProviderModelConfig(model_name=openai_default_model())
messages = [
ProviderMessage(
role=MessageRole.USER,
content=[MessageContent.Text(text="What is the capital of France?")],
)
]
stream = await provider.stream(model, "You are a geography expert.", messages, [])
while chunk := await stream.next_chunk():
if isinstance(chunk, StreamChunk.TextChunk):
print(chunk.text, end="")
asyncio.run(main())
```
### Kotlin
```kotlin
import io.github.aaif_goose.MessageContent
import io.github.aaif_goose.MessageRole
import io.github.aaif_goose.ProviderMessage
import io.github.aaif_goose.ProviderModelConfig
import io.github.aaif_goose.StreamChunk
import io.github.aaif_goose.streamFlow
import io.github.aaif_goose.providers.openai.defaultModel
import io.github.aaif_goose.providers.openai.provider as openAiProvider
import kotlinx.coroutines.runBlocking
fun main() = runBlocking {
val provider = openAiProvider(System.getenv("OPENAI_API_KEY"))
val model = ProviderModelConfig(modelName = defaultModel())
val messages = listOf(
ProviderMessage(
role = MessageRole.USER,
content = listOf(MessageContent.Text(text = "What is the capital of France?")),
),
)
provider.streamFlow(model, "You are a geography expert.", messages)
.collect { chunk ->
if (chunk is StreamChunk.TextChunk) print(chunk.text)
}
}
```
### Rust
```rust
use goose_sdk::bindings::{
openai_default_model, openai_provider, MessageContent, MessageRole, ProviderMessage,
ProviderModelConfig, StreamChunk,
};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let provider = openai_provider(std::env::var("OPENAI_API_KEY")?)?;
let model = ProviderModelConfig {
model_name: openai_default_model(),
..Default::default()
};
let messages = vec![ProviderMessage {
role: MessageRole::User,
content: vec![MessageContent::Text {
text: "What is the capital of France?".to_string(),
}],
}];
let stream = provider
.stream(model, "You are a geography expert.".to_string(), messages, vec![])
.await?;
while let Some(chunk) = stream.next_chunk().await? {
if let StreamChunk::TextChunk { text } = chunk {
print!("{text}");
}
}
Ok(())
}
```
## Kotlin idioms
The Kotlin package adds a few conveniences on top of the generated bindings:
| Kotlin API | Equivalent generated call |
| --- | --- |
| `provider.streamFlow(model, system, messages, tools)` | `stream(...)` plus a `nextChunk()` loop, as a `Flow<StreamChunk>` |
| `providers.openai.provider(apiKey)` | `openaiProvider(apiKey)` |
| `providers.openai.defaultModel()` | `openaiDefaultModel()` |
| `providers.anthropic.provider(apiKey, baseUrl, betaHeaders)` | `anthropicProvider(...)` |
| `providers.groq.provider(apiKey)` | `groqProvider(apiKey)` |
| `providers.databricks.provider(host, token)` | `databricksProvider(host, token)` |
`tools` defaults to an empty list in the Kotlin helpers, and suspending
functions map to Kotlin coroutines. Errors surface as `GooseException`
subclasses.
## Declarative providers
Any provider that speaks an OpenAI- or Anthropic-compatible API can be defined
in JSON and loaded without new Rust code:
```python
provider = goose.declarative_provider_from_json(open("deepseek.json").read())
```
Environment variable placeholders such as `${DEEPSEEK_API_KEY}` in the JSON are
resolved when the provider is constructed.
## Streaming model
`stream()` returns a `ProviderStream`. Call `next_chunk()` until it returns
`None` to consume the response:
| Chunk | Meaning |
| --- | --- |
| `TextChunk` | Assistant text |
| `ToolChunk` | A tool call request with JSON arguments |
| `ThinkingChunk` / `RedactedThinkingChunk` | Reasoning output |
| `EndChunk` | Stream finished, carries final token `Usage` |
| `ErrorChunk` | Mid-stream failure, carries a `GooseStreamError` |
Errors raised before the stream starts are thrown as `GooseError`
(`GooseException` in Kotlin). Errors that occur mid-stream arrive as an
`ErrorChunk` instead.
## Next steps
- [API Reference](/docs/gdk/api-reference) — every function, type, and error
- [goose in ACP clients](/docs/guides/acp-clients) — drive the full goose agent
over the Agent Client Protocol