ClimateClaw Client Documentation#

A Python client library for interacting with the ClimateClaw backend. This library provides both synchronous and asynchronous interfaces for communicating with a ClimateClaw chatbot instance.

Contents:

Quickstart#

Install the package from source:

git clone https://github.com/freva-org/climateclaw-client.git
cd climateclaw-client
pip install -e .

Or using uv:

uv pip install -e .

Basic Usage Example#

from climateclaw_client.client import ClimateClaw

# Create a client instance
cc = ClimateClaw(
    base_url="https://your-climate-claw-backend.com",
    token_store_path="~/.cache/climateclaw-client/token-store.json",
)

# Authenticate with the backend
cc.authenticate()

# List available models
print(f"Available models: {cc.available_models}")

# Send a prompt
conversation = cc.prompt("Please calculate the average temperature over Germany for 1990-2020!")

# Access messages
for message in conversation.messages:
    print(f"{message.variant}: {message.content}")

Streaming Example#

# Send a prompt with streaming enabled
stream_conv = cc.prompt("Please explain the ENSO phenomenon to me!", stream=True)

# Iterate over markdown chunks as they arrive
with stream_conv as stream:
    for markdown_chunk in stream.iter_for_markdown():
        print(markdown_chunk)

Asynchronous Client Example#

import asyncio
from climate_claw_cc.client import AsyncClimateClaw


async def main():
    # Create an async client instance
    client = AsyncClimateClaw(
        base_url="https://your-climate-claw-backend.com",
        token_store_path="~/.cache/climateclaw-client/token-store.json",
    )

    # Authenticate with the backend
    await cc.authenticate()

    # List available models
    print(f"Available models: {cc.available_models}")
    cc.model = cc.available_models[0]

    # Send a prompt
    response = await cc.prompt(
        "Please calculate the average temperature over Germany for 1990-2020!"
    )
    print(response)

    # Thread management works the same way
    thread_id = await cc.newthread()
    response = await cc.prompt(
        "Please explain how the SOI can be calculated.",
        thread_id=thread_id,
    )


asyncio.run(main())

Thread Management Example#

# Create a new conversation thread
thread_id = cc.newthread()

# Continue a conversation in an existing thread
response = cc.prompt("Please explain how the SOI can be calculated.", thread_id=thread_id)

# List all your conversation threads
total_threads, user_threads = cc.getuserthreads(num_threads=10)
print(f"A total number of {total_threads} threads was retrieved.")
# access individual threads (which are Conversation objects)
print(user_threads[0])

# Search for threads by topic
total_results, matching_threads = cc.searchthreads(query="climate analysis", num_threads=5)

# Set a topic for a thread (useful for searching later)
cc.setthreadtopic("ENSO analysis", thread_id=thread_id)

# Delete a thread when you're done with it
cc.deletethread(thread_id=thread_id)

Features#

  • Synchronous client (ClimateClaw) with full API support

  • Asynchronous client (AsyncClimateClaw) with full API support

  • OIDC authentication via py-oidc-auth-client

  • Thread management: create, retrieve, list, search, fork, and delete conversation threads

  • Streaming and non-streaming prompt responses

  • Thread operations: stop active conversations, set thread topics, edit/fork threads

  • User feedback: submit positive/negative feedback on assistant messages

  • Rich message types with markdown rendering support

  • Message variants: Prompt, User, Assistant, Code, CodeOutput, Image, ServerError, OpenAIError, CodeError, StreamEnd, ServerHint

Indices and Tables#