everalgo-core 0.1.0__tar.gz

everalgo_core-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+wheels/
+
+# Environments
+.env
+.env.local
+.venv
+env/
+venv/
+
+# uv
+.uv/
+
+# Test / coverage / cache
+.pytest_cache/
+.cache
+.coverage
+.coverage.*
+coverage.xml
+report.xml
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+
+# Type checkers / linters
+.mypy_cache/
+.dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# IDE / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Logs
+*.log
+
+# Project local artifacts (placed under local/ per project convention)
+local/
+
+# Claude Code session-local state (scheduled tasks, agent caches, locks)
+.claude/

everalgo_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this package are documented here. Format follows
+[Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/). Versioning
+follows [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `MemCell` pydantic model: ordered `items: list[ConversationItem]` slice produced by boundary detection, plus `timestamp` (Unix epoch ms of the closing item).
+- `ConversationItem` discriminated union (`ChatMessage | ToolCallRequest | ToolCallResult`) keyed on the `kind` field.
+- `ChatMessage` with `kind="text"` discriminator, multimodal `content: str | list[ContentBlock]`, required `id`, `sender_id`, `sender_name`, and ms-epoch `timestamp`.
+- `ContentBlock` / `TextContent` for multimodal message payloads.
+- `Episode`, `Foresight`, `AtomicFact`, `Profile` user-memory output types with `ConfigDict(extra="allow")` so additional LLM-emitted keys are preserved without a schema bump.
+- `AgentCase`, `AgentSkill` agent-memory output types; `ToolCall`, `ToolCallFunction`, `ToolCallRequest`, `ToolCallResult` agent-trajectory wire types.
+- `Candidate`, `FactCandidate`, `ScoredItem`, `RankInput`, `RankOutput` ranking I/O types.
+- `ParsedContent`, `RawData`, `RawFile`, `KnowledgeMemory` types reserved for the parser and knowledge distributions.
+- `LLMClient` Protocol (async-first: `achat` / `achat_stream`; sync bridge via `asgiref.async_to_sync`).
+- `ChatMessage` (LLM-layer), `ChatResponse`, `Usage` wire types for the LLM facade.
+- `LLMConfig` pydantic model carrying model name, base URL, API key, and per-call timeout.
+- `LLMError` base exception with provider-neutral subclass hierarchy.
+- `build_client` factory that auto-detects provider from `LLMConfig.base_url`.
+- `SensitiveHeadersFilter`: redacts authorization-style values from log `record.args` mappings; attached to the `everalgo.llm` logger by default (ADR-013).
+- `render_prompt` helper: string-replace template rendering that tolerates literal `{` / `}` in template bodies without raising `KeyError`.
+- `everalgo.testing.FakeLLMClient`: deterministic LLM replay via a call queue; raises `AssertionError` on unexpected calls.
+- `everalgo.testing.CallRecord`: frozen record of a single fake LLM call (prompt, model, usage).
+- `everalgo.testing.assert_episode_shape`, `assert_foresight_shape`, `assert_atomic_fact_shape`, `assert_profile_shape`: structural assertion helpers for memory output types.
+
+### Changed
+
+- LLM binding simplified to instance-only injection: `build_client` / constructor `llm=` parameter is the sole binding path. The prior 4-layer resolution (configure / use / current / resolve) was removed in favour of the pattern used by `openai-python`, `anthropic-sdk-python`, LangChain, and Instructor.
+
+[Unreleased]: https://github.com/EverMind-AI/EverAlgo/compare/main...HEAD

everalgo_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EverMind
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

everalgo_core-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: everalgo-core
+Version: 0.1.0
+Summary: EverAlgo foundation: types, LLM client + providers, prompt validators, testing helpers.
+Project-URL: Homepage, https://github.com/EverMind-AI/EverAlgo
+Project-URL: Repository, https://github.com/EverMind-AI/EverAlgo
+Project-URL: Issues, https://github.com/EverMind-AI/EverAlgo/issues
+Project-URL: Documentation, https://github.com/EverMind-AI/EverAlgo/tree/main/packages/everalgo-core
+Project-URL: Changelog, https://github.com/EverMind-AI/EverAlgo/blob/main/packages/everalgo-core/CHANGELOG.md
+Author: EverMind
+License-Expression: MIT
+License-File: LICENSE
+Keywords: algorithm,everalgo,llm,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: openai>=1.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: tiktoken>=0.7
+Description-Content-Type: text/markdown
+
+# 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](../../README.md) and the architecture document at [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md).
+
+## Install
+
+```bash
+pip install everalgo-core
+```
+
+## What this distribution provides
+
+| Subpackage | What it contains |
+|---|---|
+| `everalgo.types` | All shared data types: `MemCell`, `ChatMessage`, `ConversationItem`, `Episode`, `Foresight`, `AtomicFact`, `Profile`, `AgentCase`, `AgentSkill`, `RankInput`, `RankOutput`, `Candidate`, `ScoredItem`, `ParsedContent`, `RawFile`, tool-call types |
+| `everalgo.llm` | `LLMClient` Protocol, `LLMConfig`, `ChatMessage` / `ChatResponse` / `Usage`, `LLMError`, `build_client` factory |
+| `everalgo.llm.format` | `format_message_timestamp`, `format_natural_language_time` — timestamp rendering for LLM prompts |
+| `everalgo.llm.parse` | `parse_llm_json_object` — three-tier robust JSON-object extraction |
+| `everalgo.llm.providers.openai_compat` | `OpenAICompatClient` — wraps `openai.AsyncOpenAI` |
+| `everalgo.prompts` | `render_prompt` — shared template substitution helper |
+| `everalgo.testing` | `FakeLLMClient`, `CallRecord`, and `assert_*_shape` structural assertion helpers |
+
+## Quick start
+
+```python
+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
+
+```python
+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"}), 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
+
+```python
+from everalgo.llm.format import 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
+
+```python
+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`](https://github.com/openai/tiktoken).
+
+## API surface
+
+| Symbol | Module | Role |
+|---|---|---|
+| `MemCell` | `everalgo.types` | Boundary-detected conversation slice; `items: list[ConversationItem]`, `timestamp: int` |
+| `ChatMessage` | `everalgo.types` | Chat wire type: `id`, `role`, `content`, `timestamp`, `sender_id`, `sender_name` |
+| `ConversationItem` | `everalgo.types` | `ChatMessage \| ToolCallRequest \| ToolCallResult` discriminated union |
+| `Episode` / `Foresight` / `AtomicFact` / `Profile` | `everalgo.types` | User-side memory output types |
+| `AgentCase` / `AgentSkill` | `everalgo.types` | Agent-side memory output types |
+| `RankInput` / `RankOutput` / `Candidate` / `ScoredItem` | `everalgo.types` | Rank I/O contracts |
+| `LLMClient` | `everalgo.llm` | Protocol — `chat(messages, *, model=None, ...) → ChatResponse` |
+| `LLMConfig` | `everalgo.llm` | `model`, `api_key` (SecretStr), `base_url`, `temperature`, `max_tokens`, `timeout` |
+| `build_client` | `everalgo.llm` | Factory: `LLMConfig → LLMClient` (returns `OpenAICompatClient`) |
+| `LLMError` | `everalgo.llm` | Base exception raised by all providers |
+| `OpenAICompatClient` | `everalgo.llm.providers.openai_compat` | Wraps `openai.AsyncOpenAI`; no retry logic |
+| `format_message_timestamp` | `everalgo.llm.format` | ISO 8601 UTC string from a millisecond timestamp |
+| `format_natural_language_time` | `everalgo.llm.format` | Human-readable timestamp label; `lang="en"` or `"zh"` |
+| `parse_llm_json_object` | `everalgo.llm.parse` | Robust JSON-object parser with three-tier fallback |
+| `render_prompt` | `everalgo.prompts` | Template substitution for `{placeholder}` patterns |
+| `FakeLLMClient` | `everalgo.testing` | In-memory `LLMClient` double; `responses=[...]` or `handler=callable` |
+| `CallRecord` | `everalgo.testing` | Single recorded `chat()` invocation (for test assertions) |
+| `assert_episode_shape` | `everalgo.testing` | Structural assertion: required `Episode` fields are non-empty |
+| `assert_foresight_shape` | `everalgo.testing` | Structural assertion for `Foresight` |
+| `assert_atomic_fact_shape` | `everalgo.testing` | Structural assertion for `AtomicFact` |
+| `assert_profile_shape` | `everalgo.testing` | Structural assertion for `Profile` |
+
+## Related distributions
+
+- [`everalgo-boundary`](../everalgo-boundary/) — uses `MemCell`, `ChatMessage`, `LLMClient`
+- [`everalgo-clustering`](../everalgo-clustering/) — uses `MemCell`, `LLMClient`
+- [`everalgo-rank`](../everalgo-rank/) — uses `RankInput`, `RankOutput`, `Candidate`, `ScoredItem`
+- [`everalgo-user-memory`](../everalgo-user-memory/) — uses all user-side types + `LLMClient`
+- [`everalgo-agent-memory`](../everalgo-agent-memory/) — uses agent-side types + `LLMClient`

everalgo_core-0.1.0/README.md

@@ -0,0 +1,127 @@
+# 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](../../README.md) and the architecture document at [`docs/concepts/architecture.md`](../../docs/concepts/architecture.md).
+
+## Install
+
+```bash
+pip install everalgo-core
+```
+
+## What this distribution provides
+
+| Subpackage | What it contains |
+|---|---|
+| `everalgo.types` | All shared data types: `MemCell`, `ChatMessage`, `ConversationItem`, `Episode`, `Foresight`, `AtomicFact`, `Profile`, `AgentCase`, `AgentSkill`, `RankInput`, `RankOutput`, `Candidate`, `ScoredItem`, `ParsedContent`, `RawFile`, tool-call types |
+| `everalgo.llm` | `LLMClient` Protocol, `LLMConfig`, `ChatMessage` / `ChatResponse` / `Usage`, `LLMError`, `build_client` factory |
+| `everalgo.llm.format` | `format_message_timestamp`, `format_natural_language_time` — timestamp rendering for LLM prompts |
+| `everalgo.llm.parse` | `parse_llm_json_object` — three-tier robust JSON-object extraction |
+| `everalgo.llm.providers.openai_compat` | `OpenAICompatClient` — wraps `openai.AsyncOpenAI` |
+| `everalgo.prompts` | `render_prompt` — shared template substitution helper |
+| `everalgo.testing` | `FakeLLMClient`, `CallRecord`, and `assert_*_shape` structural assertion helpers |
+
+## Quick start
+
+```python
+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
+
+```python
+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"}), 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
+
+```python
+from everalgo.llm.format import 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
+
+```python
+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`](https://github.com/openai/tiktoken).
+
+## API surface
+
+| Symbol | Module | Role |
+|---|---|---|
+| `MemCell` | `everalgo.types` | Boundary-detected conversation slice; `items: list[ConversationItem]`, `timestamp: int` |
+| `ChatMessage` | `everalgo.types` | Chat wire type: `id`, `role`, `content`, `timestamp`, `sender_id`, `sender_name` |
+| `ConversationItem` | `everalgo.types` | `ChatMessage \| ToolCallRequest \| ToolCallResult` discriminated union |
+| `Episode` / `Foresight` / `AtomicFact` / `Profile` | `everalgo.types` | User-side memory output types |
+| `AgentCase` / `AgentSkill` | `everalgo.types` | Agent-side memory output types |
+| `RankInput` / `RankOutput` / `Candidate` / `ScoredItem` | `everalgo.types` | Rank I/O contracts |
+| `LLMClient` | `everalgo.llm` | Protocol — `chat(messages, *, model=None, ...) → ChatResponse` |
+| `LLMConfig` | `everalgo.llm` | `model`, `api_key` (SecretStr), `base_url`, `temperature`, `max_tokens`, `timeout` |
+| `build_client` | `everalgo.llm` | Factory: `LLMConfig → LLMClient` (returns `OpenAICompatClient`) |
+| `LLMError` | `everalgo.llm` | Base exception raised by all providers |
+| `OpenAICompatClient` | `everalgo.llm.providers.openai_compat` | Wraps `openai.AsyncOpenAI`; no retry logic |
+| `format_message_timestamp` | `everalgo.llm.format` | ISO 8601 UTC string from a millisecond timestamp |
+| `format_natural_language_time` | `everalgo.llm.format` | Human-readable timestamp label; `lang="en"` or `"zh"` |
+| `parse_llm_json_object` | `everalgo.llm.parse` | Robust JSON-object parser with three-tier fallback |
+| `render_prompt` | `everalgo.prompts` | Template substitution for `{placeholder}` patterns |
+| `FakeLLMClient` | `everalgo.testing` | In-memory `LLMClient` double; `responses=[...]` or `handler=callable` |
+| `CallRecord` | `everalgo.testing` | Single recorded `chat()` invocation (for test assertions) |
+| `assert_episode_shape` | `everalgo.testing` | Structural assertion: required `Episode` fields are non-empty |
+| `assert_foresight_shape` | `everalgo.testing` | Structural assertion for `Foresight` |
+| `assert_atomic_fact_shape` | `everalgo.testing` | Structural assertion for `AtomicFact` |
+| `assert_profile_shape` | `everalgo.testing` | Structural assertion for `Profile` |
+
+## Related distributions
+
+- [`everalgo-boundary`](../everalgo-boundary/) — uses `MemCell`, `ChatMessage`, `LLMClient`
+- [`everalgo-clustering`](../everalgo-clustering/) — uses `MemCell`, `LLMClient`
+- [`everalgo-rank`](../everalgo-rank/) — uses `RankInput`, `RankOutput`, `Candidate`, `ScoredItem`
+- [`everalgo-user-memory`](../everalgo-user-memory/) — uses all user-side types + `LLMClient`
+- [`everalgo-agent-memory`](../everalgo-agent-memory/) — uses agent-side types + `LLMClient`

everalgo_core-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "everalgo-core"
+version = "0.1.0"
+description = "EverAlgo foundation: types, LLM client + providers, prompt validators, testing helpers."
+requires-python = ">=3.12"
+license = "MIT"
+readme = "README.md"
+authors = [{ name = "EverMind" }]
+keywords = ["llm", "memory", "algorithm", "everalgo"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "openai>=1.0",
+  "pydantic>=2.7",
+  "tiktoken>=0.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/EverMind-AI/EverAlgo"
+Repository = "https://github.com/EverMind-AI/EverAlgo"
+Issues = "https://github.com/EverMind-AI/EverAlgo/issues"
+Documentation = "https://github.com/EverMind-AI/EverAlgo/tree/main/packages/everalgo-core"
+Changelog = "https://github.com/EverMind-AI/EverAlgo/blob/main/packages/everalgo-core/CHANGELOG.md"
+
+# `everalgo` here is a PEP 420 namespace; hatchling packages the directory
+# tree under `src/everalgo/` belonging to this distribution only.
+# Reference: https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pyproject.toml
+[tool.hatch.build.targets.wheel]
+packages = ["src/everalgo"]

everalgo_core-0.1.0/src/everalgo/_tokenize.py

@@ -0,0 +1,45 @@
+"""Shared tokenizer utilities using OpenAI ``o200k_base`` encoding (GPT-4o / o-series).
+
+Module-private — internal shared implementation; not part of the public ``everalgo.*`` API.
+"""
+
+from __future__ import annotations
+
+import tiktoken
+
+_ENCODING_NAME = "o200k_base"
+_tokenizer_cache: tiktoken.Encoding | None = None
+
+
+def _get_tokenizer() -> tiktoken.Encoding:
+    """Return the shared ``o200k_base`` encoding, initialising on first call."""
+    global _tokenizer_cache
+    if _tokenizer_cache is None:
+        _tokenizer_cache = tiktoken.get_encoding(_ENCODING_NAME)
+    return _tokenizer_cache
+
+
+def count_tokens(text: str) -> int:
+    """Count tokens in ``text`` under ``o200k_base``. Empty string returns 0."""
+    if not text:
+        return 0
+    return len(_get_tokenizer().encode(text))
+
+
+def force_split(text: str, *, max_tokens: int) -> list[str]:
+    """Split ``text`` into chunks of at most ``max_tokens`` tokens (no semantic awareness).
+
+    Returns ``[]`` for empty input, ``[text]`` when the whole string already fits.
+
+    Raises:
+        ValueError: If ``max_tokens <= 0``.
+    """
+    if max_tokens <= 0:
+        raise ValueError(f"max_tokens must be positive, got {max_tokens}")
+    if not text:
+        return []
+    tokenizer = _get_tokenizer()
+    token_ids = tokenizer.encode(text)
+    if len(token_ids) <= max_tokens:
+        return [text]
+    return [tokenizer.decode(token_ids[i : i + max_tokens]) for i in range(0, len(token_ids), max_tokens)]

everalgo_core-0.1.0/src/everalgo/config.py

@@ -0,0 +1,4 @@
+"""Global configuration for the EverAlgo algorithm library.
+
+See ``AGENTS.md`` §5 (Code Style) for the LLM injection contract.
+"""

everalgo_core-0.1.0/src/everalgo/llm/__init__.py

@@ -0,0 +1,64 @@
+"""LLM facade — chat-style abstraction over OpenAI-compatible providers.
+
+Public surface, grouped by role:
+
+- protocol:    LLMClient
+- data:        ChatMessage, ChatResponse, ContentPart, ImageUrlInner, ImageUrlPart, TextPart, Usage, LLMConfig
+- helpers:     image_url_part_from_bytes
+- errors:      LLMError
+- factory:     build_client
+- format/parse: Lang, format_message_timestamp, format_natural_language_time, parse_llm_json_object
+
+LLM binding is instance-only: every operator accepts ``llm: LLMClient`` at construction time.
+There is no global default, no scoped context-var override, and no per-call resolution layer.
+This matches the industry convention used by openai-python, anthropic-sdk-python, LangChain,
+Instructor, and scikit-learn (5/7 dominant SDKs bind the client at construction time only).
+"""
+
+from __future__ import annotations
+
+import logging
+
+from everalgo.llm._filters import SensitiveHeadersFilter
+from everalgo.llm.config import LLMConfig
+from everalgo.llm.errors import LLMError
+from everalgo.llm.factory import build_client
+from everalgo.llm.format import Lang, format_message_timestamp, format_natural_language_time
+from everalgo.llm.parse import parse_llm_json_object
+from everalgo.llm.protocols import LLMClient
+from everalgo.llm.types import (
+    ChatMessage,
+    ChatResponse,
+    ContentPart,
+    ImageUrlInner,
+    ImageUrlPart,
+    TextPart,
+    Usage,
+    image_url_part_from_bytes,
+)
+
+# Library logging setup (ADR-013). NullHandler suppresses "No handlers" noise
+# under Python's library-logging contract; SensitiveHeadersFilter redacts
+# authorization-style values from `record.args` mappings, default-on.
+_logger = logging.getLogger(__name__)
+_logger.addHandler(logging.NullHandler())
+_logger.addFilter(SensitiveHeadersFilter())
+
+__all__ = [
+    "ChatMessage",
+    "ChatResponse",
+    "ContentPart",
+    "ImageUrlInner",
+    "ImageUrlPart",
+    "LLMClient",
+    "LLMConfig",
+    "LLMError",
+    "Lang",
+    "TextPart",
+    "Usage",
+    "build_client",
+    "format_message_timestamp",
+    "format_natural_language_time",
+    "image_url_part_from_bytes",
+    "parse_llm_json_object",
+]  # fmt: skip

everalgo_core-0.1.0/src/everalgo/llm/_filters.py

@@ -0,0 +1,39 @@
+"""Logging filters for ``everalgo.llm`` — redacts sensitive header values."""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Final
+
+__all__ = ["SensitiveHeadersFilter"]
+
+
+_REDACTED: Final[str] = "<redacted>"
+
+# Matches header / parameter names that conventionally carry credentials.
+# Case-insensitive; covers Authorization, Api-Key / api_key, X-Api-Key,
+# Bearer tokens. Keep narrow — false positives leak data; false negatives
+# leak credentials.
+_SENSITIVE_KEY_PATTERN: Final[re.Pattern[str]] = re.compile(
+    r"(authorization|api[-_]?key|x-api-key|bearer)",
+    re.IGNORECASE,
+)
+
+
+class SensitiveHeadersFilter(logging.Filter):
+    """Redact sensitive header values in ``LogRecord.args`` mappings.
+
+    Default-attached to ``everalgo.llm``; ``filter()`` always returns ``True`` — it mutates payload, never
+    drops records. Only mapping-shaped ``record.args`` are scanned; tuple / ``None`` args pass through.
+    Does not scan request/response bodies (body PII is out of scope for a header filter).
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Redact sensitive entries from ``record.args`` in place; always returns ``True``."""
+        if isinstance(record.args, dict):
+            record.args = {
+                key: (_REDACTED if _SENSITIVE_KEY_PATTERN.search(str(key)) else value)
+                for key, value in record.args.items()
+            }
+        return True

everalgo_core-0.1.0/src/everalgo/llm/config.py

@@ -0,0 +1,21 @@
+"""LLM client configuration."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field, SecretStr
+
+
+class LLMConfig(BaseModel):
+    """OpenAI-compatible LLM client configuration.
+
+    ``api_key`` uses ``SecretStr`` so repr / serialization never leaks the raw key; call
+    ``config.api_key.get_secret_value()`` explicitly when passing it to an SDK.
+    """
+
+    model: str
+    api_key: SecretStr
+    base_url: str
+    temperature: float = 0.0
+    max_tokens: int | None = None
+    timeout: float = 60.0
+    extra: dict[str, Any] = Field(default_factory=dict)

everalgo_core-0.1.0/src/everalgo/llm/errors.py

@@ -0,0 +1,5 @@
+"""LLM-layer error types — minimal single-base set."""
+
+
+class LLMError(Exception):
+    """Raised on any LLM call failure. Inspect ``__cause__`` (PEP 3134) for the original SDK exception."""

everalgo_core-0.1.0/src/everalgo/llm/factory.py

@@ -0,0 +1,15 @@
+"""Factory for building an LLM client from configuration."""
+
+from everalgo.llm.config import LLMConfig
+from everalgo.llm.protocols import LLMClient
+
+
+def build_client(config: LLMConfig) -> LLMClient:
+    """Build an OpenAI-compatible LLM client.
+
+    ``OpenAICompatClient`` is imported lazily so that ``import everalgo.llm`` remains cheap for callers
+    that only need the Protocol / Config / Error types. Do not hoist this to a top-level import.
+    """
+    from everalgo.llm.providers.openai_compat import OpenAICompatClient
+
+    return OpenAICompatClient(config)