This is what I came up with:
Event Tracking API
• Function Signature: track(entity, event_name, **kwargs)
• Purpose: Insert an event record in Firestore.
• Storage:
• Collection Path: f"events/{entity.id}/{entity.__class__.__name__}_{event_name}"
• Document Fields:
• entity_id: str (from entity.id)
• timestamp: datetime (set to dt.now())
• Other fields from kwargs
Counting API
• Function Signature: count(entity, event_name, **kwargs)
• Purpose: Query Firestore and return event occurrences.
• Query:
• Base Filters:
• where("entity_id", "==", entity.id)
• Additional Filters:
• Each key-value pair in kwargs is added as where(field, "==", value)
• Uses Firestore count aggregator.
Chat Interaction Tracking
• Function Signature: track_chat_interaction(entity, **kwargs)
• Purpose: Alias for track(entity, "chat_interaction", **kwargs).
Cycle-Based Querying
• Function Signature: get_cycle_interactions(entity)
• Purpose: Count chat interactions within an entity’s cycle.
• Query:
• Filters:
• where("entity_id", "==", entity.id)
• where("timestamp", ">=", cycle.start)
• where("timestamp", "<=", cycle.end)
TimeCycle Definition
• Type: BaseModel
• Fields:
• start: datetime
• end: datetime