`context.indices()` – Global Index API Reference¶

context.indices() returns a scope-aware ScopedIndices wrapper around the global SearchBackend.

It is the primary API for writing and retrieving text records (e.g., memory snippets, run events, artifacts) while automatically attaching and enforcing scope metadata.

What “scoped” means¶

Each ScopedIndices instance carries:

scope: a Scope object describing the active org/user/app/session/run/node context.
scope_id (optional): an extra logical partition key (commonly a memory_scope_id for memory-tied corpora).

Writes: automatic metadata¶

On upsert(), ScopedIndices merges your provided metadata with base scope labels (e.g. user/org/app/session/run/node identifiers) and drops keys whose values are None.

Reads: automatic filters¶

On search(), ScopedIndices automatically applies base scope filters (and optional scope_id), then merges in any user-provided filters (dropping None values).

Quickstart¶

Upsert a document¶

indices = context.indices()

await indices.upsert(
    corpus="artifact",
    item_id="artifact:123",
    text="Design review notes for v2 surrogate workflow...",
    metadata={"kind": "note", "tag": "surrogate"},
)

Search within a corpus¶

indices = context.indices()

items = await indices.search(
    corpus="artifact",
    query="surrogate workflow",
    top_k=10,
    filters={"tag": "surrogate"},
    time_window="7d",  # optional: interpreted as [now - 7d, now]
)

Convenience helpers¶

indices = context.indices()

events = await indices.search_events("error", top_k=20, time_window="24h")
artifacts = await indices.search_artifacts("invoice template", top_k=10)

Note: time_window is ignored if created_at_min is provided. You can also pass created_at_min / created_at_max as UNIX timestamps for precise control.

1. Upsert any text¶

upsert(*, corpus, item_id, text, metadata=None)

Upsert (insert or update) a text item with associated metadata into the backend index. This method merges base metadata with any provided metadata, strips out keys with None values, and delegates the upsert operation to the backend. This ensures that only meaningful metadata is stored and that None values are treated as wildcards by the backend.

Examples:

Basic usage to upsert a text item:

