Safeguard Docs
Safeguard AI SDKs

Conversations

Create, continue, list and read back Safeguard AI conversations with the SDKs.

Conversations

A conversation is a thread of prompts and answers owned by the key's member. It also shows in that member's Safeguard AI history in the web app.

ActionTypeScriptPythonGo
Create an empty conversationconversations.create({ title })conversations.create(title=...)CreateConversation(ctx, &opts)
Continue onequery(p, { conversationId })query(p, conversation_id=...)Query(ctx, p, &QueryOptions{ConversationID: id})
List, newest activity firstconversations.list({ limit, offset })conversations.list(limit=, offset=)ListConversations(ctx, ListOptions{...})
Every conversationconversations.listAll()conversations.iter_all()EachConversation(ctx, size, fn) or Conversations(ctx)
One conversationconversations.get(id)conversations.get(id)GetConversation(ctx, id)
Stored historyconversations.messages(id)conversations.messages(id)ListMessages(ctx, id, opts)

A query without a conversation id creates a new conversation, titled from the prompt, and returns its id. Lists take limit from 1 to 100 and an offset. History comes back oldest first, one entry per turn with prompt and answer.

TypeScript

import { Safeguard } from "@safeguard-sh/sdk";

const client = new Safeguard();

// Create an empty conversation, then ask into it.
const conv = await client.conversations.create({ title: "SDK docs check" });
await client.query("What does CVSS stand for?", { conversationId: conv.id });

// Read it back: the conversation, then its stored turns (oldest first).
const one = await client.conversations.get(conv.id);
console.log(one.title, one.messageCount);
const turns = await client.conversations.messages(conv.id, { limit: 10 });
for (const m of turns.messages) console.log(`Q: ${m.prompt}\nA: ${m.answer.slice(0, 80)}`);

// Page through every conversation.
let n = 0;
for await (const c of client.conversations.listAll({ pageSize: 50 })) n++;
console.log(`${n} conversations in total`);

Python

from safeguard_sdk import Safeguard

client = Safeguard()

# Create an empty conversation, then ask into it.
conv = client.conversations.create(title="SDK docs check")
client.query("What does CVSS stand for?", conversation_id=conv.id)

# Read it back: the conversation, then its stored turns (oldest first).
one = client.conversations.get(conv.id)
print(one.title, one.message_count)
turns = client.conversations.messages(conv.id, limit=10)
for m in turns.messages:
    print(f"Q: {m.prompt}\nA: {m.answer[:80]}")

# Page through every conversation.
n = sum(1 for _ in client.conversations.iter_all(page_size=50))
print(f"{n} conversations in total")

Go

package main

import (
	"context"
	"fmt"
	"log"

	safeguard "safeguard.sh/sdk"
)

func main() {
	ctx := context.Background()
	client, err := safeguard.NewClient()
	if err != nil {
		log.Fatal(err)
	}

	// Create an empty conversation, then ask into it.
	conv, err := client.CreateConversation(ctx, &safeguard.CreateConversationOptions{Title: "SDK docs check"})
	if err != nil {
		log.Fatal(err)
	}
	if _, err := client.Query(ctx, "What does CVSS stand for?", &safeguard.QueryOptions{ConversationID: conv.ID}); err != nil {
		log.Fatal(err)
	}

	// Read it back: the conversation, then its stored turns (oldest first).
	one, err := client.GetConversation(ctx, conv.ID)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(one.Title, one.MessageCount)
	turns, err := client.ListMessages(ctx, conv.ID, safeguard.ListOptions{Limit: 10})
	if err != nil {
		log.Fatal(err)
	}
	for _, m := range turns.Messages {
		answer := m.Answer
		if len(answer) > 80 {
			answer = answer[:80]
		}
		fmt.Printf("Q: %s\nA: %s\n", m.Prompt, answer)
	}

	// Page through every conversation.
	n := 0
	err = client.EachConversation(ctx, 50, func(safeguard.Conversation) error {
		n++
		return nil
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%d conversations in total\n", n)
}

Example output (shortened):

SDK docs check 1
Q: What does CVSS stand for?
A: CVSS stands for **Common Vulnerability Scoring System**.
10 conversations in total

messageCount is a count kept by the service and can lag a moment behind a turn that just finished. A conversation id that does not exist, or that is not the key owner's, answers 404 NOT_FOUND before any turn runs.

On this page