edge-completions

An ergonomic, typed Rust SDK and optional command-line client for OpenAI-compatible chat completions through Cloudflare. The first supported convenience model is moonshotai/kimi-k3.

This is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Cloudflare, Inc. Cloudflare is a trademark of Cloudflare, Inc.

Why this crate

• A small, object-safe ChatCompletions trait for application boundaries.
• A sealed typestate request builder that rejects illegal construction sequences at compile time.
• Validated newtypes for account IDs, API tokens, models, URLs, timeouts, and limits.
• Typed tool schemas, arguments, and results without a public untyped JSON escape hatch.
• thiserror errors for configuration, transport, provider, response, and tool failures.
• Redacted token debug output and bounded response-body decoding.
• An opt-in edge-completions command that prints typed assistant text and never prints provider envelopes.
• No autonomous tool loop: your application retains authorization and execution control.

Install

Add the library:

cargo add edge-completions

Install the optional command-line client:

cargo install edge-completions --features cli

The cli feature is intentionally disabled for library consumers, so SDK-only builds do not compile command-line dependencies. The minimum supported Rust version is 1.86.

Applications using the asynchronous examples also need Tokio. Typed tool definitions use Schemars and Serde:

cargo add tokio --features macros,rt-multi-thread
cargo add schemars
cargo add serde --features derive

Configuration

Create a scoped Cloudflare API token and set:

export CLOUDFLARE_ACCOUNT_ID="your_cloudflare_account_id"
export CLOUDFLARE_API_TOKEN="your_least_privilege_api_token"

Client::from_env() also accepts the original KIMI3_ON_CLOUDFLARE_API_KEY variable as a compatibility fallback. New applications should use CLOUDFLARE_API_TOKEN.

You can find the account ID in the Cloudflare dashboard after selecting your account, or follow Cloudflare's account and zone ID guide. Never commit either value.

Command line

Validate configuration without making an API request:

source ~/.zshrc
edge-completions check

Expected output:

configuration is valid

Send a prompt and print only the assistant's text:

edge-completions chat \
  --temperature 0.2 \
  --max-tokens 200 \
  "Explain typed API boundaries in one sentence."

Prompts can also come from standard input:

printf '%s\n' 'Explain capability traits concisely.' | edge-completions chat

Use edge-completions help chat for all chat options. The command returns typed, sanitized errors on standard error. It does not expose raw request or response envelopes and does not execute model-proposed tools. See the complete CLI reference, including exit codes and the base-URL security contract.

Library quickstart

use edge_completions::{AssistantOutput, ChatMessage, ChatRequest, Client, Error};

async fn answer() -> Result<(), Error> {
    let client = Client::from_env()?;
    let request = ChatRequest::kimi_k3_builder()
        .message(ChatMessage::user(
            "Explain typed API boundaries in one sentence.",
        ))
        .build();

    let completion = client.chat(&request).await?;
    let text = match completion.first_choice()?.message().output() {
        AssistantOutput::Text(text) => text,
        AssistantOutput::TextAndToolCalls { text, .. } => text,
        AssistantOutput::ToolCalls(_) | AssistantOutput::Empty => {
            return Err(Error::MissingContent);
        }
    };

    println!("{text}");
    Ok(())
}

Run the complete example:

source ~/.zshrc
cargo run --example simple_chat

Expected result: the example prints the model identifier followed by validated assistant text. It never prints the provider response envelope.

Typed tool calls

A tool contract ties together its generated JSON Schema, validated input type, and serializable output type:

use edge_completions::ToolDefinition;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

struct GetWeather;

#[derive(Deserialize, JsonSchema)]
struct WeatherArguments {
    city: String,
}

#[derive(Serialize)]
struct WeatherReport {
    temperature_celsius: i16,
}

impl ToolDefinition for GetWeather {
    type Arguments = WeatherArguments;
    type Output = WeatherReport;

    const NAME: &'static str = "get_weather";
    const DESCRIPTION: &'static str = "Get the weather for a city";
}

Decode a provider proposal only through the matching contract:

let call = completion.first_choice()?.message().first_tool_call()?;
let validated_call = call.validate::<GetWeather>()?;

// The application authorizes and executes the action here.
let report = get_weather(validated_call.arguments());
let result_message = validated_call.result(&report)?;

Run the complete two-turn example:

source ~/.zshrc
cargo run --example weather_tool

The example returns deterministic sample weather; it does not call a weather service or claim to provide a live forecast.

Output follows this shape. The final sentence depends on the model:

