llm-apps-creator

What this skill does

# LLM Apps Creator

## Overview

This skill provides essential patterns for building LLM-powered applications using LangChain. It covers three core concepts:

1. **Universal LLM Initialization** - Initialize any LLM provider with a single function
2. **Agent Loop Pattern** - The simple but powerful pattern used by top AI agents
3. **Structured Output** - Get predictable, validated responses from LLMs

## Core Philosophy

> "The main agent is just a loop. The session memory is just a list of messages. It is enough to build the most powerful agent in the world."

Forget complex frameworks like ReAct/Reflection agents. The same simple agent-loop pattern is used in one of the most powerful agents: Claude Code.

## Quick Start

### Initialize Any LLM

Use `init_chat_model` to initialize any LLM provider with automatic detection:

```python
from langchain.chat_models import init_chat_model
from dotenv import load_dotenv
load_dotenv()

# Auto-detects provider from model name
llm = init_chat_model("gpt-4.1")                    # OpenAI (needs OPENAI_API_KEY)
llm = init_chat_model("claude-sonnet-4-5-20250929") # Anthropic (needs ANTHROPIC_API_KEY)
llm = init_chat_model("grok-code-fast-1")           # xAI (needs XAI_API_KEY)

# Explicit provider specification
llm = init_chat_model("gemini-2.5-flash", model_provider="google_genai")  # Google
llm = init_chat_model("my-model", model_provider="openai")                # Custom
```

### Create Tools with DETAILED Docstrings

> **CRITICAL**: The docstring IS the prompt that tells the LLM how to use the tool. Poor docstrings = poor tool usage = broken agent.

```python
from langchain_core.tools import tool

# BAD - minimal docstring, LLM won't know how to use properly
@tool
def read_file(file_path: str) -> str:
    """Read a file."""  # DON'T DO THIS!
    ...

# GOOD - detailed docstring with usage guidelines
@tool("Read")  # Named tool for clarity
def read_file(file_path: str) -> str:
    """Reads a file from the local filesystem and returns its contents.

    ## Usage Guidelines
    - **file_path must be ABSOLUTE** (e.g., /Users/name/project/file.py), NOT relative
    - Returns file contents with line numbers in `cat -n` format
    - If file doesn't exist, returns an error message (this is OK, don't panic)

    ## When to Use
    - Reading source code to understand implementation
    - Checking configuration files
    - ALWAYS read a file BEFORE trying to edit or write to it

    ## Performance Tips
    - You can call this tool multiple times in parallel for different files

    Args:
        file_path: The ABSOLUTE path to the file (e.g., /Users/name/project/src/main.py)

    Returns:
        File contents with line numbers, or error message if file not found
    """
    try:
        with open(file_path, 'r') as f:
            lines = f.readlines()
        # Format with line numbers like cat -n
        result = []
        for i, line in enumerate(lines, 1):
            result.append(f"{i:6d}\t{line.rstrip()}")
        return "\n".join(result)
    except FileNotFoundError:
        return f"Error: File not found: {file_path}"
    except Exception as e:
        return f"Error reading file: {e}"
```

### More Tool Examples

```python
@tool("Write")
def write_file(file_path: str, content: str) -> str:
    """Writes content to a file, creating it if it doesn't exist or OVERWRITING if it does.

    ## Usage Guidelines
    - **file_path must be ABSOLUTE**, NOT relative
    - This will OVERWRITE the entire file - use Edit tool for partial modifications
    - **CRITICAL**: ALWAYS use Read tool first to check existing content!

    ## When to Use
    - Creating NEW files that don't exist yet
    - Completely replacing file contents

    ## When NOT to Use
    - Modifying existing files (use Edit tool instead)
    - If you haven't read the file first

    Args:
        file_path: The ABSOLUTE path to write to
        content: The complete content to write to the file

    Returns:
        Success message with file path, or error message
    """
    import os
    try:
        dir_path = os.path.dirname(file_path)
        if dir_path:
            os.makedirs(dir_path, exist_ok=True)
        with open(file_path, 'w') as f:
            f.write(content)
        return f"Successfully wrote {len(content)} characters to {file_path}"
    except Exception as e:
        return f"Error writing file: {e}"

@tool("Bash")
def run_command(command: str, working_dir: str = None) -> str:
    """Executes a bash/shell command and returns the output (stdout + stderr).

    ## Usage Guidelines
    - Use for running scripts, builds, tests, git commands, etc.
    - Commands timeout after 30 seconds
    - Use absolute paths in commands to avoid directory confusion

    ## When to Use
    - Running build tools (npm, pip, cargo, make, etc.)
    - Git operations (git status, git diff, git commit, etc.)
    - Running tests (pytest, jest, cargo test, etc.)

    ## When NOT to Use
    - Reading files (use Read tool instead of cat/head/tail)
    - Searching files (use dedicated search tools instead of grep/find)

    Args:
        command: The shell command to execute
        working_dir: Optional working directory (absolute path)

    Returns:
        Command output (stdout + stderr combined), or error/timeout message
    """
    import subprocess
    import os
    try:
        cwd = working_dir if working_dir else os.getcwd()
        result = subprocess.run(
            command, shell=True, capture_output=True,
            text=True, timeout=30, cwd=cwd
        )
        output = result.stdout
        if result.stderr:
            output += f"\nSTDERR:\n{result.stderr}"
        if result.returncode != 0:
            output += f"\n[Exit code: {result.returncode}]"
        return output if output.strip() else "(Command completed with no output)"
    except subprocess.TimeoutExpired:
        return "Error: Command timed out after 30 seconds"
    except Exception as e:
        return f"Error executing command: {e}"
```

### Initialize Agent with Tools

```python
from langchain.chat_models import init_chat_model

# Initialize LLM with tools
llm = init_chat_model("gpt-4.1")
llm_with_tools = llm.bind_tools([read_file, write_file, run_command])
```

### Get Structured Output

```python
from pydantic import BaseModel, Field
from langchain.agents import create_agent

class ContactInfo(BaseModel):
    """Contact information for a person."""
    name: str = Field(description="The name of the person")
    email: str = Field(description="The email address")
    phone: str = Field(description="The phone number")

agent = create_agent(
    model="gpt-4.1",
    response_format=ContactInfo  # Auto-selects best strategy
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Extract: John Doe, [email protected], 555-1234"}]
})
print(result["structured_response"])
# ContactInfo(name='John Doe', email='[email protected]', phone='555-1234')
```

## The Agent Loop Pattern

The core pattern is deceptively simple:

```
1. User sends a message
2. LLM responds (possibly with tool calls)
3. If tool calls exist, execute them and feed results back
4. Repeat until LLM responds without tool calls
```

### Complete Agent Implementation

```python
from typing import List, Dict, Any, Optional
from langchain_core.messages import SystemMessage, HumanMessage, ToolMessage
from langchain_core.tools import BaseTool
from langchain.chat_models import init_chat_model

class SimpleAgent:
    """A minimal agent that uses tools to accomplish tasks."""

    def __init__(
        self,
        system_prompt: str,
        tools: List[BaseTool],
        model_name: str = "gpt-4.1",
        model_provider: Optional[str] = None,
    ):
        # Store tools in a map for quick lookup
        self.tools_map: Dict[str, BaseTool] = {tool.name: tool for tool in tools}

        # Create LLM with tools bound
        llm = init_chat_model(model_name, model_provider=model_provider)
        self.llm_w