fleet-memory/hindsight-clients/go/integration_test.go
Nicolò Boschi 9b96becc5c
feat: entity labels — optional, free_values, multi_value, UI polish (#450)
* feat: entity labels

* feat: entity labels — optional, free_values, multi_value, UI polish

Completes the entity labels system:

**Schema & extraction**
- Dynamic Pydantic Labels model per fact: each group becomes a typed
  field (Literal | None, list[Literal], str | None, or list[str])
- `optional: bool` flag per group — non-optional enum fields appear in
  JSON schema required array so structured-output providers enforce them
- `free_values: bool` flag per group — accepts any LLM-generated string
  instead of a predefined enum; example values shown as hints in prompt
- New `is_label_entity()` helper for labels-only mode filtering that
  handles both enum lookup and free_values key-prefix matching
- Sentinel rejection: "None"/"null"/"n/a" strings dropped in post-processing

**BM25 / dense retrieval**
- `text_signals` column on memory_units: entity names + date tokens for
  enriched BM25 indexing without polluting stored fact text
- Dense embedding includes occurred_end when it differs from occurred_start
- Alembic migration z1u2v3w4x5y6 (merge revision fixing two heads)

**UI (bank-config-view)**
- Shadcn Switch replaces custom Toggle for both entity-labels and observations
- Shadcn Checkbox for multi/optional/free_values per group
- Input heights bumped to h-8 throughout the editor
- "Label Groups" → "Entity Labels", "Free-form entities" → "Entities"
- Free-text groups show "Example hints" banner in values section

**Tests (45 unit + 3 LLM integration)**
- build_labels_model: single, multi, mixed, free_values optional/required/multi
- is_label_entity: enum match, free_values prefix match, no false positives
- Post-processing: null/absent/string-None/free_values/sentinels/multi-value
- Schema: labels in required, structured object, no labels when unconfigured
- LLM integration: single-value enum, multi-value enum, free_values retain

**Docs**
- retain.md: new Entity Labels section covering groups, flags, examples
- configuration.md: retain_free_form_entities env var + entity_labels note

* fix(tests): update hierarchical fields count for entity_labels additions

entity_labels and retain_free_form_entities are hierarchical fields,
bumping the expected count from 11 to 13.

* fix(migration): rename text_signals revision to avoid collision with main

Main branch claimed z1u2v3w4x5y6 for observation_scopes. Rename our
text_signals migration to a2b3c4d5e6f7, chaining after z1u2v3w4x5y6.

* refactor(entity-labels): simplify free_values — always str|None, no multi

- free_values groups always produce str | None (multi_value and optional
  flags are ignored for free text groups — always optional, never multi)
- Prompt section for free_values groups shows only key + description,
  no values list (users put examples in the description instead)
- UI: section title "Entities", toggle "Free Form Entities", replace
  per-group checkboxes with a type dropdown (Enum / Free text); only
  show multi checkbox and values list when type is Enum
- Update tests to reflect new behaviour

* refactor(entity-labels): replace free_values/multi_value booleans with type field

- LabelGroup now uses type: "value" | "multi-values" | "text" instead of
  free_values/multi_value boolean pair
- Backward-compat migration converts legacy dicts automatically
- Rename retain_free_form_entities → entities_allow_free_form throughout
- Update UI dropdown to show Single value / Multi-values / Free text
- Remove separate multi checkbox (captured by type selection)
- Update docs examples and configuration.md
- Update all tests to use new field names

* fix(migration): backfill observation_scopes column for DBs with swapped z1u2v3w4x5y6

Local DBs that had z1u2v3w4x5y6 applied when it referred to the old
text_signals migration (before it was renamed to a2b3c4d5e6f7) won't have
observation_scopes in their memory_units table. This migration adds the
column with IF NOT EXISTS so it's a no-op on clean installs.

* feat(entity-labels): add tag field to auto-populate memory unit tags from labels

When a LabelGroup has tag=True, extracted key:value entities for that group
are automatically written to the memory unit's tags array. This lets entity
labels double as tags, enabling immediate filtering via the existing
tags/tags_match API params with no extra infrastructure.

- Add tag: bool = False to LabelGroup
- _inject_label_tags() helper called in both sync and batch extraction paths
- UI: add Tag checkbox per label group row
- Docs: document the new tag field
- Tests: 4 new unit tests covering all tag injection paths

* style: ruff format migration file

* fix(migration): fix multiple alembic heads after rebase — point text_signals after nullable_event_date

* fix(clients): update timestamp field to use Timestamp wrapper type after timestamp=unset feature

* style: ruff format agent.py

* fix(docs): update Go quickstart example to use NullableTimestamp for timestamp field
2026-03-02 13:05:25 +01:00

479 lines
11 KiB
Go

//go:build integration
package hindsight
import (
"context"
"fmt"
"os"
"testing"
"time"
)
func apiURL(t *testing.T) string {
t.Helper()
u := os.Getenv("HINDSIGHT_API_URL")
if u == "" {
u = "http://localhost:8888"
}
return u
}
func newClient(t *testing.T) *APIClient {
t.Helper()
cfg := NewConfiguration()
cfg.Servers = ServerConfigurations{
{URL: apiURL(t)},
}
return NewAPIClient(cfg)
}
func uniqueBank(t *testing.T) string {
t.Helper()
return fmt.Sprintf("go_test_%d", time.Now().UnixNano())
}
// --- Retain tests ---
func TestRetainSingle(t *testing.T) {
client := newClient(t)
ctx := context.Background()
bankID := uniqueBank(t)
req := RetainRequest{
Items: []MemoryItem{
{Content: "Alice loves artificial intelligence and machine learning"},
},
}
resp, httpResp, err := client.MemoryAPI.RetainMemories(ctx, bankID).RetainRequest(req).Execute()
if err != nil {
t.Fatal(err)
}
defer httpResp.Body.Close()
if !resp.GetSuccess() {
t.Error("expected success=true")
}
}
func TestRetainWithContext(t *testing.T) {
client := newClient(t)
ctx := context.Background()
bankID := uniqueBank(t)
timestamp := time.Date(2024, 1, 15, 10, 30, 0, 0, time.UTC)
req := RetainRequest{
Items: []MemoryItem{
{
Content: "Bob went hiking in the mountains",
Timestamp: *NewNullableTimestamp(&Timestamp{TimeTime: &timestamp}),
Context: *NewNullableString(PtrString("outdoor activities")),
},
},
}
resp, httpResp, err := client.MemoryAPI.RetainMemories(ctx, bankID).RetainRequest(req).Execute()
if err != nil {
t.Fatal(err)
}
defer httpResp.Body.Close()
if !resp.GetSuccess() {
t.Error("expected success=true")
}
}
func TestRetainBatch(t *testing.T) {
client := newClient(t)
ctx := context.Background()
bankID := uniqueBank(t)
req := RetainRequest{
Items: []MemoryItem{
{Content: "Charlie enjoys reading science fiction books"},
{Content: "Diana is learning to play the guitar"},
{Content: "Eve completed a marathon last month"},
},
}
resp, httpResp, err := client.MemoryAPI.RetainMemories(ctx, bankID).RetainRequest(req).Execute()
if err != nil {
t.Fatal(err)
}
defer httpResp.Body.Close()
if !resp.GetSuccess() {
t.Error("expected success=true")
}
if resp.GetItemsCount() != 3 {
t.Errorf("expected items_count=3, got %d", resp.GetItemsCount())
}
}
func TestRetainWithTags(t *testing.T) {
client := newClient(t)
ctx := context.Background()
bankID := uniqueBank(t)
req := RetainRequest{
Items: []MemoryItem{
{
Content: "New feature implementation for project Z",
Tags: []string{"project_z", "features"},
},
},
}
resp, httpResp, err := client.MemoryAPI.RetainMemories(ctx, bankID).RetainRequest(req).Execute()
if err != nil {
t.Fatal(err)
}
defer httpResp.Body.Close()
if !resp.GetSuccess() {
t.Error("expected success=true")
}
}
func TestRetainBatchWithDocumentTags(t *testing.T) {
client := newClient(t)
ctx := context.Background()
bankID := uniqueBank(t)
req := RetainRequest{
Items: []MemoryItem{
{Content: "Document with tags test 1"},
{Content: "Document with tags test 2"},
},
DocumentTags: []string{"test_doc", "batch"},
}
resp, httpResp, err := client.MemoryAPI.RetainMemories(ctx, bankID).RetainRequest(req).Execute()
if err != nil {
t.Fatal(err)
}
defer httpResp.Body.Close()
if !resp.GetSuccess() {
t.Error("expected success=true")
}
}
// --- Recall tests ---
func setupRecallBank(t *testing.T, client *APIClient, bankID string) {
t.Helper()
ctx := context.Background()
req := RetainRequest{
Items: []MemoryItem{
{Content: "Alice enjoys hiking in the mountains"},
{Content: "Bob loves to read science fiction novels"},
{Content: "Charlie is learning to play the piano"},
},
}
_, _, err := client.MemoryAPI.RetainMemories(ctx, bankID).RetainRequest(req).Execute()
if err != nil {
t.Fatal(err)
}
// Give the system time to process
time.Sleep(time.Second)
}
func TestRecallBasic(t *testing.T) {
client := newClient(t)
ctx := context.Background()
bankID := uniqueBank(t)
setupRecallBank(t, client, bankID)
req := RecallRequest{
Query: "outdoor activities",
}
resp, httpResp, err := client.MemoryAPI.RecallMemories(ctx, bankID).RecallRequest(req).Execute()
if err != nil {
t.Fatal(err)
}
defer httpResp.Body.Close()
if resp.Results == nil {
t.Error("expected results, got nil")
}
}
func TestRecallWithMaxTokens(t *testing.T) {
client := newClient(t)
ctx := context.Background()
bankID := uniqueBank(t)
setupRecallBank(t, client, bankID)
req := RecallRequest{
Query: "outdoor activities",
MaxTokens: PtrInt32(1024),
}
resp, httpResp, err := client.MemoryAPI.RecallMemories(ctx, bankID).RecallRequest(req).Execute()
if err != nil {
t.Fatal(err)
}
defer httpResp.Body.Close()
if resp.Results == nil {
t.Error("expected results, got nil")
}
}
func TestRecallFullFeatured(t *testing.T) {
client := newClient(t)
ctx := context.Background()
bankID := uniqueBank(t)
setupRecallBank(t, client, bankID)
req := RecallRequest{
Query: "What are people's hobbies?",
Types: []string{"world"},
MaxTokens: PtrInt32(2048),
Trace: PtrBool(true),
}
resp, httpResp, err := client.MemoryAPI.RecallMemories(ctx, bankID).RecallRequest(req).Execute()
if err != nil {
t.Fatal(err)
}
defer httpResp.Body.Close()
if resp.Results == nil {
t.Error("expected results, got nil")
}
// Verify trace data is present
if resp.Trace != nil && len(resp.Trace) > 0 {
t.Logf("✓ Trace data received with %d keys", len(resp.Trace))
}
}
// --- Reflect tests ---
func setupReflectBank(t *testing.T, client *APIClient, bankID string) {
t.Helper()
ctx := context.Background()
// Create bank with mission
createReq := CreateBankRequest{
Mission: *NewNullableString(PtrString("I am a helpful AI assistant interested in technology and science.")),
}
_, _, err := client.BanksAPI.CreateOrUpdateBank(ctx, bankID).CreateBankRequest(createReq).Execute()
if err != nil {
t.Fatal(err)
}
// Add memories
retainReq := RetainRequest{
Items: []MemoryItem{
{Content: "Quantum computing uses quantum bits (qubits) for processing"},
{Content: "Neural networks are inspired by biological neurons"},
},
}
_, _, err = client.MemoryAPI.RetainMemories(ctx, bankID).RetainRequest(retainReq).Execute()
if err != nil {
t.Fatal(err)
}
time.Sleep(time.Second)
}
func TestReflectBasic(t *testing.T) {
client := newClient(t)
ctx := context.Background()
bankID := uniqueBank(t)
setupReflectBank(t, client, bankID)
req := ReflectRequest{
Query: "What do you know about computing?",
}
resp, httpResp, err := client.MemoryAPI.Reflect(ctx, bankID).ReflectRequest(req).Execute()
if err != nil {
t.Fatal(err)
}
defer httpResp.Body.Close()
if resp.GetText() == "" {
t.Error("expected non-empty answer")
}
}
func TestReflectWithMaxTokens(t *testing.T) {
client := newClient(t)
ctx := context.Background()
bankID := uniqueBank(t)
setupReflectBank(t, client, bankID)
req := ReflectRequest{
Query: "Tell me about neural networks",
MaxTokens: PtrInt32(500),
}
resp, httpResp, err := client.MemoryAPI.Reflect(ctx, bankID).ReflectRequest(req).Execute()
if err != nil {
t.Fatal(err)
}
defer httpResp.Body.Close()
if resp.GetText() == "" {
t.Error("expected non-empty answer")
}
}
// --- Bank tests ---
func TestCreateBank(t *testing.T) {
client := newClient(t)
ctx := context.Background()
bankID := uniqueBank(t)
req := CreateBankRequest{
Mission: *NewNullableString(PtrString("Test mission")),
}
resp, httpResp, err := client.BanksAPI.CreateOrUpdateBank(ctx, bankID).CreateBankRequest(req).Execute()
if err != nil {
t.Fatal(err)
}
defer httpResp.Body.Close()
if resp.GetBankId() != bankID {
t.Errorf("expected bank_id=%s, got %s", bankID, resp.GetBankId())
}
}
func TestSetMission(t *testing.T) {
client := newClient(t)
ctx := context.Background()
bankID := uniqueBank(t)
// Create bank with initial mission
createReq := CreateBankRequest{
Mission: *NewNullableString(PtrString("Initial mission")),
}
_, _, err := client.BanksAPI.CreateOrUpdateBank(ctx, bankID).CreateBankRequest(createReq).Execute()
if err != nil {
t.Fatal(err)
}
// Update mission by creating/updating bank again
updateReq := CreateBankRequest{
Mission: *NewNullableString(PtrString("Updated mission")),
}
resp, httpResp, err := client.BanksAPI.CreateOrUpdateBank(ctx, bankID).CreateBankRequest(updateReq).Execute()
if err != nil {
t.Fatal(err)
}
defer httpResp.Body.Close()
if resp.GetMission() != "Updated mission" {
t.Errorf("expected mission='Updated mission', got %s", resp.GetMission())
}
}
func TestListBanks(t *testing.T) {
client := newClient(t)
ctx := context.Background()
resp, httpResp, err := client.BanksAPI.ListBanks(ctx).Execute()
if err != nil {
t.Fatal(err)
}
defer httpResp.Body.Close()
if resp.Banks == nil {
t.Error("expected banks list, got nil")
}
}
func TestDeleteBank(t *testing.T) {
client := newClient(t)
ctx := context.Background()
bankID := uniqueBank(t)
// Create bank
createReq := CreateBankRequest{}
_, _, err := client.BanksAPI.CreateOrUpdateBank(ctx, bankID).CreateBankRequest(createReq).Execute()
if err != nil {
t.Fatal(err)
}
// Delete bank
resp, httpResp, err := client.BanksAPI.DeleteBank(ctx, bankID).Execute()
if err != nil {
t.Fatal(err)
}
defer httpResp.Body.Close()
if !resp.GetSuccess() {
t.Error("expected success=true")
}
}
// --- End-to-end workflow test ---
func TestCompleteWorkflow(t *testing.T) {
client := newClient(t)
ctx := context.Background()
bankID := uniqueBank(t)
// 1. Create bank
createReq := CreateBankRequest{
Mission: *NewNullableString(PtrString("I am a helpful assistant")),
}
_, _, err := client.BanksAPI.CreateOrUpdateBank(ctx, bankID).CreateBankRequest(createReq).Execute()
if err != nil {
t.Fatal(err)
}
// 2. Retain memories
retainReq := RetainRequest{
Items: []MemoryItem{
{Content: "Paris is the capital of France"},
{Content: "The Eiffel Tower is in Paris"},
},
}
retainResp, _, err := client.MemoryAPI.RetainMemories(ctx, bankID).RetainRequest(retainReq).Execute()
if err != nil {
t.Fatal(err)
}
if !retainResp.GetSuccess() {
t.Error("retain failed")
}
time.Sleep(time.Second)
// 3. Recall
recallReq := RecallRequest{
Query: "What is in Paris?",
}
recallResp, _, err := client.MemoryAPI.RecallMemories(ctx, bankID).RecallRequest(recallReq).Execute()
if err != nil {
t.Fatal(err)
}
if len(recallResp.Results) == 0 {
t.Error("expected recall results")
}
// 4. Reflect
reflectReq := ReflectRequest{
Query: "Tell me about Paris",
}
reflectResp, _, err := client.MemoryAPI.Reflect(ctx, bankID).ReflectRequest(reflectReq).Execute()
if err != nil {
t.Fatal(err)
}
if reflectResp.GetText() == "" {
t.Error("expected reflect answer")
}
t.Log("✓ Complete workflow passed")
}