everalgo-core

Foundation distribution of EverAlgo — data types, LLM client + provider routing, prompt helpers, and testing utilities shared by every other everalgo-* package.

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

Install

pip install everalgo-core

What this distribution provides

Quick start

from everalgo.llm import LLMConfig, build_client
from everalgo.llm.types import ChatMessage

config = LLMConfig(model="gpt-4o-mini", api_key="sk-...", base_url="https://api.openai.com/v1")
client = build_client(config)

response = await client.chat(
    messages=[ChatMessage(role="user", content="Hello")],
)
print(response.content)

Using FakeLLMClient in tests

import json
from everalgo.llm.types import ChatResponse
from everalgo.testing import FakeLLMClient

# Scripted mode — responses are returned in order
fake = FakeLLMClient(responses=[
    ChatResponse(content=json.dumps({"title": "T", "content": "C", "summary": "S"}), model="fake"),
])

# Handler mode — full control over each call
from everalgo.llm.types import ChatMessage as LLMMsg
def handler(messages: list[LLMMsg], **_) -> ChatResponse:
    return ChatResponse(content="ok", model="fake")

fake = FakeLLMClient(handler=handler)
print(fake.call_count)  # 0

LLM utilities

everalgo.llm.format and everalgo.llm.parse provide prompt-rendering helpers used by boundary detection and every extractor.

everalgo.llm.format — timestamp rendering

from everalgo.llm.format import format_atomic_fact_time, format_message_timestamp, format_natural_language_time

# ISO 8601 UTC anchor — used as inline message prefix in prompts
# e.g. "2023-11-14T22:13:20Z"
ts_str = format_message_timestamp(1_700_000_000_000)

# Human-readable label for LLM time-of-day reasoning
# Example output: "November 14, 2023 (Tuesday) at 10:13 PM UTC"
label = format_natural_language_time(1_700_000_000_000, lang="en")

everalgo.llm.parse — robust JSON extraction

from everalgo.llm.parse import parse_llm_json_object

# Three-tier fallback: fence block → direct loads → outermost braces
result = parse_llm_json_object('```json\n{"key": "value"}\n```')
# → {"key": "value"}

parse_llm_json_object(raw: str) -> dict[str, Any] tries each strategy in order and raises ValueError if all three fail.

everalgo._tokenize — token counting

count_tokens(text: str) → int and force_split(text: str, *, max_tokens: int) → list[str] are module-private utilities (used internally by boundary algorithms; not part of the public everalgo.* surface). They use OpenAI o200k_base encoding via tiktoken.

API surface

Related distributions

• everalgo-boundary — uses MemCell, ChatMessage, LLMClient
• everalgo-clustering — uses LLMClient and core prompt helpers
• everalgo-rank — uses RankInput, RankOutput, Candidate, ScoredItem
• everalgo-user-memory — uses all user-side types + LLMClient
• everalgo-agent-memory — uses agent-side types + LLMClient