Retrieval

Query documents using natural language

The Retrieval API enables natural language querying over embedded documents, providing a semantic search interface.

Retrieval Models

RetrievalRequest

Used to submit natural language queries:

from avenieca.api.model import RetrievalRequest

retrieval = RetrievalRequest(
    query="what is the temperature on 3rd of may at around 1pm?"
)

RetrievalResponse

Returned with the query result:

@dataclass
class RetrievalResponse(Base):
    response: str  # Natural language response

Retrieval Methods

query()

Submit a natural language query:

from avenieca.api.model import RetrievalRequest

retrieval = RetrievalRequest(
    query="what is the temperature on 3rd of may at around 1pm?"
)

res, status = eca.retrieval.query(data=retrieval)
if status == 200:
    print(f"Response: {res.response}")

Complete Example

import os
from avenieca.api.eca import ECA
from avenieca.api.model import Config, DocumentInsert, RetrievalRequest

# Initialize client
config = Config(
    uri="http://localhost:2580/v1",
    username=os.getenv("USERNAME"),
    password=os.getenv("PASSWORD")
)
eca = ECA(config)

# First, create and embed some documents
documents = [
    DocumentInsert(
        doc_id="weather_001",
        text="The temperature on May 3rd at 1pm was 28 degrees Celsius.",
        embed=True
    ),
    DocumentInsert(
        doc_id="weather_002",
        text="On May 3rd at 2pm, the temperature dropped to 25 degrees.",
        embed=True
    ),
    DocumentInsert(
        doc_id="weather_003",
        text="May 4th saw temperatures of 30 degrees at noon.",
        embed=True
    )
]

for doc in documents:
    res, status = eca.document.create(data=doc)
    print(f"Created document: {res.doc_id}")

# Now query the documents
retrieval = RetrievalRequest(
    query="what is the temperature on 3rd of may at around 1pm?"
)

res, status = eca.retrieval.query(data=retrieval)
if status == 200:
    print(f"\nQuery: {retrieval.query}")
    print(f"Response: {res.response}")
else:
    print(f"Error: {res}")

# Try another query
retrieval2 = RetrievalRequest(
    query="what was the temperature on may 4th?"
)

res, status = eca.retrieval.query(data=retrieval2)
if status == 200:
    print(f"\nQuery: {retrieval2.query}")
    print(f"Response: {res.response}")

How Retrieval Works

1. Document Embedding - Documents are embedded when created with embed=True or via document.embed()
2. Query Embedding - Your natural language query is embedded using the same model
3. Semantic Search - The system finds documents with similar embeddings
4. Response Generation - A natural language response is generated from relevant documents

Requirements

For retrieval to work effectively:

• Documents must be embedded before querying
• Use clear, specific queries
• Ensure documents contain relevant information
• The embedding model must be properly configured

Example Queries

from avenieca.api.model import RetrievalRequest

# Specific fact queries
query1 = RetrievalRequest(query="what is the temperature on May 3rd?")

# Time-based queries
query2 = RetrievalRequest(query="what happened at 1pm?")

# Comparative queries
query3 = RetrievalRequest(query="when was it hottest?")

# Aggregate queries
query4 = RetrievalRequest(query="what were the temperature trends?")

for query in [query1, query2, query3, query4]:
    res, status = eca.retrieval.query(data=query)
    if status == 200:
        print(f"Q: {query.query}")
        print(f"A: {res.response}\n")

Use Cases

• Question answering - Answer questions about stored documents
• Information retrieval - Find relevant information semantically
• Context search - Search through ESS and sequence contexts
• Knowledge base queries - Query organizational knowledge

Best Practices

• Embed documents promptly - Embed documents as soon as they’re created
• Use descriptive text - Write clear, detailed document text
• Specific queries - More specific queries yield better results
• Batch document creation - Create multiple related documents for comprehensive coverage
• Update embeddings - Re-embed documents after updates