await service.upsert(
    corpus="my_corpus",
    item_id="item123",
    text="Sample document text."

Upserting with additional metadata:

await service.upsert(
    corpus="my_corpus",
    item_id="item123",
    text="Sample document text.",
    metadata={"author": "Alice", "category": "news"}

Args: corpus: The name of the corpus or collection to upsert the item into. item_id: The unique identifier for the item within the corpus. text: The text content to be indexed or updated. metadata: Optional mapping of additional metadata to associate with the item.

Returns:

Type	Description
`None`	None

Notes

Metadata keys with None values are omitted before upserting to the backend.

2. Search API¶

search(*, corpus, query, top_k=10, filters=None, time_window=None, created_at_min=None, created_at_max=None)

Perform a search operation on the specified corpus. This method executes a search query against the backend, applying optional filters, time constraints, and other parameters to refine the results.

Examples:

Basic usage to search a corpus:

results = await search(corpus="documents", query="machine learning")

Searching with additional filters and time constraints:

results = await search(
corpus="articles",
query="AI advancements",
top_k=5,
filters={"author": "John Doe"},
time_window="7d"

Parameters:

Name	Type	Description	Default
`corpus`	`str`	The name of the corpus to search within.	required
`query`	`str`	The search query string.	required
`top_k`	`int`	The maximum number of results to return (default: 10).	`10`
`filters`	`Mapping[str, Any] \| None`	Optional dictionary of additional filters to apply to the search.	`None`
`time_window`	`str \| None`	Optional human-friendly duration (e.g., "7d", "24h", "30m")	`None`
`created_at_min`	`float \| None`	Optional minimum UNIX timestamp (float) for filtering results by creation time.	`None`
`created_at_max`	`float \| None`	Optional maximum UNIX timestamp (float) for filtering results by creation time.	`None`
`level`	`ScopeLevel \| None`	Optional scope level to filter results by (e.g., "session", "run", "user", "org"). If provided, the search will be constrained to items associated with the specified scope level.	`None`

Returns:

Type	Description
`list[ScoredItem]`	A list of `ScoredItem` objects representing the search results.

Notes

If time_window is provided, it is used to calculate the time range unless created_at_min is explicitly set.
Filters with None values are automatically excluded from the search.

search_events(query, *, top_k=20, filters=None, time_window=None, created_at_min=None, created_at_max=None)

Perform a search for events based on the given query and optional filters.

This method queries the "event" corpus using the specified parameters to retrieve a list of scored items matching the search criteria.

Examples:

Basic usage to search for events:

results = await search_events("error logs")

Searching with additional filters and a time window:

results = await search_events(
"user activity",
top_k=10,
filters={"status": "active"},
time_window="last_24_hours",
created_at_min=1672531200.0,
created_at_max=1672617600.0

Parameters:

Name	Type	Description	Default
`query`	`str`	The search query string.	required
`top_k`	`int`	The maximum number of results to return (default: 20).	`20`
`filters`	`Mapping[str, Any] \| None`	Optional dictionary of filters to apply to the search.	`None`
`time_window`	`str \| None`	Optional time window for the search (e.g., "last_24_hours").	`None`
`created_at_min`	`float \| None`	Optional minimum creation timestamp for filtering results.	`None`
`created_at_max`	`float \| None`	Optional maximum creation timestamp for filtering results.	`None`
`level`	`ScopeLevel \| None`	Optional scope level to filter results by (e.g., "session", "run", "user", "org"). If provided, the search will be constrained to events associated with the specified scope level.	`None`

Returns:

Type	Description
`list[ScoredItem]`	A list of `ScoredItem` objects representing the search results.

Notes: - The filters parameter allows you to specify key-value pairs to narrow down the search results. - The time_window parameter can be used to specify a predefined time range for the search. - The created_at_min and created_at_max parameters allow for fine-grained control over the creation time range of the events being searched.

search_artifacts(query, *, top_k=20, filters=None, time_window=None, created_at_min=None, created_at_max=None)

Perform a search for artifacts based on the provided query and optional filters.

This method queries the "artifact" corpus using the specified parameters and returns a list of scored items matching the search criteria.

Examples:

Basic usage to search for artifacts:

results = await search_artifacts("example query")

Searching with additional filters and a time window:

results = await search_artifacts(
"example query",
top_k=10,
filters={"type": "document"},
time_window="last_7_days",
created_at_min=1672531200.0,
created_at_max=1672617600.0,

Parameters:

Name	Type	Description	Default
`query`	`str`	The search query string.	required
`top_k`	`int`	The maximum number of results to return (default: 20).	`20`
`filters`	`Mapping[str, Any] \| None`	Optional dictionary of filters to apply to the search.	`None`
`time_window`	`str \| None`	Optional time window for the search (e.g., "last_7_days").	`None`
`created_at_min`	`float \| None`	Optional minimum creation timestamp for filtering results.	`None`
`created_at_max`	`float \| None`	Optional maximum creation timestamp for filtering results.	`None`
`level`	`ScopeLevel \| None`	Optional scope level to filter results by (e.g., "session", "run", "user", "org"). If provided, the search will be constrained to artifacts associated with the specified scope level.	`None`

Returns:

Type	Description
`list[ScoredItem]`	A list of `ScoredItem` objects representing the search results.

Notes

The filters parameter allows specifying additional constraints for the search.
The time_window parameter can be used to limit results to a specific time range.
The created_at_min and created_at_max parameters allow filtering by creation time.

context.indices() – Global Index API Reference¶

What “scoped” means¶

Writes: automatic metadata¶

Reads: automatic filters¶

Quickstart¶

Upsert a document¶

Search within a corpus¶

Convenience helpers¶

1. Upsert any text¶

2. Search API¶

`context.indices()` – Global Index API Reference¶