Profile Management

search_user_profiles

Search for user profiles using semantic queries.

response = client.search_user_profiles(
    user_id="user_123",
    query="laptop preferences",
    threshold=0.7,
    top_k=5
)

rerank_user_profiles

Rerank a list of candidate profile IDs by query relevance using a CPU cross-encoder. Use after search_user_profiles (or any other source of candidate IDs) when initial results are noisy. The server fetches each candidate's full content (scoped to user_id), scores (query, content) pairs, and returns the top_k profiles sorted by descending score. IDs that don't resolve for the user are silently dropped.

response = client.rerank_user_profiles(
    user_id="user_123",
    query="laptop preferences",
    profile_ids=["prof_1", "prof_2", "prof_3"],
    top_k=5,
)

Returns: SearchProfilesViewResponse with success, user_profiles (sorted by descending cross-encoder score, capped at top_k), and msg.

storage_stats

Get a lightweight count of how many profiles and playbooks a user has, plus the modified-time range across every status. Useful for sizing top_k before retrieval.

stats = client.storage_stats(user_id="user_123")
print(stats.profile_count, stats.playbook_count)

get_profiles

Retrieve user profiles.

response = client.get_profiles(
    user_id="user_123",
    top_k=10
)

get_all_profiles

Get profiles across all users (admin operation).

response = client.get_all_profiles(limit=100)

Returns: GetUserProfilesResponse with profiles from all users

Example:

# Get profiles from all users
all_profiles = client.get_all_profiles(limit=50)

# Group by user
from collections import defaultdict
by_user = defaultdict(list)

for profile in all_profiles.user_profiles:
    by_user[profile.user_id].append(profile)

for user_id, profiles in by_user.items():
    print(f"User {user_id}: {len(profiles)} profiles")
    for p in profiles[:3]:  # Show first 3
        print(f"  - {p.content[:50]}...")

add_user_profile

Add user profiles directly to storage, bypassing the inference pipeline. Useful for seeding known facts (testing, migration, manual injection). The server populates the embedding automatically.

response = client.add_user_profile(
    user_profiles=[
        {"user_id": "user_123", "content": "Prefers concise responses"},
    ]
)

delete_profile

Delete user profiles by ID or search query.

response = client.delete_profile(
    user_id,
    profile_id="",
    search_query="",
    wait_for_response=False
)

get_profile_change_log

Retrieve the history of profile changes.

logs = client.get_profile_change_log()

Bulk Delete Operations

delete_profiles_by_ids

Delete multiple profiles by their IDs.

response = client.delete_profiles_by_ids(profile_ids=["prof_1", "prof_2"])

Returns: BulkDeleteResponse with success, deleted_count, and message

delete_all_profiles

Delete all profiles.

response = client.delete_all_profiles()

Returns: BulkDeleteResponse with success, deleted_count, and message