stemedb/docs/sdk/README.md

SDK Documentation

Client libraries and integration guides for Episteme (StemeDB).

---

Go SDK

The official Go client library provides type-safe access to the Episteme API with built-in Ed25519 signing.

Quick Start

go get github.com/orchard9/stemedb-go/steme

import "github.com/orchard9/stemedb-go/steme"

// Generate keypair
signer, _ := steme.GenerateSigner()

// Create client
client := steme.NewClient("http://localhost:18180", signer)

// Assert a fact
assertion := steme.NewAssertion("Tesla_Inc", "has_revenue").
    WithNumber(96.7).
    WithConfidence(0.95).
    Build()

hash, _ := client.Assert(ctx, assertion)

// Query with conflict resolution
params := steme.NewQuery().
    WithSubject("Tesla_Inc").
    WithPredicate("has_revenue").
    WithLens(steme.LensConsensus).
    Build()

result, _ := client.Query(ctx, params)

Documentation

• Go SDK Reference - Complete API documentation
• Usage Guide - Patterns and examples
• ADK-Go Integration - Building AI agents

---

Features

Fluent Builders

The SDK provides fluent builders for readable, type-safe API calls:

// Assertions
assertion := steme.NewAssertion(subject, predicate).
    WithString(value).
    WithConfidence(0.9).
    WithSourceHash(hash).
    WithLifecycle("Approved").
    Build()

// Queries
params := steme.NewQuery().
    WithSubject("Semaglutide").
    WithPredicate("has_side_effect").
    WithLens(steme.LensSkeptic).
    WithAsOf(timestamp).
    Build()

// Votes
vote := steme.NewVote(assertionHash).
    WithWeight(0.8).
    Build()

Automatic Signing

All assertions are automatically signed with Ed25519:

signer, _ := steme.GenerateSigner()
client := steme.NewClient(endpoint, signer)

// Every assertion includes:
// - Timestamp
// - Agent public key
// - Ed25519 signature

Lens Support

Query with different conflict resolution strategies:

// Most recent wins
steme.LensRecency

// Weighted consensus
steme.LensConsensus

// Vote-aware resolution
steme.LensVoteAware

// Surface disagreement
steme.LensSkeptic

// Per-tier breakdown
steme.LensLayered

// Trust-aware authority
steme.LensTrustAware

// Epoch-aware filtering
steme.LensEpochAware

---

AI Agent Integration

ADK-Go Tools

The SDK integrates with Google ADK-Go for building AI agents:

// Define tools for agents
func QueryKnowledge(ctx context.Context, subject, predicate string, lens string) (string, error) {
    resp, err := episteme.Query(ctx, &QueryParams{
        Subject:   subject,
        Predicate: predicate,
        Lens:      lens,
    })
    if err != nil {
        return "", err
    }
    return formatForAgent(resp), nil
}

func AssertFact(ctx context.Context, subject, predicate, object string) error {
    return episteme.Assert(ctx, &AssertionRequest{
        Subject:    subject,
        Predicate:  predicate,
        Object:     ObjectText(object),
        Confidence: 0.9,
    })
}

→ Full ADK-Go Guide

---

Examples

Basic Workflow

package main

import (
    "context"
    "github.com/orchard9/stemedb-go/steme"
)

func main() {
    ctx := context.Background()

    // Initialize
    signer, _ := steme.GenerateSigner()
    client := steme.NewClient("http://localhost:18180", signer)

    // Write
    assertion := steme.NewAssertion("GLP1_Agonists", "cardiovascular_benefit").
        WithBoolean(true).
        WithConfidence(0.85).
        Build()

    hash, _ := client.Assert(ctx, assertion)

    // Read
    params := steme.NewQuery().
        WithSubject("GLP1_Agonists").
        WithPredicate("cardiovascular_benefit").
        WithLens(steme.LensConsensus).
        Build()

    result, _ := client.Query(ctx, params)
    // result.Winner.Object contains the resolved value
}

Conflict Handling

// Create competing claims
client1.Assert(ctx, steme.NewAssertion("Drug_X", "safety_profile").
    WithString("safe").
    WithConfidence(0.7).
    Build())

client2.Assert(ctx, steme.NewAssertion("Drug_X", "safety_profile").
    WithString("unsafe").
    WithConfidence(0.6).
    Build())

// Query with Skeptic lens to see disagreement
params := steme.NewQuery().
    WithSubject("Drug_X").
    WithPredicate("safety_profile").
    WithLens(steme.LensSkeptic).
    Build()

result, _ := client.Query(ctx, params)
// result.Status: "Contested"
// result.ConflictScore: 0.72
// result.Claims: [{value: "safe", ...}, {value: "unsafe", ...}]

Time Travel

// Query historical state
pastTime := time.Now().Add(-24 * time.Hour)

params := steme.NewQuery().
    WithSubject("Bitcoin").
    WithPredicate("price_usd").
    WithAsOf(pastTime).
    Build()

result, _ := client.Query(ctx, params)
// Returns what was believed 24 hours ago

---

Error Handling

The SDK returns typed errors:

hash, err := client.Assert(ctx, assertion)
if err != nil {
    switch err.(type) {
    case *steme.ValidationError:
        // Invalid assertion structure
    case *steme.SignatureError:
        // Signing failed
    case *steme.NetworkError:
        // Connection issues
    case *steme.QuotaExceededError:
        // Rate limited
    default:
        // Other errors
    }
}

---

Configuration

Client Options

client := steme.NewClient(endpoint, signer,
    steme.WithTimeout(30*time.Second),
    steme.WithRetry(3),
    steme.WithUserAgent("MyApp/1.0"),
)

Environment Variables

Variable	Default	Description
STEMEDB_ENDPOINT	http://localhost:18180	API endpoint
STEMEDB_TIMEOUT	30s	Request timeout
STEMEDB_RETRY_COUNT	3	Retry attempts

---

Testing

Mock Client

The SDK provides a mock for testing:

import "github.com/orchard9/stemedb-go/steme/mock"

func TestMyCode(t *testing.T) {
    mockClient := mock.NewClient()

    // Configure expected calls
    mockClient.ExpectAssert(assertion).Return(hash, nil)
    mockClient.ExpectQuery(params).Return(result, nil)

    // Run your code
    myFunction(mockClient)

    // Verify expectations
    mockClient.AssertExpectations(t)
}

---

Performance

Batching

// Batch assertions
batch := steme.NewBatch()
batch.Add(assertion1)
batch.Add(assertion2)
batch.Add(assertion3)

hashes, err := client.SubmitBatch(ctx, batch)

Connection Pooling

The client automatically manages connection pooling:

// Reuse the client across requests
var globalClient *steme.Client

func init() {
    signer, _ := steme.GenerateSigner()
    globalClient = steme.NewClient(endpoint, signer)
}

---

Migration Guide

From Direct HTTP

Before:

// Manual HTTP + signing
body := marshal(assertion)
signature := sign(privateKey, body)
req := http.NewRequest("POST", endpoint+"/v1/assert", bytes.NewReader(body))
req.Header.Set("X-Signature", signature)
resp, _ := http.DefaultClient.Do(req)

After:

// SDK handles it all
hash, _ := client.Assert(ctx, assertion)

---

Resources

• API Reference - HTTP API documentation
• Architecture - System design
• Use Cases - Real-world examples
• ADK-Go Examples - Agent patterns

---

Support

• GitHub Issues: Report bugs or request features
• Examples: See sdk/go/examples/ directory
• Integration Help: Check ADK-Go Integration

---

← Back to Documentation Index