Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""Notes to the employee: what it should learn at the start of its next turn
in a chat (docs-internal/chat_protocol.md, "Notes to the employee").
A note is one bracketed line, keyed per session so a newer note of the same
kind replaces an older one not yet told (``[ui-state]`` for an interface the
owner changed without pressing anything). The next run's payload claims the
session's untold notes (``claim_notes``, from ``agent.prepare_payload``) and
puts them ahead of the owner's message; the run's end marks them told
(``deliver_notes``) when it finished or stopped. A run that failed leaves
them untold, so the next turn offers them again, and a note changed after it
was claimed stays untold too.
"""
from __future__ import annotations
from datetime import datetime, timezone
from typing import Any, List
from sqlmodel import select
from core.logging import get_logger
from models.chat import ChatNote
logger = get_logger(__name__)
#: The most notes one turn carries; older ones wait for the next.
MAX_NOTES_PER_TURN = 8
def _utcnow() -> datetime:
return datetime.now(timezone.utc)
def _aware(moment: Any) -> Any:
if moment is not None and moment.tzinfo is None:
return moment.replace(tzinfo=timezone.utc)
return moment
async def upsert_note(database: Any, *, session_id: str, key: str, kind: str, text: str) -> None:
"""Keep ``text`` as the note under ``key``: a new note, or the newer
version of one (told again even when the older one was told)."""
now = _utcnow()
async with database.reserved_session() as session:
found = await session.execute(select(ChatNote).where(ChatNote.session_id == session_id, ChatNote.key == key))
note = found.scalar_one_or_none()
if note is None:
note = ChatNote(session_id=session_id, key=key, kind=kind, text=text, created_at=now, updated_at=now)
else:
note.kind = kind
note.text = text
note.updated_at = now
note.delivered_at = None
session.add(note)
await session.commit()
async def claim_notes(database: Any, *, session_id: str, run_id: str) -> List[ChatNote]:
"""The session's untold notes, oldest first, claimed by ``run_id`` (a
retried claim by the same run returns the same notes)."""
now = _utcnow()
async with database.reserved_session() as session:
found = await session.execute(
select(ChatNote)
.where(ChatNote.session_id == session_id, ChatNote.delivered_at.is_(None))
.order_by(ChatNote.updated_at, ChatNote.id)
.limit(MAX_NOTES_PER_TURN)
)
notes = list(found.scalars().all())
for note in notes:
note.claimed_run_id = run_id
note.claimed_at = now
session.add(note)
await session.commit()
for note in notes:
session.expunge(note)
return notes
async def deliver_notes(database: Any, run_id: str) -> int:
"""Mark the notes ``run_id`` claimed as told, except any changed since
it claimed them. Returns how many."""
async with database.reserved_session() as session:
found = await session.execute(select(ChatNote).where(ChatNote.claimed_run_id == run_id, ChatNote.delivered_at.is_(None)))
told = 0
now = _utcnow()
for note in found.scalars().all():
claimed, updated = _aware(note.claimed_at), _aware(note.updated_at)
if claimed is not None and updated is not None and updated > claimed:
continue
note.delivered_at = now
session.add(note)
told += 1
await session.commit()
return told
async def drop_note(database: Any, *, session_id: str, key: str) -> None:
"""Forget the note under ``key`` if it was not told yet (what it said no
longer holds, such as a rating taken back)."""
from sqlalchemy import delete
async with database.get_session() as session:
await session.execute(
delete(ChatNote).where(ChatNote.session_id == session_id, ChatNote.key == key, ChatNote.delivered_at.is_(None))
)
await session.commit()
async def clear_notes(database: Any, session_id: str) -> None:
"""Forget a session's notes (its conversation was cleared or reset)."""
from sqlalchemy import delete
async with database.get_session() as session:
await session.execute(delete(ChatNote).where(ChatNote.session_id == session_id))
await session.commit()
def notes_prompt(notes: List[ChatNote]) -> str:
"""The notes as the lines ahead of the owner's message."""
return "\n".join(note.text for note in notes)
__all__ = ["MAX_NOTES_PER_TURN", "claim_notes", "clear_notes", "deliver_notes", "drop_note", "notes_prompt", "upsert_note"]