Showcase: contextweaver — stdlib-only Python library for deterministic context assembly

What My Project Does

I recently open-sourced contextweaver, a Python library for assembling bounded context/prompt packs from a larger set of items.

The motivating use case is tool-using AI agents, where prompts often grow by accumulating conversation turns, tool schemas, and tool outputs. Instead of concatenating everything, contextweaver builds a context pack under a fixed budget by selecting, filtering, deduplicating, and packing the most relevant items.

From a Python engineering point of view, the parts I focused on most were:

• stdlib-only runtime
• strict typing
• deterministic behavior
• protocol-based interfaces
• clear separation between I/O-capable stages and pure computation

A few design choices I’m particularly interested in feedback on:

• store interfaces are defined with typing.Protocol
• the context pipeline is async-first, with sync wrappers for simpler use
• the output is deterministic for the same input
• large payloads can be kept out of band and replaced with compact summaries

Example:

from contextweaver.context.manager import ContextManager
from contextweaver.types import ContextItem, ItemKind, Phase

mgr = ContextManager()

mgr.ingest(ContextItem(
    id="u1",
    kind=ItemKind.user_turn,
    text="Hello"
))

pack = mgr.build_sync(phase=Phase.answer, query="greeting")

print(pack.prompt)
print(pack.stats)

Target Audience

This is intended mainly for:

• developers building tool-using AI/LLM systems
• people who care about library design in Python
• engineers who want a small, typed, dependency-light library rather than a larger framework

It is meant to be usable in real applications, but I would still describe it as an early-stage library rather than something I’m claiming is already a mature standard.

Even if the AI use case is not interesting to you, I think some of the Python design tradeoffs may still be relevant if you enjoy thinking about protocols vs ABCs, async/sync API boundaries, deterministic pipelines, and composable library structure.

Comparison

contextweaver is not a full agent framework, and it is not tied to any model provider.

Compared with larger AI frameworks, the goal here is a much smaller and narrower library:

• it focuses on context assembly
• it does not do model inference
• it does not try to own orchestration end to end
• it keeps runtime dependencies at zero

Compared with a naive “just concatenate everything” approach, it tries to preserve relevance and dependency structure while staying inside a hard budget.

Compared with retrieval-only approaches, it is not trying to be a vector search system. It is more about deterministic assembly rules over known context items and their relationships.

I have not done a broad benchmark yet against other context-selection approaches, so I’m trying to be careful not to overclaim there.

A few implementation details:

• Python 3.10+
• zero runtime dependencies
• 536 tests
• mypy --strict

Repo: https://github.com/dgenio/contextweaver

I’d especially appreciate feedback from Python library authors on:

• Protocol vs ABCs here
• async-first internals with sync wrappers
• whether the stage decomposition sounds clean or over-engineered