lovia

English | 简体中文

lovia is an elegant, restrained Python framework for developers who want to own the agent loop without rebuilding every supporting primitive from scratch. It covers the recurring hard parts of agent applications — tools, sessions, events, context compaction, serving — without turning into a platform.

pip install lovia

from lovia import Agent, tool


@tool
def get_order(order_id: str) -> str:
    """Look up an order's status by id."""
    return f"Order {order_id}: shipped 2 days ago, arriving Thursday."


# Configure OPENAI_BASE_URL and OPENAI_API_KEY in your environment.
agent = Agent(
    name="support",
    instructions="You are a customer-support agent. Look the order up before "
    "answering, and reply in one or two concrete sentences.",
    model="glm-5.2",
    tools=[get_order],
)

# run_sync() suits scripts and notebooks; from async code,
# use `await Runner.run(agent, ...)` instead.
result = agent.run_sync("Where is my order A-1042?")
print(result.output)

Or serve a full chat UI — memory, skills, scheduling, and a workspace on the current directory included — in one line:

pip install "lovia[web]" && lovia web

Anthropic is built in too: configure ANTHROPIC_API_KEY, set ANTHROPIC_BASE_URL for non-default endpoints, and use the anthropic: model prefix. Everything else about models lives in Providers & models.

Documentation

This README is a quick tour. For the full guide, start with the quickstart and core concepts in the documentation. The examples are a numbered, runnable learning path.

Why lovia

Composable primitives, ordinary Python — no new universe of abstractions:

Minimum dependencies. The core depends only on httpx, pydantic, and pyyaml; install everything else only when needed.
Few abstractions. An Agent is treated as immutable configuration and normally varied with clone(); a Runner executes one run, and @tool wraps a typed callable as a Tool; handoff and agent-as-tool compose agents; plugins package the rest.
Readable. The critical path is concentrated and explicit: model calls, tool execution, retries, and persistence happen in a clear order. When something surprises you, there is one chain to follow.
Lightweight model integration. OpenAI, Anthropic, and compatible endpoints are built in. There is no adapter stack to fight; a new provider is just a small Protocol.
Cache-friendly context management. Compaction changes only the next model view, without rewriting the conversation body, and keeps prompt prefixes stable. Explicit output limits and persistence maintenance still apply.
Production seams, not a production costume. Approvals, budgets, cancellation, mid-run steering, retries, checkpoint/resume — explicit knobs you wire into your own app.
One extension axis. Skills, MCP, Todo, and Memory are all plugins on the same seam you get for your own capabilities.

The design pressure throughout is restraint: if a feature can be a short user-side recipe, it stays out of the framework.

The tour

Every stop below has a full guide; each snippet runs as written.

Agents

An Agent is declarative configuration — no conversation state, safe to share, cheap to clone(). Tools, a workspace, and plugins compose directly on that configuration:

from lovia import Agent, Memory, Skills, tool
from lovia.workspace import Workspace


@tool
def light_travel_time(distance_km: float) -> str:
    """Calculate one-way light-signal delay for a distance in kilometers."""
    return f"{distance_km / 299_792.458:.2f} seconds"


agent = Agent(
    name="science-writer",
    instructions="Explain complex science with vivid, everyday analogies.",
    model="gpt-5.5",
    tools=[light_travel_time],
    workspace=Workspace.local(".", mode="readonly"),
    plugins=[
        Skills("./skills"),
        Memory(),
    ],
)

→ Agents

Running and streaming

One run, three consumption styles — and the stream handle is both async-iterable and awaitable. Iteration never raises: every stream ends with exactly one terminal event.

from lovia import Runner, events

handle = Runner.stream(
    agent,
    "How long does a signal take to reach Mars at 225 million km?",
)

async for ev in handle:
    if isinstance(ev, events.TextDelta):
        print(ev.delta, end="", flush=True)

result = await handle.result()

→ Running · Streaming

Tools

@tool wraps a typed callable as a Tool; the schema comes from signatures, docstrings, Annotated, and Pydantic Fields. One turn's calls execute concurrently by default — tools with non-reentrant side effects opt out and become execution barriers:

from typing import Annotated
from pydantic import Field
from lovia import tool


@tool(strict=True)
def search_docs(
    query: Annotated[str, "Search terms"],
    limit: Annotated[int, Field(ge=1, le=10)] = 5,
) -> list[str]:
    """Search internal documentation."""
    return []


@tool(parallel=False)
async def apply_migration(name: str) -> str:
    """Apply a database migration (never concurrently with other tools)."""
    return "applied"

The built-in web tools (read_page, http_request, web_search) fence what they fetch, so the model reads it as material rather than instructions; fence() does the same for your own tools.

