lauren-ai

lauren-ai: the first-party AI/LLM companion to the Lauren web framework. Agents, tools, memory, workflows, RAG, and evaluation in the same decorator-first, DI-driven programming model.

---

Documentation: https://ai.lauren-py.dev

Source Code: https://github.com/lauren-framework/lauren-ai

---

For AI Agents & Coding Assistants

Install all skills in one command

# Claude Code, Cursor, Copilot, Continue, Codex CLI -- auto-detected
npx skills add lauren-framework/lauren-ai

This copies the repository's skill packs into your agent's global skills directory (~/.claude/skills/, ~/.cursor/skills/, etc.). The next time your agent opens a lauren-ai project it has pre-loaded guidance on agents, tools, memory, evaluation, workflows, and Lauren integration patterns.

Resource	What it contains
llms.txt	2 KB overview -- start here
llms-full.txt	Complete reference -- all decorators, memory, guardrails, teams, and common errors
AGENTS.md	By-task lookup, common errors, skills index, definition of done
CLAUDE.md	Architecture invariants, commands, pattern selection, codemap navigation
skills/	Copy-paste skill guides covering common lauren-ai tasks

Skills index: skills/

---

lauren-ai is the first-party AI/LLM companion to the Lauren web framework. It brings large language model agents into the same decorator-first, DI-driven, module-scoped programming model the rest of Lauren uses. It is built on these core ideas:

• Decorator-first metadata. Agents, tools, teams, guardrails, prompt templates, and memory behaviors are declared with decorators and metadata rather than custom runtime glue.
• Module-scoped integration. LLMModule.for_root() and AgentModule.for_root() plug into Lauren's module system so transports, runners, tools, and stores compose like the rest of your application.
• Provider-agnostic execution. Anthropic, OpenAI, Ollama, LiteLLM, and MockTransport all flow through a unified transport layer and consistent agent runner API.
• AI-ready by default. The public surface is mirrored in llms.txt, llms-full.txt, AGENTS.md, CLAUDE.md, and skills/ so both human and AI contributors can navigate the package quickly.

Features

• Provider-agnostic transport - Anthropic, OpenAI, Ollama, LiteLLM, and MockTransport for zero-network-call tests.
• @tool() decorator - Function-form and class-form (DI-injected), with JSON Schema auto-generated from type hints and docstrings.
• @agent() decorator - Autonomous agentic loop with use_tools(), lifecycle hooks, retry/error policies, and budget guards.
• Four memory tiers - ShortTermMemory, ConversationStore, UserMemoryStore plus @remember(), and vector-backed retrieval for RAG.
• Typed extractors - Agent[T], Completion[T], Embed[T], and StreamCompletion[T] as Lauren handler parameters.
• Module factories - LLMModule.for_root() and AgentModule.for_root() feel like the rest of Lauren's DI-first module configuration.
• Knowledge Base and agentic RAG - KnowledgeBase with document loaders, hybrid retrieval, and kb.as_tool().
• Structured workflows - Workflow, Step, Parallel, Condition, and Loop for deterministic multi-agent pipelines.
• Tool enhancements - Human-in-the-loop confirmation, pre/post hooks, and result caching.
• Extended thinking - First-class support for Claude extended thinking and OpenAI reasoning models.
• Evaluation framework - AccuracyEval, AgentJudge, TrajectoryEval, and PerformanceEval.
• Signals - ModelCallComplete, ToolCallComplete, and AgentRunComplete for observability.
• Pre-built skills - WebSearchTool, CodeExecutionTool, and HttpFetchTool.
• Testable - Zero API calls needed in unit tests via MockTransport.

Requirements

Python 3.11, 3.12, 3.13, and 3.14 are supported. Core dependencies:

• Lauren - the host web framework and DI/module runtime.
• Pydantic - structured models, schemas, and validation.
• httpx - provider HTTP transport.
• anyio - concurrency primitives and async portability.

Installation

# Core (no LLM provider extras)
pip install lauren-ai

# With Anthropic
pip install "lauren-ai[anthropic]"

# With OpenAI
pip install "lauren-ai[openai]"

# With everything
pip install "lauren-ai[all]"

Quick start

import os

from pydantic import BaseModel

from lauren import LaurenFactory, controller, module, post
from lauren.types import Json
from lauren_ai import (
    Agent,
    AgentModule,
    AgentRunner,
    InMemoryConversationStore,
    LLMConfig,
    LLMModule,
    agent,
    tool,
    use_tools,
)


@tool()
async def get_weather(city: str) -> dict:
    """Get current weather for a city.

    Args:
        city: The city name.
    """
    return {"city": city, "temperature_c": 18, "condition": "cloudy"}


# @agent() is outermost; @use_tools() is below it (applied first)
@agent(model="claude-opus-4-6", system="You are a helpful travel assistant.")
@use_tools(get_weather)
class TravelAgent: ...


class AskRequest(BaseModel):
    question: str


@controller("/travel")
class TravelController:
    def __init__(self, runner: AgentRunner) -> None:
        self._runner = runner

    @post("/ask")
    async def ask(self, body: Json[AskRequest], agent: Agent[TravelAgent]) -> dict:
        response = await self._runner.run(agent, body.question)
        return {"answer": response.content, "turns": response.turns}


LLMProviderModule = LLMModule.for_root(
    LLMConfig.for_anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
)
AIAgentModule = AgentModule.for_root(
    agents=[TravelAgent],
    tools=[get_weather],
    conversation_store=InMemoryConversationStore(),  # history persists across requests
)


@module(controllers=[TravelController], imports=[LLMProviderModule, AIAgentModule])
class AppModule: ...


app = LaurenFactory.create(AppModule)

uvicorn main:app --reload

Development

# Install with dev dependencies
uv sync --extra dev --extra anthropic

# Run tests
uv run nox -s tests

# Run linter
uv run nox -s lint

# Run typecheck
uv run nox -s typecheck

# Build docs
uv run nox -s docs

License

MIT - see LICENSE.