Documentation

Semantic Search

Search images and documents using natural language queries with AI-powered understanding

How It Works

Semantic search uses AI to understand the meaning of your query, not just keywords. "Damaged equipment" will find images described as "broken machinery" even if those exact words aren't used. The system iteratively refines results for accuracy.

Multiple embeddings are used under the hood: visual embeddings for image similarity search, and text embeddings for document and description search.

Tip: More Token-Efficient Than Chat

Standalone search agents are the most token-efficient way to search your data. If you don't need multi-turn conversation, use these endpoints directly instead of agentic chat to save on token usage.

Image Search

Search Your Image Library

from aion import AionVision

async with AionVision(api_key="aion_...") as client:
    result = await client.agent_search.images("damaged utility poles")

    print(f"Found {result.count} images")
    print(f"Summary: {result.summary}")

    for img in result.results[:5]:
        print(f"- {img.filename}: score={img.score:.2f}")
        print(f"  Description: {img.description[:100]}...")

Document Search

Search Across Documents

result = await client.agent_search.documents("safety inspection procedures")

print(f"Summary: {result.summary}")
print(f"Documents searched: {len(result.document_ids)}")

for chunk in result.results:
    print(f"\n{chunk.document_filename} (page {chunk.page_numbers}):")
    print(f"  Score: {chunk.score:.2f}")
    print(f"  Text: {chunk.text[:200]}...")

Simple Chunk Search

Faster, simpler document search without AI reasoning

results = await client.documents.search(
    query="safety inspection requirements",
    limit=20,
    similarity_threshold=0.3
)

for chunk in results.results:
    print(f"{chunk.document_filename}: {chunk.content[:200]}...")

Filtering Results

Filter by Folder

result = await client.agent_search.images(
    "corrosion or rust damage",
    folder_id="fld_abc123",
    limit=20
)

Search Specific Images

result = await client.agent_search.images(
    "equipment with visible damage",
    image_ids=["img_001", "img_002", "img_003"]
)
matching_ids = result.result_ids

Filter by Document Type

result = await client.agent_search.documents(
    "maintenance schedules",
    document_types=["pdf"],
    limit=25
)

Using Result Refs for UI

SDK only — build interactive interfaces with result references

result = await client.agent_search.images("vehicles in parking lot")

# The summary contains [[ref:N]] patterns you can make clickable
print(result.summary)
# "Found 3 vehicles: a red sedan [[ref:1]], a blue truck [[ref:2]]..."

# Map refs to actual results for click handling
for ref_key, ref in result.result_refs.items():
    print(f"[[ref:{ref_key}]] -> {ref.ids}")
    # ref.count: number of items
    # ref.ids: ["img_abc123", ...]
    # ref.id_type: "image"
    # ref.label: "3 vehicles"

Response Types

ImageSearchAgentResult

@dataclass(frozen=True)
class ImageSearchAgentResult:
    success: bool
    results: list[ImageSearchResultItem]       # Full image objects
    count: int                                 # Total matches
    result_ids: list[str]                      # Flat list of image IDs
    summary: str                               # Human-readable summary
    summary_raw: str                           # Original with [[ref:X]] patterns
    result_refs: dict[str, ResultRefData]      # For UI ref linking
    execution_time_ms: int
    iterations: int

DocumentSearchAgentResult

@dataclass(frozen=True)
class DocumentSearchAgentResult:
    success: bool
    results: list[DocumentChunkResultItem]     # Matching chunks
    count: int                                 # Total chunk matches
    chunk_ids: list[str]
    document_ids: list[str]                    # Unique documents found
    summary: str                               # Human-readable summary
    summary_raw: str                           # Original with [[ref:X]] patterns
    result_refs: dict[str, ResultRefData]      # For UI ref linking
    search_mode: str                           # Search strategy used
    execution_time_ms: int
    iterations: int

Writing Effective Queries

Be descriptive, not keyword-focused

✓ "Photos showing water damage on ceiling tiles"
✗ "water damage ceiling"

Include context

✓ "Construction workers without proper safety equipment"
✗ "safety violation"

Use natural language

✓ "Show me all the images from the March site inspection"
✗ "date:march type:inspection"