→ Tools · Built-in tools

Structured output

Pass a Pydantic model, dataclass, TypedDict, or plain type; the final answer is validated — and repaired once, by default, when it doesn't parse:

from pydantic import BaseModel
from lovia import Agent, Runner


class Brief(BaseModel):
    title: str
    bullets: list[str]


agent = Agent(name="summarizer", model="glm-5.2", output_type=Brief)
result = await Runner.run(agent, "Summarize Transformer for a Python developer.")
print(result.output.title)

→ Structured output

Providers

Use model strings or provider instances. OpenAI-compatible endpoints read OPENAI_BASE_URL / OPENAI_API_KEY; Anthropic defaults to the official endpoint, reads ANTHROPIC_API_KEY, and uses ANTHROPIC_BASE_URL for non-default endpoints. Prompt caching and reasoning models are handled per endpoint, and a custom provider is a small Protocol:

from lovia import Agent, ModelSettings

agent = Agent(
    name="assistant",
    model="anthropic:<model>",
    settings=ModelSettings(temperature=0.2, max_tokens=800),
)

→ Providers & models

Multi-agent

Your task	Use	Runtime behavior
Let a specialist take over the conversation	Handoff	The specialist receives full history and continues in the same Run
Get a subtask result before the parent continues	Agent-as-tool	The child receives only the delegated prompt and returns a Tool result
Run independent work in the background	Subagents	The child runs independently and reports back later

The three alternatives below show the same researcher in each mode:

from lovia import Agent, Subagents

researcher = Agent(
    name="researcher",
    instructions="Research the given topic and return a concise report.",
    model="glm-5.2",
)

# Handoff: researcher takes over and receives the full conversation
router = Agent(
    name="router",
    instructions="Transfer to researcher when in-depth research is needed.",
    model="deepseek-v4-flash",
    handoffs=[researcher],
)

# Agent-as-tool: manager waits for the research, then answers the user itself
manager = Agent(
    name="manager",
    instructions="Ask researcher for any research needed before answering.",
    model="deepseek-v4-flash",
    tools=[researcher.as_tool(description="Research a topic and return a report.")],
)

# Subagents: assistant starts background research and keeps working
assistant = Agent(
    name="assistant",
    instructions="Run independent research in the background while drafting the answer.",
    model="deepseek-v4-flash",
    plugins=[Subagents([researcher])],
)

lovia web enables Subagents by default and reports completed work back to the original conversation.

→ Multi-agent

Human in the loop

Gate sensitive tools; resolve from your UI, a server-side policy, or an out-of-band channel — unresolved approvals deny, so runs never hang:

from lovia import Runner, events, tool


@tool(needs_approval=True)
async def refund(order_id: str, amount_cents: int) -> str:
    """Issue a refund."""
    return "refunded"


async for ev in Runner.stream(agent, "Refund order A123."):
    if isinstance(ev, events.ApprovalRequired):
        ev.approve()          # or ev.reject()

→ Tool approval

Sessions and checkpoints

Sessions persist conversations across runs; checkpoints make single runs crash-safe and idempotent — re-issuing a completed run_id replays its result without calling the model:

from lovia import CheckpointOptions, Runner, SQLiteCheckpointer, SQLiteSession

session = SQLiteSession("chat.db")
await Runner.run(agent, "My project is called Atlas.", session=session, session_id="u1")

cp = SQLiteCheckpointer("runs.db")
result = await Runner.run(
    agent,
    "Migrate the report format.",
    checkpoint=CheckpointOptions(cp, "report-migration-42"),
)

→ Sessions & checkpoints

Context compaction

Long conversations survive the window without rewriting history: compaction is view-only, keeps the prompt prefix stable for provider caches:

from lovia import Agent, Compaction

agent = Agent(
    name="companion",
    model="glm-5.2",
    context_policy=Compaction(context_window=200_000, compact_at=0.85, compact_to=0.60),
)

→ Context management

Guardrails and reliability

Guardrails veto runs at the input/output boundary. Reliability follows one placement rule — retry posture on the agent, per-run limits on the run:

from lovia import Agent, RetryPolicy, RunBudget, Runner
from lovia.exceptions import GuardrailTripped


async def must_cite(output, ctx):
    if "source:" not in str(output).lower():
        return "Missing source citation."


agent = Agent(
    name="researcher",
    model="glm-5.2",
    output_guardrails=[must_cite],
    retry=RetryPolicy(max_attempts=2)
)

result = await Runner.run(
    agent,
    "Analyze these logs.",
    budget=RunBudget(max_tool_calls=20, max_seconds=60)
)

→ Guardrails · Provider retries · Budgets & limits

Hooks and steering

