Bivia Rust API Library

The Bivia Rust library provides convenient access to the Bivia REST API from applications written in Rust.

Installation

cargo add bivia
cargo add tokio --features full

Or add it to your Cargo.toml:

[dependencies]
bivia = "1.0"
tokio = { version = "1", features = ["full"] }

Requirements

This library requires Rust 2021 edition or later and an async runtime such as Tokio.

Usage

use bivia::{Client, types::BooleanParams};

#[tokio::main]
async fn main() -> Result<(), bivia::BiviaError> {
    let client = Client::new()?; // reads A8_API_KEY from the environment

    let categorical_decision = client
        .decisions()
        .boolean(BooleanParams {
            question: "Is this urgent?".into(),
            state: Some("Customer threatened to cancel today.".into()),
            ..Default::default()
        })
        .await?;

    println!("{:?}", categorical_decision.evidence);
    Ok(())
}

Client::new() reads your API key from the A8_API_KEY environment variable, so the key is not stored in source control.

Request & Response types

Every endpoint has a typed params struct in bivia::types (for example BooleanParams, ChoiceParams, ScoreParams) and returns a typed response (CategoricalDecision, ScoreDecision, SetDecision, and so on). All params structs implement Default, so set the fields you need and finish with ..Default::default().

Method	Endpoint
client.decisions().create(DecideParams)	POST /decide
client.decisions().boolean(BooleanParams)	POST /boolean
client.decisions().choice(ChoiceParams)	POST /choice
client.decisions().score(ScoreParams)	POST /score
client.decisions().multi_select(SetParams)	POST /set
client.decisions().span(SpanParams)	POST /span
client.grounding().image(GroundParams)	POST /ground
client.data().decide(DataDecisionParams)	POST /ds
client.batch().create(BatchParams)	POST /v1/systemone
client.models().list()	GET /v1/models
client.models().capabilities()	GET /capabilities

Configuring the client

Use Client::builder() to set the API key, base URL, timeout, or retries explicitly:

use bivia::Client;
use std::time::Duration;

let client = Client::builder()
    .api_key("My API Key") // defaults to the A8_API_KEY environment variable
    .base_url("https://api.articul8.ai/bivia")
    .timeout(Duration::from_secs(60))
    .max_retries(3)
    .build();

Errors

When the API returns a non-success status code, the call returns BiviaError::Api, which contains the HTTP status, the error message, and the raw response body.

use bivia::{BiviaError, types::BooleanParams};

match client
    .decisions()
    .boolean(BooleanParams {
        question: "Is this urgent?".into(),
        state: Some("Customer threatened to cancel today.".into()),
        ..Default::default()
    })
    .await
{
    Ok(decision) => println!("{:?}", decision.value),
    Err(BiviaError::Api { status, message, .. }) => eprintln!("{status}: {message}"),
    Err(err) => eprintln!("{err}"),
}

Other errors are returned as:

Error	Cause
BiviaError::Connection	A network or connection error
BiviaError::Serialization	A request or response could not be (de)serialized
BiviaError::MissingApiKey	A8_API_KEY is not set and no key was passed to the builder

Retries

Certain errors are automatically retried 2 times by default. Connection errors, 429 Rate Limit, and >=500 Internal errors are retried.

You can use the max_retries option to configure or disable this:

let client = Client::builder()
    .max_retries(0) // default is 2
    .build();

Timeouts

Requests time out after 60 seconds by default. You can configure this with the timeout option:

use std::time::Duration;

let client = Client::builder()
    .timeout(Duration::from_secs(20)) // default is 60 seconds
    .build();

Semantic versioning

This package generally follows SemVer conventions, though certain backwards-incompatible changes may be released as minor versions:

1. Changes to library internals which are technically public but not intended or documented for external use. (Please open a GitHub issue to let us know if you are relying on such internals.)
2. Changes that we do not expect to impact the vast majority of users in practice.

We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.

We are keen for your feedback; please open an issue with questions, bugs, or suggestions.

Contributing

See the contributing documentation.