Tool requested: get_weather
Validated city: San Francisco
Final answer: ...

Compile-time composition

The typestate builder represents valid request states as types. Adding a message or tool consumes one state and returns the next, while trait bounds control which operations exist:

# use edge_completions::{ChatMessage, ChatRequest, FunctionTool, ToolChoice, ToolDefinition};
# use schemars::JsonSchema;
# use serde::{Deserialize, Serialize};
# struct GetWeather;
# #[derive(Deserialize, JsonSchema)] struct WeatherArguments { city: String }
# #[derive(Serialize)] struct WeatherReport { temperature_celsius: i16 }
# impl ToolDefinition for GetWeather {
#     type Arguments = WeatherArguments;
#     type Output = WeatherReport;
#     const NAME: &'static str = "get_weather";
#     const DESCRIPTION: &'static str = "Get the weather for a city";
# }
# fn request() -> Result<edge_completions::ChatRequest, edge_completions::ToolError> {
let request = ChatRequest::kimi_k3_builder()
    .message(ChatMessage::user("Weather in Paris?"))
    .tool(FunctionTool::for_tool::<GetWeather>()?)
    .tool_choice(ToolChoice::Required)
    .build();
# Ok(request)
# }

Calling build before message, or tool_choice before tool, does not compile. AssistantOutput models response alternatives as an exhaustive sum type, so callers must handle text, tool calls, text and tool calls, and empty output.

The same design has a small categorical interpretation: request states are objects, legal transitions are composable morphisms, and assistant output is a coproduct with a product branch. External network and model data still require typed runtime validation.

See the type-system guide for the complete state graph, compile-fail examples, and the boundary between static guarantees and runtime checks.

Migrating from 0.2

Version 0.3 is additive. Existing ChatRequest::new, ChatRequest::kimi_k3, with_tool, with_tools, and ToolCall::arguments_for calls remain available. New code should prefer these replacements:

No automatic migration is required. Adopt the new API when compile-time guarantees are useful at the call site.

Trait boundary

Application services can depend on behavior instead of the concrete HTTP client:

async fn answer(
    ai: &dyn edge_completions::ChatCompletions,
    request: &edge_completions::ChatRequest,
) -> Result<edge_completions::ChatCompletion, edge_completions::Error> {
    ai.complete(request).await
}

Keep the environment-based credential lookup while customizing the transport:

use edge_completions::{Client, GatewayId};

fn client() -> Result<Client, edge_completions::Error> {
    Client::builder_from_env()?
        .gateway_id(GatewayId::new("production-gateway")?)
        .build()
}

Features

Error and security model

• Every library failure is typed with thiserror; production code contains no unwrap, expect, or panic path.
• Local request cardinality and tool-choice sequencing are enforced by typestate; provider responses and model-produced tool calls are checked at runtime.
• ValidatedToolCall<T> is a proof-carrying value that binds decoded arguments and encoded output to the same ToolDefinition at compile time.
• API tokens use redacted Debug and are never included in errors.
• Success and failure bodies are size-bounded. Unknown error bodies are not exposed.
• Only HTTPS endpoints are accepted, except loopback HTTP for local tests.
• Tool names and arguments are model-controlled and remain untrusted until validate::<T>() produces a ValidatedToolCall<T> witness. The compatibility helper arguments_for::<T>() performs the same validation and returns the arguments.
• Tool execution is intentionally outside this crate.

A 402 Payment Required with Cloudflare code 2021 means the account or AI Gateway lacks usable Workers AI balance/provider billing. Add the required balance or configure BYOK before retrying the live examples.

Validation

cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-targets --all-features
cargo test --locked --doc --all-features
RUSTDOCFLAGS="-D warnings -D missing_docs" cargo doc --locked --no-deps --all-features
cargo deny check
cargo audit
cargo publish --locked --dry-run

Tests cover exact request serialization, public trait use, typed tool-call round trips, HTTP authentication, response validation, provider errors, response limits, TLS policy, and secret redaction against local servers. Tests do not make live provider calls.

Scope and limitations

• Supported now: non-streaming chat completions, typed function tools, Kimi K3 convenience construction, optional AI Gateway ID, timeout and body-size policy.
• Not supported yet: streaming, multimodal content, embeddings, Responses API, provider-specific raw extension maps, or autonomous tool execution.
• Provider contract drift remains possible. Contract changes should land with a versioned test before expanding the public API.

See the architecture, type-system guide, contributing guide, CLI reference, security policy, and release process.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.