backend/src/services/notes.py

"""Helpers for coordinating note tool usage instructions."""

from __future__ import annotations

import json

from models import TodoItem


def build_note_guidance(task: TodoItem) -> str:
    """Generate note tool usage guidance for a specific task."""

    tags_list = ["deep_research", f"task_{task.id}"]
    tags_literal = json.dumps(tags_list, ensure_ascii=False)

    if task.note_id:
        read_payload = json.dumps({"action": "read", "note_id": task.note_id}, ensure_ascii=False)
        update_payload = json.dumps(
            {
                "action": "update",
                "note_id": task.note_id,
                "task_id": task.id,
                "title": f"Task {task.id}: {task.title}",
                "note_type": "task_state",
                "tags": tags_list,
                "content": "Please add the new information from this round to the task overview",
            },
            ensure_ascii=False,
        )

        return (
            "Note collaboration guide:\n"
            f"- Current task note ID: {task.note_id}.\n"
            f"- Before writing the summary, you must call: [TOOL_CALL:note:{read_payload}] to get the latest content.\n"
            f"- After completing analysis, call: [TOOL_CALL:note:{update_payload}] to sync incremental information.\n"
            "- When updating, maintain the original paragraph structure and add new content to the corresponding sections.\n"
            f"- Recommended to keep tags as {tags_literal} so other Agents can quickly locate it.\n"
            "- After successfully syncing to notes, then output the summary for the user.\n"
        )

    create_payload = json.dumps(
        {
            "action": "create",
            "task_id": task.id,
            "title": f"Task {task.id}: {task.title}",
            "note_type": "task_state",
            "tags": tags_list,
            "content": "Please record task overview, sources overview",
        },
        ensure_ascii=False,
    )

    return (
        "Note collaboration guide:\n"
        f"- No note has been created for this task yet, please first call: [TOOL_CALL:note:{create_payload}].\n"
        "- After successful creation, record the returned note_id and reuse it in all subsequent updates.\n"
        "- After syncing notes, then output the summary for the user.\n"
    )