Hooks observe every run event (fail-open, same types as streaming); the mailbox is the inbound dual of cancellation — push a message into a live run and the model sees it next turn. A run can even steer itself:

from lovia import Mailbox, RunContext, Runner, events
from lovia.hooks import AgentHooks

hooks = AgentHooks()


@hooks.on(events.TurnStarted)
def deadline(ev, ctx: RunContext):
    if ev.turn == 9:
        ctx.mailbox.push("Last turn: answer with what you have.")


mailbox = Mailbox()
handle = Runner.stream(agent.clone(hooks=hooks), "Analyze these logs.", mailbox=mailbox)
mailbox.push("Focus on the 5xx spike around 14:00.")  # seen next turn

→ Observability · Cancellation & steering

Workspace

File and shell tools scoped to a root, governed by one allow/ask/deny policy over paths and commands — ask decisions ride the normal approval channel. shell(background=true) runs dev servers, watchers, and long builds as session-owned background processes (poll read_process_output, stop with kill_process):

from lovia import Agent
from lovia.workspace import CommandRule, Workspace

agent = Agent(
    name="coder",
    instructions="Make small, targeted code changes.",
    model="glm-5.2",
    workspace=Workspace.local(
        ".",
        mode="coding",
        denied_paths=(".env*",),
        command_rules=(CommandRule("pytest", "allow"), CommandRule("rm -rf", "deny")),
    ),
)

→ Workspace

Plugins

One extension axis: a plugin contributes tools, prompt text, per-turn view injectors, hooks, and guardrails — never control flow:

from lovia import Agent, Skills, Todo
from lovia.plugins.mcp import MCP, MCPServerStdio

agent = Agent(
    name="builder",
    model="glm-5.2",
    plugins=[
        Todo(),
        Skills("./skills"),
        MCP(MCPServerStdio(name="web", command="uvx", args=["mcp-server-fetch"])),
    ],
)

Todo() — gives the model a checklist for multi-step work; the current list is re-shown every turn without growing the transcript.
Skills(dir) — reusable instruction bundles (SKILL.md + files): a one-line index stays in the prompt, full content loads on demand.
MCP(server) — tools from Model Context Protocol servers, stdio or HTTP, with per-server name prefixes and approval gates. For web research, try the Parallel Search MCP recipe.

Writing your own is a name plus one async setup(ctx) returning the contributions.

→ Plugins · Skills · MCP

Memory

