Entity Embedding and Indexing
Hass-MCP provides automatic entity embedding and indexing for semantic search capabilities. This enables natural language discovery of entities based on their descriptions and metadata.
Overview
Entity indexing automatically:
- Generates Rich Descriptions: Creates comprehensive text descriptions from entity metadata
- Creates Embeddings: Converts descriptions to vector embeddings
- Indexes in Vector DB: Stores embeddings with metadata for semantic search
- Handles Updates: Automatically updates index when entities change
- Batch Processing: Efficiently processes large numbers of entities
Quick Start
Index a Single Entity
from app.core.vectordb.indexing import index_entity
# Index a single entity
result = await index_entity("light.living_room")
if result["success"]:
print(f"Indexed: {result['entity_id']}")
print(f"Description: {result['description']}")
Index All Entities
from app.core.vectordb.indexing import index_entities
# Index all entities in batches
result = await index_entities(batch_size=100)
print(f"Indexed {result['succeeded']} out of {result['total']} entities")
Check Indexing Status
from app.core.vectordb.indexing import get_indexing_status
# Get indexing status
status = await get_indexing_status()
print(f"Total indexed: {status['total_entities']}")
print(f"Collection exists: {status['collection_exists']}")
Entity Description Generation
Entity descriptions are automatically generated from metadata to provide rich context for semantic search.
Description Components
- Friendly Name: Primary identifier for the entity
- Domain Type: Entity type (light, sensor, switch, etc.)
- Area/Room: Location information
- Device Information: Manufacturer and model
- Capabilities: Domain-specific features
- Current State: Current entity state
Example Descriptions
Light Entity:
Living Room Light - light entity in the Living Room area.
Supports brightness, color_temp. brightness control. color temperature control.
Currently on.
Sensor Entity:
Climate Entity:
Living Room Thermostat - climate entity in the Living Room area.
current temperature 21.5. target temperature 22.0. mode heat.
Custom Descriptions
You can generate custom descriptions:
from app.core.vectordb.indexing import generate_entity_description
entity = {
"entity_id": "light.living_room",
"state": "on",
"attributes": {
"friendly_name": "Living Room Light",
"area_id": "living_room",
},
}
description = generate_entity_description(
entity,
area_name="Living Room",
device_info={"manufacturer": "Philips", "model": "Hue"},
)
Indexing Functions
index_entity
Index a single entity in the vector database.
async def index_entity(
entity_id: str,
manager: VectorDBManager | None = None
) -> dict[str, Any]:
"""
Index a single entity in the vector database.
Args:
entity_id: The entity ID to index
manager: Optional VectorDBManager instance
Returns:
Dictionary with indexing result:
- entity_id: The entity ID indexed
- success: Boolean indicating if indexing succeeded
- description: Generated description
- error: Error message if indexing failed
"""
Example:
result = await index_entity("light.living_room")
# {
# "entity_id": "light.living_room",
# "success": True,
# "description": "Living Room Light - light entity..."
# }
index_entities
Index multiple entities in batches.
async def index_entities(
entity_ids: list[str] | None = None,
batch_size: int = 100,
manager: VectorDBManager | None = None,
) -> dict[str, Any]:
"""
Index multiple entities in batches.
Args:
entity_ids: Optional list of entity IDs to index.
If None, indexes all entities.
batch_size: Number of entities to process in each batch
manager: Optional VectorDBManager instance
Returns:
Dictionary with indexing results:
- total: Total number of entities processed
- succeeded: Number of successfully indexed entities
- failed: Number of failed entities
- results: List of individual indexing results
"""
Example:
# Index all entities
result = await index_entities()
# Index specific entities
result = await index_entities(
entity_ids=["light.living_room", "sensor.temperature"],
batch_size=50,
)
update_entity_index
Update an existing entity in the index.
async def update_entity_index(
entity_id: str,
manager: VectorDBManager | None = None
) -> dict[str, Any]:
"""
Update an existing entity in the index.
Args:
entity_id: The entity ID to update
manager: Optional VectorDBManager instance
Returns:
Dictionary with update result
"""
Example:
remove_entity_from_index
Remove an entity from the index.
async def remove_entity_from_index(
entity_id: str,
manager: VectorDBManager | None = None
) -> dict[str, Any]:
"""
Remove an entity from the index.
Args:
entity_id: The entity ID to remove
manager: Optional VectorDBManager instance
Returns:
Dictionary with removal result
"""
Example:
get_indexing_status
Get indexing status for the entity collection.
async def get_indexing_status(
manager: VectorDBManager | None = None
) -> dict[str, Any]:
"""
Get indexing status for the entity collection.
Args:
manager: Optional VectorDBManager instance
Returns:
Dictionary with indexing status:
- collection_exists: Whether the collection exists
- total_entities: Total number of indexed entities
- dimensions: Vector dimensions
- metadata: Collection metadata
"""
Example:
status = await get_indexing_status()
# {
# "collection_exists": True,
# "total_entities": 50,
# "dimensions": 384,
# "metadata": {}
# }
Metadata Storage
Entities are indexed with rich metadata for filtering and search:
{
"entity_id": "light.living_room",
"domain": "light",
"friendly_name": "Living Room Light",
"area_id": "living_room",
"device_id": "device_123",
"device_class": None,
"manufacturer": "Philips",
"model": "Hue",
"last_updated": "2025-01-01T12:00:00Z",
"indexed_at": "2025-01-01T12:00:00Z"
}
Metadata Fields
- entity_id: Unique entity identifier
- domain: Entity domain (light, sensor, etc.)
- friendly_name: Display name
- area_id: Area/room identifier
- device_id: Device identifier
- device_class: Device class (if applicable)
- manufacturer: Device manufacturer (if available)
- model: Device model (if available)
- last_updated: Last entity update timestamp
- indexed_at: Indexing timestamp
Batch Processing
Batch indexing processes entities in configurable batches for performance:
Batch Size Configuration
# Small batches for slower systems
result = await index_entities(batch_size=50)
# Large batches for faster systems
result = await index_entities(batch_size=500)
# Default batch size (100)
result = await index_entities()
Progress Tracking
result = await index_entities(batch_size=100)
print(f"Total: {result['total']}")
print(f"Succeeded: {result['succeeded']}")
print(f"Failed: {result['failed']}")
# Check individual results
for item in result["results"]:
if not item["success"]:
print(f"Failed to index {item['entity_id']}: {item.get('error')}")
Incremental Updates
Entities can be updated incrementally when they change:
Manual Updates
Automatic Updates
For automatic updates, you would typically:
- Listen to entity state changes
- Detect relevant changes (name, area, attributes)
- Call
update_entity_index()for changed entities
Example:
# When entity name changes
async def on_entity_changed(entity_id: str):
await update_entity_index(entity_id)
Error Handling
Indexing functions handle errors gracefully:
Entity Not Found
result = await index_entity("light.nonexistent")
# {
# "entity_id": "light.nonexistent",
# "success": False,
# "error": "Entity not found"
# }
Vector DB Disabled
# If vector DB is disabled
result = await index_entity("light.living_room")
# {
# "entity_id": "light.living_room",
# "success": False,
# "error": "Vector DB is disabled"
# }
Partial Failures
When indexing multiple entities, individual failures don't stop the process:
result = await index_entities(
entity_ids=["light.living_room", "sensor.nonexistent"],
)
# result["succeeded"] == 1
# result["failed"] == 1
# Check individual results for details
Best Practices
- Initial Indexing: Index all entities on startup or first run
- Batch Size: Use batch sizes of 100-500 for optimal performance
- Incremental Updates: Update entities when they change (name, area, attributes)
- Error Handling: Check individual results for failures
- Status Monitoring: Regularly check indexing status
- Cleanup: Remove deleted entities from the index
Performance Considerations
- Batch Processing: Process entities in batches for better performance
- Async Operations: All operations are async for non-blocking I/O
- Error Recovery: Individual entity failures don't stop batch processing
- Metadata Caching: Area and device information is cached for performance
Troubleshooting
Entities Not Indexing
Problem: Entities fail to index
Solutions: - Check vector DB is enabled - Verify entity exists in Home Assistant - Check entity metadata is valid - Review logs for specific errors
Slow Indexing
Problem: Indexing is slow
Solutions: - Reduce batch size for slower systems - Check vector DB backend performance - Verify embedding model is working correctly - Check network connectivity (for cloud embeddings)
Index Out of Sync
Problem: Index doesn't match current entities
Solutions:
- Re-index all entities: await index_entities()
- Check for indexing errors
- Verify entity updates are being processed
- Check vector DB collection status
Related Features
- US-VD-001: Vector DB Core Infrastructure
- US-VD-004: Semantic Entity Search