Skip to main content

everalgo-boundary

Boundary detection for EverAlgo — cuts a conversation into coherent MemCell slices with an LLM, either in one batch call or one message at a time. Agent trajectories with tool calls and tool results go through the same class: only the chat messages reach the model, and the tool items stay in the cells.

See the umbrella project: EverAlgo monorepo and the architecture document at docs/concepts/architecture.md.

Install

pip install everalgo-boundary

everalgo-user-memory and everalgo-agent-memory both depend on this package and re-export BoundaryDetector unchanged.

What this distribution provides

Symbol Role
BoundaryDetector Class binding an LLM client: adetect / detect (batch, over ConversationItem), adetect_step / detect_step (incremental, over ChatMessage)
adetect_boundaries Async function behind BoundaryDetector.adetect: (Sequence[ConversationItem], *, llm, is_final, ...) → DetectionResult
detect_boundaries Sync bridge over adetect_boundaries (asgiref.async_to_sync); never call it inside a running event loop
adetect_boundary_step Async function behind BoundaryDetector.adetect_step: single-step boundary decision → BoundaryDecision
DetectionResult NamedTuple(cells: list[MemCell], tail: list[ConversationItem], tail_complete: bool | None)

Tool items

adetect_boundaries renders only the ChatMessage items for the model and carries its cuts back to the full list: tool items between two chat messages go with the earlier one, tool items ahead of the first chat message with the first cell, and trailing tool items into the tail (into the last cell when is_final=True). Every item lands exactly once. Without any ChatMessage no LLM is called and every item goes to the tail.

Hard limits

Both paths cut without the model once a window reaches a hard limit: 65536 tokens or 500 messages by default (hard_token_limit / hard_msg_limit on the batch path, hard_token_limit / hard_message_limit on adetect_step).

Prompts

Each model call sends two messages. The system message holds the rules — BATCH_BOUNDARY_DETECT_SYSTEM_PROMPT or STEP_BOUNDARY_DETECT_SYSTEM_PROMPT in everalgo.boundary.prompts.en.chat — and is the same text on every call, so a prompt cache can share all of it. The user message holds only the data, rendered from BATCH_BOUNDARY_DETECT_USER_PROMPT (<messages count="N">) or STEP_BOUNDARY_DETECT_USER_PROMPT (<conversation_history>, <time_gap>, <new_messages>). Each message line is [N] [YYYY-MM-DD HH:MM UTC (Weekday)] speaker: text on the batch path and the same without [N] on the step path. Batch records escape XML delimiters in names and content, indent continuation lines, and retain empty content as [N] [empty message]. Material inside these records is data, not instructions to the detector.

The batch input is an open streaming window of one or more messages, not a finished conversation. Topic boundaries and tail completion are independent: boundaries=[] does not imply tail_complete=True. The tail needs evidence that its exchange or task has concluded; a workflow opening or intermediate action stays incomplete even if that individual action succeeded. A single message can still be complete when it states a final outcome or a self-contained fact. A closed status exchange can be complete while the work it discusses is unfinished; this differs from executing that workflow. Related feedback stays with the topic it refers to. The prompt limits reasoning to two to three English words of tail evidence, without topic lists, message ranges, or rule explanations. This is a prompt-level output budget; the reply schema remains unchanged.

custom_instructions= on adetect_boundaries, adetect_boundary_step and the BoundaryDetector methods adds the host's text to the bundled rules, never replacing them: it is placed verbatim, never rendered as a template, in a <custom_instructions> block that is always the system message's last, and None or a blank string leaves it out. The user message is unchanged and always rendered by the operator. There is no prompt=: the bundled rules cannot be replaced per call.

Quick start

import asyncio
import json

from everalgo.boundary import adetect_boundaries
from everalgo.testing.fake_llm import FakeLLMClient
from everalgo.types import ChatMessage

_BOUNDARY_JSON = json.dumps(
    {"reasoning": "Question unanswered", "boundaries": [], "tail_complete": False}
)

