Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us