artifactr-ai 0.2.1

artifactr is a Python library for chat applications in which people and agents work on the same documents, plans and specs, with every change versioned, attributed and fed back into the agent's context.

Status: alpha, on PyPI. 0.1.0, from its original repository, was the first release, and delivered RFC-0001, the v0.1 plan. The API may still change before 1.0.

Why

In most chat applications the conversation is the only channel. artifactr adds a second: artifacts that live beside the chat and that both sides edit directly. When a person rewrites a paragraph the agent drafted, or the agent restructures a plan, the edit says something about how each side is thinking. So every edit is versioned, attributed to whoever made it, visible to every participant, and told to the agent before it acts.

Install

Python 3.12 or newer. artifactr is on PyPI as artifactr-ai, and imported as artifactr (the name artifactr on PyPI is an unrelated project):

uv add "artifactr-ai[fastapi]"

Extras: fastapi (WebSocket and REST), mcp (external agents), postgres or sqlite (SQL storage with a driver), and sql (SQL storage without one).

Example

A person edits a brief, then asks the agent for more. The agent is told about the edit before it starts, and its own edit is recorded the same way:

import asyncio

from pydantic_ai import Agent

from artifactr import (
    ArtifactWorkspace,
    InMemoryStorage,
    MarkdownArtifact,
    Runner,
    Session,
    UserActor,
    Workspaces,
)
from artifactr.core import SetFocus


class Brief(MarkdownArtifact):  # an artifact type: a Pydantic model, registered as "brief"
    pass


agent = Agent(
    "anthropic:claude-sonnet-5-5",
    deps_type=Session[None],
    capabilities=[ArtifactWorkspace(types=[Brief])],  # tools, instructions and change notes
)
runner = Runner(agent, app=None)
workspaces = Workspaces(InMemoryStorage(), types=[Brief])


async def main() -> None:
    alice = UserActor(id="u_alice", name="Alice")
    ws = await workspaces.open("acme", "launch", actor=alice)
    thread = await ws.create_thread("Launch brief")

    await ws.create(Brief(text="# Launch\n\nWe ship on Friday."), artifact_id="brief")
    await ws.commit(SetFocus(thread_id=thread.id, artifact_ids=("brief",)))

    brief = await ws.get(Brief, "brief")
    await ws.commit(brief.edit_text("Friday", "Monday"))  # version 2, by Alice

    sent = await runner.send(ws, thread.id, "Add a risks section to the brief.")
    if sent.run is not None:
        await sent.run.wait()  # the agent is told what Alice changed before it starts

    for envelope in await ws.read():
        print(envelope.seq, envelope.actor.kind, envelope.event.type)


asyncio.run(main())

It needs ANTHROPIC_API_KEY, or any other pydantic-ai model. The log it prints shows Alice's edit, the agent's run, its tool call and its own edit, in order and attributed.

Try it

examples/docplan is a complete application built on the library: a person and an agent co-write a document and plan its work, over WebSocket, REST and MCP, with a terminal client. From the root of a clone of lattice:

make install
export ANTHROPIC_API_KEY=...
uv run docplan-serve            # in one terminal
uv run docplan --user alice     # in another

Set DOCPLAN_DATABASE_URL (for example sqlite+aiosqlite:///docplan.db) to keep its workspaces in a database instead of memory.

What you get

• Artifact types as Pydantic models. Subclass Artifact; versioning, validation, patches, change summaries and agent tools come from the library.
• One write path. Every change, from any participant and any surface, is a command committed through a tenant-scoped workspace handle, checked against the artifact's version and appended to the workspace's ordered log.
• Proposals that don't block. Artifact types can make agents propose instead of edit; people accept, edit or reject whenever they like, and the agent hears the outcome.
• An agent that follows along. One pydantic-ai capability adds the artifact tools, instructions rendered fresh for every request, notes on what others changed, steering mid-run, and pauses for questions and approvals.
• Live output apart from history. Token-level output streams to watchers; the log holds only durable facts.
• Surfaces that behave the same. A WebSocket thread protocol and REST for your frontend, and MCP for external agents, all through one command handler.
• Storage in memory, SQLite or PostgreSQL, behind one protocol.
• Rules you can read and port. A pure, synchronous core pinned by language-neutral conformance fixtures, with 100% branch coverage and pyright strict.

Documentation

The documentation is artifactr's section of lattice's site, at https://lattice.alexnodeland.com/artifactr/. It is built from docs/artifactr/ and published from main on every push; run moon run lattice:docs-serve to read it locally at http://localhost:8000.

• Getting started and the guides: artifact types, workspaces, storage, the agent, live output, serving, MCP, security and testing.
• Architecture: concepts, layers, the write path, the agent, tenancy and concurrency.
• Thread protocol v1: the WebSocket, REST and MCP contracts, with a generated JSON Schema.
• Architecture decision records: why each part is the way it is.
• RFCs: proposals and the v0.1 build plan.
• Brand: the mark, colours and type.

Built on

Pydantic, pydantic-ai, SQLAlchemy, FastAPI and the MCP Python SDK.

Contributing

See CONTRIBUTING.md for setup, the trunk-based workflow, and the RFC and ADR process.

License

MIT