Getting Started › Installation

Installation

Get n00dles running in your Python environment. The core package has minimal dependencies and installs in seconds.

Requirements

Python 3.10 or later
pip 22+ or Poetry 1.5+
At least one LLM API key (Anthropic, OpenAI, etc.)

Install

Install from PyPI with pip:

bash

pip install n00dles

Or with Poetry:

bash

poetry add n00dles

ℹ

For the latest unreleased features, install from GitHub: pip install git+https://github.com/n00dles/n00dles

Configure API keys

n00dles reads LLM credentials from environment variables. Set the key for your preferred provider:

bash

# Anthropic (recommended)
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI
export OPENAI_API_KEY="sk-..."

# Mistral
export MISTRAL_API_KEY="..."

✓

Add these to your .env file and use python-dotenv — n00dles will pick them up automatically.

Verify installation

python

from n00dles import version
print(version())  # → "0.1.0"

Core Concepts › Agents

Agents

An agent is an LLM-backed function with typed inputs and outputs. In n00dles, you define one by decorating any Python function with @agent.

Defining an agent

python

from n00dles import agent

@agent(model="claude-sonnet-4-6")
def summarizer(text: str) -> str:
    """Summarize the given text in three concise sentences."""

The function's docstring becomes the system prompt. The type annotations define the contract — n00dles validates input and output against them automatically.

How it works

When you call an agent, n00dles:

Validates the input against the type annotations
Constructs a prompt from the docstring + serialized input
Calls the specified LLM with retry + timeout logic
Parses and validates the typed output
Emits a structured trace event

Output types

Agents support all standard Python types as outputs. For structured data, use Pydantic models:

python

from pydantic import BaseModel
from n00dles import agent

class Sentiment(BaseModel):
    label: str       # "positive" | "negative" | "neutral"
    confidence: float  # 0.0 – 1.0
    summary: str

@agent(model="claude-haiku-4-5")
def analyze_sentiment(review: str) -> Sentiment:
    """Analyze the sentiment of the product review."""

result = analyze_sentiment("Absolutely love this product!")
print(result.label)       # → "positive"
print(result.confidence)  # → 0.97

Overriding the prompt

Use the prompt parameter to supply a system prompt explicitly, independent of the docstring:

python

@agent(
    model="claude-sonnet-4-6",
    prompt="""You are a financial analyst specializing in tech sector equities.
Provide structured analysis with explicit uncertainty estimates."""
)
def equity_analyst(ticker: str, context: str) -> dict:
    """Analyze the equity."""

API Reference › @agent

@agent

The @agent decorator transforms any Python function into an LLM-backed agent with built-in retry, timeout, type validation, and tracing.

Signature

python

@agent(
    model: str,
    prompt: str | None = None,
    timeout: int = 60,
    retry: int = 3,
    temperature: float = 0.7,
    max_tokens: int | None = None,
    tags: list[str] = [],
)

Parameters

Parameter	Type	Default	Description
model	str	required	The LLM model identifier. e.g. "claude-sonnet-4-6", "gpt-4o", "mistral-large".
prompt	str \| None	None	System prompt. If None, the function's docstring is used.
timeout	int	60	Timeout in seconds per attempt. Raises TimeoutError if exceeded.
retry	int	3	Maximum retry attempts on transient failures. Uses exponential backoff with jitter.
temperature	float	0.7	LLM sampling temperature (0.0–2.0). Lower = more deterministic.
max_tokens	int \| None	None	Cap on output tokens. None defers to model default.
tags	list[str]	[]	Arbitrary tags attached to trace events for filtering in the dashboard.

Returns

The decorator returns a callable with the same signature as the decorated function. The return type is the declared return annotation, validated via Pydantic.

⚠

If the LLM output cannot be coerced into the declared return type after all retries, an AgentOutputError is raised.

Examples

python

# Minimal — model is the only required arg
@agent(model="claude-haiku-4-5")
def translator(text: str, target_lang: str) -> str:
    """Translate the text into the target language."""

# With overrides for a production-critical agent
@agent(
    model="claude-sonnet-4-6",
    timeout=120,
    retry=5,
    temperature=0.2,
    tags=["production", "kyc"]
)
def kyc_extractor(document: str) -> CustomerRecord:
    """Extract structured KYC data from the document."""

Docs

Documentation

This section of the documentation is being written. Check back soon, or ask on Discord.

ℹ

Want to contribute docs? Open a PR at github.com/n00dles/n00dles/docs — we merge fast.