stemedb/sdk/go/steme

StemeDB Go SDK

Go SDK for StemeDB - A probabilistic knowledge graph database.

Installation

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

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    // Generate a new keypair (or load from environment)
    signer, err := steme.GenerateSigner()
    if err != nil {
        log.Fatal(err)
    }

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

    // Create an assertion
    assertion := steme.NewAssertion("Tesla_Inc", "has_revenue").
        WithNumber(96.7).
        WithConfidence(0.95).
        WithLifecycle(steme.LifecycleApproved).
        WithSourceClass(steme.SourceClassClinical).
        WithSourceHash("0000000000000000000000000000000000000000000000000000000000000000").
        Build()

    // Submit to StemeDB (automatically signed)
    hash, err := client.Assert(context.Background(), assertion)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Created assertion: %s\n", hash)

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

    result, err := client.Query(context.Background(), params)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d assertions\n", result.TotalCount)
    for _, a := range result.Assertions {
        fmt.Printf("  %s: %v (confidence: %.2f)\n", a.Subject, a.Object.Value, a.Confidence)
    }
}

Features

1. Automatic Signing

The SDK automatically signs all assertions using Ed25519 cryptography. You don't need to think about keys, signatures, or timestamps.

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

// Assertion is automatically signed during Assert()
hash, _ := client.Assert(ctx, assertion)

2. Fluent API

Build assertions and queries with a clean, chainable API.

assertion := steme.NewAssertion("Semaglutide", "muscle_loss").
    WithText("significant").
    WithConfidence(0.85).
    WithLifecycle(steme.LifecycleApproved).
    WithSourceClass(steme.SourceClassClinical).
    WithSourceHash("...").
    Build()

params := steme.NewQuery().
    WithSubject("Semaglutide").
    WithPredicate("muscle_loss").
    WithLens(steme.LensConsensus).
    WithLimit(10).
    Build()

3. Type-Safe Enums

All StemeDB enums are type-safe Go constants.

// Lifecycle stages
steme.LifecycleProposed
steme.LifecycleUnderReview
steme.LifecycleApproved
steme.LifecycleDeprecated
steme.LifecycleRejected

// Source authority tiers
steme.SourceClassRegulatory  // Tier 0
steme.SourceClassClinical    // Tier 1
steme.SourceClassExpert      // Tier 3
steme.SourceClassAnecdotal   // Tier 5

// Lenses
steme.LensRecency
steme.LensConsensus
steme.LensAuthority
steme.LensVoteAwareConsensus
steme.LensTrustAwareAuthority

4. Context Support

All API calls support context.Context for cancellation and deadlines.

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

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

5. Skeptic Queries ("Trust but Verify")

See all competing claims instead of just the winner.

result, err := client.Skeptic(ctx, steme.SkepticQueryParams{
    Subject:   "Semaglutide",
    Predicate: "muscle_effect",
})

fmt.Printf("Status: %s, Conflict: %.2f\n", result.Status, result.ConflictScore)
for _, claim := range result.Claims {
    fmt.Printf("  %v (%.1f%% support, %d assertions)\n",
        claim.Value.Value,
        claim.WeightShare*100,
        claim.AssertionCount,
    )
}

Key Management

Generate New Keypair

signer, err := steme.GenerateSigner()
if err != nil {
    log.Fatal(err)
}

// Save for later
seed := signer.Seed() // Hex-encoded 32-byte seed
publicKey := signer.PublicKey() // Your agent_id

Load from Seed

signer, err := steme.NewSignerFromHex("your-hex-seed")
if err != nil {
    log.Fatal(err)
}

Load from Environment

signer, err := steme.SignerFromEnv("STEME_PRIVATE_KEY")
if err != nil {
    log.Fatal(err)
}

Object Values

StemeDB supports four value types.

// Text
assertion.WithText("hello world")

// Number
assertion.WithNumber(42.5)

// Boolean
assertion.WithBoolean(true)

// Reference (pointer to another entity)
assertion.WithReference("Other_Entity_Id")

Error Handling

The SDK uses typed errors for common failure modes.

hash, err := client.Assert(ctx, assertion)
if err != nil {
    switch e := err.(type) {
    case *steme.APIError:
        fmt.Printf("API error [%d]: %s\n", e.StatusCode, e.Message)
    case *steme.ValidationError:
        fmt.Printf("Validation failed on %s: %s\n", e.Field, e.Message)
    default:
        fmt.Printf("Error: %v\n", err)
    }
}

Testing

Run unit tests:

go test -v ./...

Run integration tests against a live server:

# Start the StemeDB API server
cargo run --bin stemedb-api

# Run integration tests
STEMEDB_URL=http://localhost:18180 go test -tags=integration -v ./...

See INTEGRATION_TESTS.md for detailed integration test documentation.

Examples

See the examples/ directory for complete examples:

• examples/basic/ - Simple assertion and query
• examples/skeptic/ - Trust-but-verify conflict analysis
• examples/batch/ - Batch assertion ingestion

License

MIT