# lauren-ai

> First-party AI/LLM companion for the Lauren web framework. Integrates large-language-model completions, agentic loops, tool execution, memory management, and structured workflows into Lauren applications using the same decorator-first, DI-driven, module-scoped paradigm as Lauren itself.

## Installation

```bash
pip install "lauren-ai[anthropic]"   # Anthropic Claude (default)
pip install "lauren-ai[openai]"      # OpenAI / Ollama
pip install "lauren-ai[all]"         # All providers + all extras
```

## Core concepts

- **`@tool()`** — Marks an async function or class as an agent tool. JSON schema auto-generated from type annotations + Google-style `Args:` docstring. Never use `from __future__ import annotations` in function-form tool files.
- **`@agent()`** — Declares an agent class with an autonomous agentic loop. Must be outermost decorator; `@use_tools()` is innermost.
- **`AgentRunner`** — Protocol. `AgentRunnerBase` is the concrete implementation. In production, created by `AgentModule.for_root()`.
- **`LLMModule.for_root(cfg)`** — Wires the LLM provider into the Lauren DI container.
- **`AgentModule.for_root(...)`** — Registers agents, tools, and a runner as a Lauren module.
- **Memory tiers** — `InMemoryConversationStore` (per-session history), `UserMemoryStore` + `@remember()` (long-term facts), `KnowledgeBase` + `VectorStore` (RAG).
- **`@use_guardrails(input=[...], output=[...])`** — Attaches guardrail instances to an agent for scope enforcement.
- **`@team()`** — Multi-agent team with coordinator or collaborate mode.
- **`SignalBus`** — Observability hook: `ModelCallComplete`, `ToolCallComplete`, `AgentRunComplete`.
- **`CostTracker`** — Accumulates token usage and cost per model.

## Critical rules

1. `from __future__ import annotations` is **forbidden** in function-form `@tool()` files — it breaks JSON schema generation.
2. Decorator order is mandatory: `@agent` → `@remember` → `@use_guardrails` → `@use_knowledge_sources` → `@use_tools`.
3. All AI decorators require parentheses: `@tool()` not `@tool`.
4. Never read user identity from LLM tool parameters — read from `ctx.execution_context.request.state.get("user_id")`.
5. Use `AgentRunner[AgentX]` (parameterized form) when multiple runners are visible in the same DI scope.

## Documentation for LLMs

- Full API reference: https://raw.githubusercontent.com/lauren-framework/lauren-ai/main/llms-full.txt
- Short overview: https://raw.githubusercontent.com/lauren-framework/lauren-ai/main/llms.txt
- Agent instructions: https://raw.githubusercontent.com/lauren-framework/lauren-ai/main/AGENTS.md
- Skills: https://github.com/lauren-framework/lauren-ai/tree/main/skills/