Documents

Manage documents in AveniECA

The Document API allows you to store, retrieve, and embed text documents for use with retrieval and other features.

Document Models

DocumentInsert

Used to create or update documents:

from avenieca.api.model import DocumentInsert

document = DocumentInsert(
    doc_id="001",          # Required: Document identifier
    text="testing 123",    # Required: Document text
    embed=True             # Optional: Auto-embed flag (default: False)
)

DocumentResponse

Returned when retrieving documents:

@dataclass
class DocumentResponse(Base):
    id: int           # Database ID
    doc_id: str       # Document identifier
    text: str         # Document text
    status: str       # Processing status
    created_at: str   # Creation timestamp
    updated_at: str   # Last update timestamp

Document Methods

create()

Create a new document:

from avenieca.api.model import DocumentInsert

document = DocumentInsert(
    doc_id="001",
    text="testing 123",
    embed=True
)

res, status = eca.document.create(data=document)
if status == 201:
    print(f"Created document with ID: {res.id}")
    print(f"Status: {res.status}")

get_all()

Retrieve all documents:

res, status = eca.document.get_all()
if status == 200:
    for doc in res:
        print(f"Document {doc.doc_id}: {doc.text[:50]}...")

get_one()

Get a specific document by database ID:

res, status = eca.document.get_one(db_id=20)
if status == 200:
    print(f"Doc ID: {res.doc_id}")
    print(f"Text: {res.text}")
    print(f"Status: {res.status}")

update()

Update an existing document:

from avenieca.api.model import DocumentInsert

updated_doc = DocumentInsert(
    doc_id="001",
    text="updated content",
    embed=False
)

res, status = eca.document.update(db_id=20, data=updated_doc)
if status == 200:
    print(f"Updated document {res.id}")

delete()

Delete a document:

res, status = eca.document.delete(db_id=100)
if status == 200:
    print("Document deleted successfully")

embed()

Embed an existing document:

res, status = eca.document.embed(db_id=20)
if status == 200:
    print(f"Document embedded: {res.status}")

create_from_ess()

Create a document from an existing ESS entry:

res, status = eca.document.create_from_ess(
    module_id="air_conditioner",
    ess_id=5
)
if status == 201:
    print(f"Created document from ESS: {res.id}")

create_from_sequence()

Create a document from an existing sequence:

res, status = eca.document.create_from_sequence(
    module_id="air_conditioner",
    sequence_id=3
)
if status == 201:
    print(f"Created document from sequence: {res.id}")

Complete Example

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

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

# Create a document with auto-embedding
document = DocumentInsert(
    doc_id="weather_001",
    text="The temperature on May 3rd at 1pm was 28 degrees Celsius.",
    embed=True
)

res, status = eca.document.create(data=document)
if status == 201:
    doc_id = res.id
    print(f"Created document {doc_id}")
    print(f"Status: {res.status}")
    
    # Get the document
    res, status = eca.document.get_one(db_id=doc_id)
    print(f"Retrieved: {res.text}")
    
    # Update the document
    updated = DocumentInsert(
        doc_id="weather_001",
        text="The temperature on May 3rd at 1pm was 29 degrees Celsius.",
        embed=False
    )
    res, status = eca.document.update(db_id=doc_id, data=updated)
    print(f"Updated: {res.text}")
    
    # Re-embed after update
    res, status = eca.document.embed(db_id=doc_id)
    print(f"Re-embedded: {res.status}")
    
    # Get all documents
    res, status = eca.document.get_all()
    print(f"Total documents: {len(res)}")

Document Status

Documents have a status field that indicates their processing state:

• Status changes based on embedding and processing operations
• Check the status to determine if a document is ready for retrieval
• Use the embed parameter during creation for automatic embedding

Use Cases

• Knowledge base - Store documentation and reference material
• RAG (Retrieval Augmented Generation) - Enable semantic search over documents
• Context storage - Store contextual information for sequences and ESS
• Audit trails - Document state changes and events