Graph API

The Graph API is the primary interface for reading from bRRAIn. Every Retrieve call consults the full graph — semantic embeddings, full-text index, and POPE relationships — to produce context-aware results.

Retrieve method signature

func (w *Workspace) Retrieve(q sdk.Query) ([]sdk.Result, error)

Query type

type Query struct {
    Search       string            // Free-text or natural-language query
    Filters      map[string]any    // Structured filters (see below)
    Types        []string          // Record types to include
    Classifications []Classification // public/internal/confidential/restricted
    Limit        int               // Default 20, max 500
    Cursor       string            // Pagination token returned from prior call
    Sort         SortSpec          // Ranking overrides
    Expand       []string          // Expand linked entities inline
}

Result type

type Result struct {
    ID        string             // Record ID
    Data      map[string]any     // The original stored record
    Context   map[string]string  // Metadata from Store
    Score     float64            // 0.0 – 1.0 relevance
    Snippets  []string           // Highlighted excerpts
    Entities  []GraphEntity      // POPE entities linked to this record
    Relations []GraphRelation    // Graph edges this record participates in
}

Semantic search

The simplest query — just pass a natural-language Search:

results, _ := ws.Retrieve(sdk.Query{
    Search: "patients with elevated blood pressure in Q1",
    Limit:  10,
})

The Handler maps the query to an embedding and finds nearest neighbors, then re-ranks with graph signals.

Graph traversal

Follow relationships explicitly:

results, _ := ws.Retrieve(sdk.Query{
    Filters: map[string]any{
        "linked_to.person.email": "alice@firm.io",
        "relation":                "authored",
    },
})

Supported relation types: authored, reviewed, about, mentions, owns, member_of, participated_in, plus any custom relationships defined in your ontology.

Filters

Structured filters combine with Search:

sdk.Query{
    Search: "hedge strategy",
    Filters: map[string]any{
        "type":           "report",
        "classification": "internal",
        "created_after":  "2026-01-01",
        "tags":           []string{"Q1", "finance"},
    },
}

Filter values support operators:

• map[string]any{"created_at": sdk.Gte("2026-01-01")}
• map[string]any{"amount": sdk.Between(1000, 5000)}
• map[string]any{"status": sdk.In("draft", "pending")}

Sorting

Default sort is by computed relevance. Override when needed:

sdk.Query{
    Search: "latest contracts",
    Sort: sdk.SortSpec{
        Field:     "created_at",
        Direction: sdk.Descending,
    },
}

You may sort on: created_at, updated_at, score, size, or any indexed field.

Pagination

Pass Cursor from the previous response to continue:

first, _ := ws.Retrieve(sdk.Query{Search: "invoices", Limit: 100})
next, _ := ws.Retrieve(sdk.Query{Search: "invoices", Limit: 100, Cursor: first.NextCursor})

Cursors are stable for 24 hours. Prefer cursor pagination over offset-based for workspaces above 10K records.

Response format

The on-wire JSON mirrors the Go types:

{
    "results": [
        {
            "id": "rec_lh3f...",
            "data": { "type": "report", "title": "Q1 Portfolio Summary" },
            "context": { "classification": "internal" },
            "score": 0.94,
            "snippets": ["...hedge <em>strategy</em> for Q1 2026..."],
            "entities": [
                { "type": "person", "id": "alice", "role": "author" }
            ],
            "relations": [
                { "type": "about", "target": "project:portfolio-2026" }
            ]
        }
    ],
    "next_cursor": "eyJvZmZzZXQi..."
}

Advanced examples

Find decisions informed by a given learning

results, _ := ws.Retrieve(sdk.Query{
    Filters: map[string]any{
        "type":            "key_decision",
        "informed_by.id":  "learning:lr_112",
    },
})

Hybrid search with boosted types

results, _ := ws.Retrieve(sdk.Query{
    Search: "revenue recognition",
    Types:  []string{"contract", "memo"},
    Sort: sdk.SortSpec{
        Boost: map[string]float64{
            "contract": 1.5,
            "memo":     0.8,
        },
    },
})

Expand linked entities inline

results, _ := ws.Retrieve(sdk.Query{
    Search:  "board meetings 2026",
    Expand:  []string{"attendees", "decisions"},
})

Expand trades extra round trips for a single larger response — useful for rendering dashboards.