Template placeholders

from vectorshift.agent import Agent, AgentType, IOConfig, LLMInfo
from vectorshift.agent.template_refs import TemplateReferenceError
from vectorshift.agent.tool import ToolInput, ToolInputType
from vectorshift.agent.tools import GoogleSearchTool


def main() -> None:
    # Tool whose LLM-facing name is `google_search` — users reference it
    # as `[[tools.google_search]]` in instructions and descriptions.
    search = GoogleSearchTool(
        tool_name="google_search",
        tool_description="Look up fresh facts about [[inputs.topic]] on the web.",
        query=ToolInput(
            type=ToolInputType.DYNAMIC,
            description="A query related to [[inputs.topic]]",
        ),
        num_results=10,
    )

    agent = Agent.new(
        name="Topic briefing (v2 templates)",
        type=AgentType.FUNCTIONAL,
        llm_info=LLMInfo(provider="openai", model_id="gpt-4o"),
        tools=[search],
        instructions=(
            "For the given [[inputs.topic]], call [[tools.google_search]] "
            "for fresh facts, then write a short brief into [[outputs.brief]]."
        ),
        inputs={
            "topic": IOConfig(io_type="string", description="Subject to brief"),
        },
        outputs={
            "brief": IOConfig(io_type="string", description="Markdown brief"),
        },
    )
    print(f"Created agent: {agent.name} (id={agent.id})")
    # After Agent.new() the server stores the rewritten canonical form.
    fresh = Agent.fetch(id=agent.id)
    print("Server-stored instructions (canonical {{...}} form):")
    print(f"  {fresh.instructions!r}")
    tool_from_server = next(iter(fresh.tools), None)
    if tool_from_server is not None:
        print(f"Server-stored tool description: {tool_from_server.description!r}")

    # Re-saving an agent already carrying canonical placeholders is a
    # no-op: the `{{...}}` wire form passes through unchanged.
    fresh.save()
    print("Saved with canonical placeholders (idempotent).")

    # Demonstrate the rejection paths: both a missing prefix and a
    # namespaced typo raise TemplateReferenceError before anything hits
    # the network.
    for bad, why in [
        ("Summarize [[topic]]", "bare placeholder (no prefix)"),
        ("Summarize [[inputs.topci]]", "typo in input key"),
        ("Call [[tools.goggle_search]]", "typo in tool name"),
    ]:
        try:
            Agent.new(
                name="will not be created",
                type=AgentType.FUNCTIONAL,
                llm_info=LLMInfo(provider="openai", model_id="gpt-4o"),
                tools=[search],
                instructions=bad,
                inputs={"topic": IOConfig(io_type="string")},
            )
        except TemplateReferenceError as e:
            print(f"\n[{why}] rejected:")
            print(f"  {e}")

    # f-strings keep working side-by-side — `[[ ]]` never conflicts.
    subject = "quantum computing"
    composed = (
        f"(Briefing subject: {subject}) For [[inputs.topic]] call "
        f"[[tools.google_search]]."
    )
    print(f"\nf-string composed instructions preserved:\n  {composed!r}")


if __name__ == "__main__":
    main()