Long-term memory across conversations — always-in-prompt Notes (facts the user stated or confirmed, never the assistant's own claims; pinned per session so they never bust the prompt cache) plus a searchable Archive, zero-config, self-tidying (a periodic dream pass merges duplicates and prunes stale facts), upgradeable one argument at a time:

from lovia import Agent, Memory
from lovia.plugins import OpenAIEmbedder

agent = Agent(name="assistant", model="glm-5.2",
              plugins=[Memory("./.lovia/memory")])

Memory("./memory")                             # stdlib keyword search (FTS5 bm25)
Memory("./memory", embedder=OpenAIEmbedder())  # + semantic arm -> hybrid recall
Memory("./memory", index=None)                 # notes only, no archive

→ Memory

Web UI

A lightweight FastAPI chat app for any agent (pip install "lovia[web]"):

lovia web --port 9000                      # python -m lovia.web works too

from lovia.web import create_app, serve

serve(create_app(agent, db_path="lovia.db"), host="127.0.0.1", port=8000)

Full chat out of the box — SSE streaming, sessions, approvals, schedules, a memory editor and file attachments; runs survive browser disconnects.
Models set up in the browser — Settings → Models saves profiles to ~/.lovia/config.json and applies changes live; lovia web --check diagnoses the connection.
Rich tool results — a tool returns ui_result(kind, props) to draw UI; tables, ECharts charts and sandboxed HTML pages come built in (show_table, show_chart, show_html).
Customizable page — ChatUI(...) and assets= change wording, logo, styles and scripts; scripts drive the page through window.lovia, and run_context= hands tools the user's identity and page context.
Headless if you prefer — everything is a JSON + SSE REST API (/api/docs); create_app(agent, ui=False) serves your own front-end.

→ Web UI · Web server · HTTP API

Evals

Behavioral test suites: a Case pairs input with checks, any function is a check, the LLM judge is just another check, and reports diff against a baseline in CI:

from lovia.eval import Case, contains, evaluate, llm_judge, tool_called

report = await evaluate(agent, [
    Case("What is the capital of France?", checks=[contains("Paris")]),
    Case("What's 23.4 * 91?", checks=[tool_called("calculator")]),
    Case("Write a haiku about spring",
         checks=[llm_judge("A 5-7-5 haiku that evokes spring")],
         samples=4, pass_threshold=0.75),
])
print(report)
assert report.passed

→ Evals

Testing

Everything runs offline against a scripted provider — real tools, real loop, canned model:

from lovia.testing import ScriptedProvider, call, text

provider = ScriptedProvider([
    call("add", {"a": 2, "b": 3}, call_id="c1"),
    text("The answer is 5."),
])

→ Testing

Examples

The examples/ directory is a numbered learning path of thirty self-contained, runnable scripts — from 01_hello.py to a terminal support bot — plus one script per built-in tool family (tools/) and the classic agentic patterns in plain Python (workflows/). Setup and the full index: examples/README.md.

Install extras

Need	Install
Core framework	`pip install lovia`
DuckDuckGo search	`pip install "lovia[ddg]"`
Tavily search	no extra — set `TAVILY_API_KEY`
MCP integration	`pip install "lovia[mcp]"`
Web UI	`pip install "lovia[web]"`
Runnable examples	`pip install "lovia[examples,web]"`
Development	`pip install -e ".[dev]"`

Development

pip install -e ".[dev]"
.venv/bin/python -m pytest
.venv/bin/python -m ruff check .
.venv/bin/python -m ruff format .
.venv/bin/python -m mypy lovia

Live provider tests are marked live_provider and stay skipped unless enabled explicitly. Contributor-facing internals are documented in docs/architecture.md.

Metadata

Release files for lovia 0.9.102

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lovia 0.9.102
File	Size	Uploaded	Provenance
lovia-0.9.102.tar.gz	3.1 MB	Oct 20, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for lovia 0.9.102
File	Interpreter	ABI	Platform	Reset
lovia-0.9.102-py3-none-any.whl 2.0 MB Oct 20, 2026 With provenance	Python 3	none	any	Details

Total release size: 5.1 MB

Release files / lovia-0.9.102.tar.gz

Download URL	lovia-0.9.102.tar.gz
Size	3.1 MB
Tags	Source
SHA-256 checksum How to use checksums	`71bccf7facbe1efd1f5002c2ec89d28b539b4aad43e37b3add131018069e628c`
BLAKE2b-256 checksum How to use checksums	`3738e09fce601cccc05e02ba54c9025feae611d7fa4d13b9c2d7b9b74a4514b9`
Upload date	Oct 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/cymoo/lovia
Publishing commit: github.com/cymoo/lovia/tree/02eda991b718bdefcbbc840a17bb028129b2d207

Workflow

Publishing configuration: github.com/cymoo/lovia/blob/02eda991b718bdefcbbc840a17bb028129b2d207/.github/workflows/ci.yml
Publishing logs: github.com/cymoo/lovia/actions/runs/39473364124/attempts/1

Artifact

Subject: lovia-0.9.102.tar.gz
SHA-256 checksum: 71bccf7facbe1efd1f5002c2ec89d28b539b4aad43e37b3add131018069e628c Verifying attestations

Release files / lovia-0.9.102-py3-none-any.whl

Download URL	lovia-0.9.102-py3-none-any.whl
Size	2.0 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`86f607655ca430ae637539c6c9e31e3242995ecdf2ef49540080ae4657fdfca7`
BLAKE2b-256 checksum How to use checksums	`863d96257ed37a8e469eb1fc159c92d698fe4c2e58e11747a3e5ad71a2033208`
Upload date	Oct 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/cymoo/lovia
Publishing commit: github.com/cymoo/lovia/tree/02eda991b718bdefcbbc840a17bb028129b2d207

Workflow

Publishing configuration: github.com/cymoo/lovia/blob/02eda991b718bdefcbbc840a17bb028129b2d207/.github/workflows/ci.yml
Publishing logs: github.com/cymoo/lovia/actions/runs/39473364124/attempts/1

Artifact

Subject: lovia-0.9.102-py3-none-any.whl
SHA-256 checksum: 86f607655ca430ae637539c6c9e31e3242995ecdf2ef49540080ae4657fdfca7 Verifying attestations

Security for lovia 0.9.102

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for lovia-0.9.102.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/cymoo/lovia
Publishing commit: github.com/cymoo/lovia/tree/02eda991b718bdefcbbc840a17bb028129b2d207

Workflow

Publishing configuration: github.com/cymoo/lovia/blob/02eda991b718bdefcbbc840a17bb028129b2d207/.github/workflows/ci.yml
Publishing logs: github.com/cymoo/lovia/actions/runs/39473364124/attempts/1

Artifact

Subject: lovia-0.9.102.tar.gz
SHA-256 checksum: 71bccf7facbe1efd1f5002c2ec89d28b539b4aad43e37b3add131018069e628c Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.