mirascope-and-lilypad-best-practices

Mirascope and Lilypad Best Practices

This rule outlines best practices for using @Mirascope and @Lilypad in this codebase. Follow these guidelines to ensure maintainable, scalable, and idiomatic LLM-powered features with robust observability.

1. Prompt Templates

• Always use @prompt_template decorators for prompt construction. Prefer prompt templates over shorthand string or list returns for clarity and reusability.
• Keep prompt logic modular: define each prompt as a separate function, ideally in a prompts/ module.
• Type all prompt template arguments for clarity and static analysis.
• Inject chat history and context using template arguments, not global state.

2. Response Models

• Define a Pydantic response model for every LLM call. Use the response_model argument in the call decorator (e.g., @llm.call(provider="openai", model="gpt-4o-mini", ..., response_model=MyModel)).
• Validate and parse LLM outputs using these models to ensure structured, reliable results.
• Store response models in a dedicated module (e.g., schemas/llm_responses.py).

3. Tools as Functions

• Write tools as plain functions using Mirascope's functional tool API, not as subclasses of BaseTool unless absolutely necessary.
• Annotate tool arguments and return types for all tool functions.
• Register tools using the appropriate Mirascope decorator or registry pattern.
• Keep tool logic stateless and side-effect free where possible.

4. Parallel and Async Calls

• Prefer async def for all LLM calls and tool functions to maximize concurrency.
• Use Mirascope's async and parallel APIs to batch or parallelize LLM/tool calls when possible.
• Avoid blocking I/O in any LLM, tool, or agent logic.

5. Agent and Call Structure

• Organize agents, prompts, tools, and calls in separate modules for clarity.
• Use chaining and composition: build complex agent flows by composing prompt templates, tools, and LLM calls.
• Document each agent, tool, and prompt with clear docstrings and usage examples.