async def main() -> None:
    # One scripted reply per LLM call; `llm.achat` returns the reply text (see `everalgo.llm.LLMClient`).
    fake = FakeLLMClient(responses=[_BOUNDARY_JSON, _BOUNDARY_JSON])
    messages = [
        ChatMessage(id="m1", role="user",   content="Let's talk about deployment.",     timestamp=1_700_000_000_000, sender_id="u_alice"),
        ChatMessage(id="m2", role="assistant", content="Sure — what's the target env?",  timestamp=1_700_000_001_000, sender_id="assistant"),
        ChatMessage(id="m3", role="user",   content="K8s. Which deployment strategy should I use?", timestamp=1_700_000_002_000, sender_id="u_alice"),
    ]

    # Streaming: hold `tail` between calls; pass prior tail + new messages each time.
    result = await adetect_boundaries(messages, llm=fake)
    cells, tail, tail_complete = result  # NamedTuple unpacking

    # `tail_complete` is the LLM's verdict on the tail, not a restatement of it being non-empty: True
    # means the trailing segment already forms a complete episode, so it can be closed now; False
    # means it is not complete yet (it opens a topic, is an intermediate task step, or is only media placeholders, a bare "ok",
    # a system notification, an ambiguous 30-min-to-4-hour gap), so hold it for the next batch.
    # `None` means no path judged it — see the DetectionResult docstring.

    # End-of-session: tail is forced into the last cell.
    result = await adetect_boundaries(messages, llm=fake, is_final=True)
    assert result.tail == []
    for mc in result.cells:
        print(mc.timestamp, len(mc.items))


asyncio.run(main())

The streaming state machine

adetect_boundaries deliberately holds back trailing messages as tail — the LLM cannot know whether a conversation continues beyond the last seen message. The caller maintains state:

tail: list[ConversationItem] = []

for batch in incoming_batches:
    result = await adetect_boundaries(tail + batch, llm=client)
    await persist(result.cells)
    tail = result.tail

# Session ends — flush everything.
final = await adetect_boundaries(tail, llm=client, is_final=True)
await persist(final.cells)

Failures

Each call makes one LLM request and validates the reply against a strict pydantic model, which it also passes as response_format. A reply that does not fit — not JSON, a missing or extra key, a non-integer boundary — raises everalgo.llm.LLMOutputError; nothing is retried, and the client's own exceptions propagate unchanged. Retry policy belongs to the caller.

Tokenizer utilities

Boundary detection counts tokens with everalgo.utils.count_tokens (in everalgo-core), which uses OpenAI's o200k_base encoding via tiktoken.

Stubs

WorkspaceMemCellExtractor (Jira / Email / Confluence) is a placeholder in v0.x — all methods raise NotImplementedError. It is deliberately excluded from everalgo.boundary.__all__; import it from everalgo.boundary.workspace directly if you need the reserved name. Implementation lands in a future minor bump when the RawData contract is finalised.

Metadata

Release files for everalgo-boundary 0.4.1

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

Source distribution (sdist)

Source distribution for everalgo-boundary 0.4.1
File Size Uploaded Provenance Actions
everalgo_boundary-0.4.1.tar.gz 50.9 kB Without provenance Details for everalgo_boundary-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for everalgo-boundary 0.4.1
File Interpreter ABI Platform Actions
everalgo_boundary-0.4.1-py3-none-any.whl Python 3 none any Details for everalgo_boundary-0.4.1-py3-none-any.whl

Total release size: 81.9 kB

Release files / everalgo_boundary-0.4.1.tar.gz

Download URL everalgo_boundary-0.4.1.tar.gz
Size 50.9 kB
Tags Source
SHA-256 checksum
How to use checksums
cf2252dff844f89a1825761a2cd709fb01d0acbf604e7bfc7ab3f107dd62dc41
BLAKE2b-256 checksum
How to use checksums
b7ca45268e061fbb7b0914882c7bb86b17a45539b1e073cc59f6c3c3cb99da6a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.12

Release files / everalgo_boundary-0.4.1-py3-none-any.whl

Download URL everalgo_boundary-0.4.1-py3-none-any.whl
Size 31.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d3c7b3441983e7eba5da24e8284b47c1b23ee38eda443ec8b826a95409782413
BLAKE2b-256 checksum
How to use checksums
7d1fc5d55f1d66ea989385776ef5881a1368572099d67e9f78cb0cc2faea5bd7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.12

Security for everalgo-boundary 0.4.1

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page