Documentation Index
Fetch the complete documentation index at: https://mintlify.com/aveni-hub/avenieca-python/llms.txt
Use this file to discover all available pages before exploring further.
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
- Document Embedding - Documents are embedded when created with
embed=True or via document.embed()
- Query Embedding - Your natural language query is embedded using the same model
- Semantic Search - The system finds documents with similar embeddings
- 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