Skip to main content

​
Overview

The Retrieval class provides methods for querying documents using natural language. It leverages embedded documents to perform semantic search and return relevant information.

​
Methods

​
query(data: RetrievalRequest)

Post a retrieval request in natural language to search through embedded documents.
​
data
RetrievalRequest
required
The retrieval query parameters
​
response
tuple
Returns a tuple of (RetrievalResponse | Error, status_code)
Example: 
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}")

​
How Retrieval Works

The retrieval system works by:
  1. Embedding documents: Documents are embedded using vector embeddings
  2. Semantic search: Your natural language query is embedded and compared against document embeddings
  3. Response generation: The most relevant documents are used to generate a natural language response

​
Prerequisites

Before using the retrieval API, ensure you have:
  1. Created documents using the Document API
  2. Embedded those documents (either during creation or using the embed() method)

​
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)

# Step 1: Create and embed documents
documents = [
    DocumentInsert(
        doc_id="temp_001",
        text="On May 3rd at 1:00 PM, the temperature was 24°C.",
        embed=True
    ),
    DocumentInsert(
        doc_id="temp_002",
        text="On May 3rd at 2:00 PM, the temperature rose to 26°C.",
        embed=True
    ),
    DocumentInsert(
        doc_id="temp_003",
        text="On May 4th at 1:00 PM, the temperature was 22°C.",
        embed=True
    )
]

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

# Step 2: 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}")

​
Use Cases

The Retrieval API is ideal for: 
retrieval = RetrievalRequest(
    query="How do I configure the air conditioner for optimal energy efficiency?"
)

res, status = eca.retrieval.query(data=retrieval)
print(res.response)

​
Historical Data Queries

retrieval = RetrievalRequest(
    query="What were the occupancy levels last Tuesday afternoon?"
)

res, status = eca.retrieval.query(data=retrieval)
print(res.response)

​
Troubleshooting Assistance

retrieval = RetrievalRequest(
    query="Why is the air quality index showing high values?"
)

res, status = eca.retrieval.query(data=retrieval)
print(res.response)

​
Best Practices

  1. Document Quality: Ensure documents contain clear, well-structured information
  2. Regular Updates: Keep documents up-to-date with the latest information
  3. Specific Queries: More specific queries tend to return more accurate responses
  4. Embedding Strategy: Embed documents as they’re created for real-time retrieval

​
Creating Effective Documents

# Good: Structured, specific information
good_doc = DocumentInsert(
    doc_id="hvac_guide_001",
    text="""Air Conditioner Maintenance Schedule:
    - Monthly: Clean or replace air filters
    - Quarterly: Check refrigerant levels
    - Annually: Professional inspection
    Optimal temperature setting: 22-24°C for energy efficiency.""",
    embed=True
)

# Less effective: Vague, unstructured
bad_doc = DocumentInsert(
    doc_id="hvac_guide_002",
    text="You should maintain your AC sometimes. Check things.",
    embed=True
)

​
Integration with Other APIs

You can create documents from ESS or Sequences to enable retrieval on your state data: 
# Create document from an ESS
doc_res, doc_status = eca.document.create_from_ess(
    module_id="air_conditioner",
    ess_id=8
)

# Embed it for retrieval
embed_res, embed_status = eca.document.embed(db_id=doc_res.id)

# Now you can query it
retrieval = RetrievalRequest(
    query="What was the air conditioner state?"
)

res, status = eca.retrieval.query(data=retrieval)
print(res.response)

Build docs developers (and LLMs) love

Get started for freeTalk to us