[project] name = "everos" version = "1.7.1" description = "EverOS — local-first markdown memory framework for AI agents and user chats; lightweight, dev-friendly, small-team" license = {text = "Apache-2.0"} readme = "README.md" requires-python = ">=3.12" authors = [ {name = "EverMind AI"}, ] keywords = ["memory", "ai-agent", "markdown", "lancedb", "rag", "everos"] classifiers = [ "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers", "License :: OSI Approved :: Apache Software License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Topic :: Scientific/Engineering :: Artificial Intelligence", "Typing :: Typed", ] dependencies = [ # Core data validation & config "pydantic>=2.7.1", "pydantic-settings>=2.0.0", # Storage stack (md-first three-piece set) # Upper bound: 0.35.0 embeds lance-rust v9 (large storage/encoding jump, not # yet stable-released). 0.32-0.34 carry a compaction offset-overflow regression # (lance-format/lance#7653); we run 0.34.0 safely via the with_position=False # FTS workaround. Do not float past 0.34.x until 0.35 has been validated under # sustained churn (bounded + reclaimable index dir, no compaction crash) — see # docs/cascade_runbook.md. Never widen this floor back below 0.34 (older lance # cannot read v8 data). Before raising the ceiling, re-check that a # merge_insert cancelled by asyncio.timeout never lands after the # TimeoutError (0.34.0: 0 of 41 did); memory deletion's index fence # assumes it. "lancedb>=0.34.0,<0.35.0", # Vector + BM25 + scalar filter (Arrow-based) # Floor, not a new package: lancedb pulls pyarrow in anyway. 25.0.1 stops # the per-value `import pytz` attempt in to_pylist() (24 walked sys.path # for every tz-aware timestamp) and materialises rows without a Scalar # per element; 25.0.0 lacks the latter and has a mimalloc exit crash. "pyarrow>=25.0.1", "aiosqlite>=0.20.0", # Async SQLite driver (used by SA async engine) "sqlmodel>=0.0.22", # ORM (Pydantic + SQLAlchemy 2.0 async) "alembic>=1.13.0", # SQLite schema migrations "greenlet>=3.0", # Required by SQLAlchemy async # LLM & embedding (one provider per file pattern) # <3: openai 3.x (2026-09-24) moved to the httpx 1.0 pre-release line and its # client raises AttributeError on every request; 2.x is what the lock tests. "openai>=1.0.0,<3", # Markdown / file system "PyYAML>=6.0", # YAML frontmatter parsing # 7.x changes event semantics and can kill recursive inotify delivery # under warnings=error. Keep installs on the supported, lock-tested line. "watchdog>=4.0.2,<7", # macOS event_filter support; tested pre-7 contract # Web framework (entrypoints/api) "fastapi>=0.104.0", "python-multipart>=0.0.7", # Required by FastAPI for Form / UploadFile endpoints "uvicorn[standard]>=0.24.0", # Observability (core/observability) "structlog>=24.0.0", "prometheus-client>=0.20.0", # CLI + TUI "typer>=0.12.0", # click is a transitive dep of uvicorn today, but our CLI raises # ``click.exceptions.Abort`` directly (e.g. tests that inject aborts) # and typer 0.15+ vendored a copy of click under ``typer._click`` — so # the two classes are DIFFERENT even though users only ever see # ``typer.Abort``. We depend on the standalone click package so # ``click.exceptions.Abort`` stays importable and both classes are # covered in the Ctrl-C catch (see backfill exit-130 path). "click>=8.1", "textual>=8.2.7", # Tokenization (BM25 Chinese support) "jieba>=0.42.1,<1.0", # OME (Offline Memory Evolution) async scheduler & file I/O "apscheduler>=3.10.4,<4.0", # async strategy scheduler chassis "portalocker>=2.8.2", # cross-platform file lock for single-engine guard # Windows only: the MSVC C++ runtime (msvcp140.dll et al.) that greenlet's # wheel links against and a stock Windows does not ship. It lands in # sys.prefix; everos/__init__.py registers that dir with the DLL loader. "msvc-runtime>=14.44; sys_platform == 'win32'", "watchfiles>=0.21.0", # native fs watcher for config hot reload "anyio>=4.0", # Async file I/O (anyio.Path, to_thread.run_sync) for the markdown layer # Algorithm library (everalgo monorepo, published on PyPI). # # All eight everalgo packages (including the four transitive ones) ship on one # contract line -- currently the 2026-11-13 line (everalgo-core 0.7.0), # still on the `LLMClient.achat` contract of everalgo-core 0.6.0; # everalgo-user-memory 0.10.1 only adds `LanguageDetector` to it. The # packages declare loose ranges on one another, so a fresh # `pip install everos` would otherwise mix lines the suite has never run # together. Pin every one with `==` and raise them together, with a run of # the release smoke against a PyPI-resolved install. "everalgo-user-memory==0.10.1", "everalgo-agent-memory==0.6.0", "everalgo-rank==0.5.0", "everalgo-knowledge==0.3.0", "everalgo-boundary==0.5.0", "everalgo-core==0.7.0", "everalgo-clustering==0.3.0", "everalgo-parser==0.3.0", ] [project.optional-dependencies] multimodal = ["everalgo-parser[svg]==0.3.0"] # [svg] bundles cairosvg → SVG works by default # Native OpenTelemetry tracing export. Optional — EverOS never imports these # unless [observability] is enabled. Install with: pip install everos[otel] otel = [ "opentelemetry-sdk>=1.27.0", "opentelemetry-exporter-otlp-proto-http>=1.27.0", ] milvus = ["pymilvus>=3.0.0"] # NLTK keyword tokenizer (`[tokenizer] name = "nltk"`). Pinned to the release the # EverAlgo LoCoMo harness used: tokens change across NLTK releases, and the # indexed side and the query side must produce the same ones. nltk = ["nltk==3.9.4"] [project.urls] Homepage = "https://evermind.ai" Repository = "https://github.com/EverMind-AI/EverOS" Changelog = "https://github.com/EverMind-AI/EverOS/blob/main/CHANGELOG.md" "Bug Tracker" = "https://github.com/EverMind-AI/EverOS/issues" [build-system] requires = ["hatchling"] build-backend = "hatchling.build" [tool.hatch.build.targets.wheel] packages = ["src/everos"] # ``env.template`` lives at src/everos/templates/env.template and is # auto-included via ``packages``. ``everos init`` reads it through # ``importlib.resources``. No force-include needed. # sdist uses an include-whitelist (not exclude) so we don't accidentally ship # things like CLAUDE.md, .claude/, CI configs, or IDE settings. New top-level # files default to NOT-shipped — you have to opt them in here. # # exclude is kept as belt-and-suspenders for build artefacts that CI generates # inside the project tree (UV_CACHE_DIR=.uv-cache in .gitlab-ci.yml). [tool.hatch.build.targets.sdist] include = [ "/src", "/tests", "/docs", "/pyproject.toml", "/README.md", "/QUICKSTART.md", "/CHANGELOG.md", "/CONTRIBUTING.md", "/CODE_OF_CONDUCT.md", "/SECURITY.md", "/ACKNOWLEDGMENTS.md", "/CITATION.md", "/LICENSE", "/NOTICE", "/config.example.toml", ] exclude = [".uv-cache", ".venv"] [project.scripts] everos = "everos.entrypoints.cli.launcher:main" # ─────────────────────────────────────────────────────────────────────────────── # Tooling # ─────────────────────────────────────────────────────────────────────────────── [tool.ruff] line-length = 88 target-version = "py312" extend-exclude = ["src_old"] [tool.ruff.lint] select = ["E", "F", "I", "N", "UP", "B", "SIM", "ASYNC", "RUF"] ignore = [ "RUF001", # ambiguous Unicode in strings (intentional × – symbols) "RUF002", # ambiguous Unicode in docstrings "RUF003", # ambiguous Unicode in comments "RUF012", # mutable class attribute default (SQLModel requires this) ] [tool.ruff.lint.per-file-ignores] # The four dataset adapters hold the answer and judge prompts as multi-line string # literals, copied byte-for-byte from each benchmark's reference harness. Rewrapping one # changes what the model is shown and so changes the score, which is the opposite of what # this code is for. Every long line in these four files is inside such a literal -- # nothing outside one is exempted, and no other file under benchmarks/ is. "benchmarks/adapters/locomo.py" = ["E501"] "benchmarks/adapters/longmemeval.py" = ["E501"] "benchmarks/adapters/subtlememory.py" = ["E501"] "benchmarks/adapters/evermembench.py" = ["E501"] [tool.pytest.ini_options] testpaths = ["tests"] python_files = ["test_*.py"] python_functions = ["test_*"] asyncio_mode = "auto" addopts = "-v --tb=short -m 'not slow and not live_llm and not acceptance'" filterwarnings = [ "error", # tzlocal (via APScheduler, imported by the OME engine): a container with no # /etc/timezone and no /etc/localtime warns and falls back to UTC. Under `error` # that aborts COLLECTION for every test that imports the app -- measured at 50 # files here -- so `make test` fails on a clean container for a reason unrelated # to any test. The fallback is already what this project wants: the display # timezone comes solely from EVEROS_MEMORY__TIMEZONE, never from the OS (see # .claude/rules/datetime-handling.md), so tzlocal's guess is never read. "ignore:Can not find any timezone configuration:UserWarning", # jieba 0.42.1: unescaped backslashes in regex strings (upstream # unmaintained; no fix available). Python 3.12 emits # SyntaxWarning for invalid escape sequences. "ignore:invalid escape sequence:SyntaxWarning", # aiosqlite teardown: connection-worker thread and Connection.__del__ # raise after pytest closes the event loop. Upstream issue # (aiosqlite + pytest-asyncio); we cannot fix their lifecycle. "ignore:Exception in thread.*_connection_worker_thread:pytest.PytestUnhandledThreadExceptionWarning", # aiosqlite + asyncio teardown: Connection.__del__ and # BaseEventLoop.__del__ fire after pytest closes the event loop. # Upstream lifecycle issue; we cannot fix their cleanup order. "ignore:Exception ignored.*:pytest.PytestUnraisableExceptionWarning", ] markers = [ "slow: runs that take >=10s (regardless of dependency); CI default excludes these. Run with `pytest -m slow`.", "live_llm: requires real LLM / embedder / reranker credentials from .env; burns tokens. CI default excludes. Run with `pytest -m live_llm`.", "acceptance: starts real everos server processes with real providers (tests/acceptance); burns tokens, minutes per test. Run with `make acceptance`.", ] [tool.coverage.run] source = ["src/everos"] branch = true omit = ["**/__init__.py"] [tool.coverage.report] fail_under = 80 show_missing = true exclude_lines = [ "if TYPE_CHECKING:", "@abstractmethod", "pragma: no cover", ] [tool.importlinter] root_packages = ["everos"] # Annotation-only imports under ``if TYPE_CHECKING:`` never run, so they # cannot couple layers at runtime; contracts check runtime imports only. exclude_type_checking_imports = true # External packages enter the graph so ``no-bypass-facade`` can name # structlog / logging / opentelemetry. include_external_packages = true [[tool.importlinter.contracts]] # Dependency inversion (stage 2b): the domain declares storage ports in # ``everos.memory.ports`` and ``everos.infra`` implements them, so infra # sits outside this order; ``infra-inverted`` and ``memory-forbidden`` # below pin both directions. name = "Layered architecture" type = "layers" layers = [ "everos.entrypoints", "everos.service", "everos.memory", ] [[tool.importlinter.contracts]] # Entry points translate a protocol (HTTP, CLI, TUI) into facade calls and # back. Request / response DTOs and error types reach them through the # ``everos.service`` facade or ``everos.core``; nothing below the service is # theirs to import. Direct imports only: an entry point reaching the domain # *through* the service is the point. name = "entrypoints-forbidden: entry points import the service, not what it wires" type = "forbidden" source_modules = ["everos.entrypoints"] forbidden_modules = [ "everos.memory", "everos.infra", "everos.component", "everalgo", ] allow_indirect_imports = true [[tool.importlinter.contracts]] name = "infra-inverted: infra reaches the domain only through its ports" type = "forbidden" source_modules = ["everos.infra"] forbidden_modules = [ "everos.memory.extract", "everos.memory.get", "everos.memory.custom_instructions", "everos.memory.reflection", "everos.memory.search", "everos.memory.strategies", "everos.memory._partition_locks", "everos.service", "everos.entrypoints", ] [[tool.importlinter.contracts]] name = "memory-forbidden: the domain does not import infra" type = "forbidden" source_modules = ["everos.memory"] forbidden_modules = ["everos.infra"] [[tool.importlinter.contracts]] name = "core-forbidden: core and config depend on nothing above them" type = "forbidden" source_modules = ["everos.core", "everos.config"] forbidden_modules = [ "everos.component", "everos.memory", "everos.service", "everos.entrypoints", "everos.infra", ] [[tool.importlinter.contracts]] name = "component-forbidden: injectable providers depend on no layer" type = "forbidden" source_modules = ["everos.component"] forbidden_modules = [ "everos.memory", "everos.service", "everos.entrypoints", "everos.infra", ] [[tool.importlinter.contracts]] name = "mappers-pure: algo <-> domain mapping does no IO" type = "forbidden" source_modules = ["everos.memory.mappers"] forbidden_modules = [ "everos.infra", "everos.component", "everos.service", ] [[tool.importlinter.contracts]] name = "Subpackage internals are private" type = "forbidden" source_modules = ["everos.service", "everos.memory", "everos.entrypoints"] # `**` matches any descendant (writer.py, reader.py, sub.foo.bar, ...). # Public API must be reached via the subpackage `__init__.py`. forbidden_modules = [ "everos.infra.persistence.markdown.**", "everos.infra.persistence.lancedb.**", "everos.infra.persistence.sqlite.**", "everos.infra.persistence.index.**", "everos.infra.persistence.records.**", "everos.infra.persistence.milvus.**", "everos.infra.cascade.**", ] # `forbidden` contracts run a *transitive closure* — any path from a # source module to a forbidden module fails the check, even when the # source only imports the subpackage top-level. The whitelist below # carves out **intra-subpackage wiring**: each storage subpackage's # own ``__init__.py`` imports its own ``tables`` / ``repos`` / manager # children to assemble the public API surface that outer layers reach. # These edges are normal Python package wiring, *not* a privacy # breach — without these ignores, even a legitimate # ``from everos.infra.persistence.sqlite import X`` would be punished # because the transitive scan walks one hop further into the package. # # Direct imports from outer layers into a subpackage internal module # (e.g. ``from everos.infra.persistence.sqlite._tables import X`` written # in ``service`` or ``entrypoints``) remain blocked — that edge is not # in this whitelist. # # Two edges below are *not* intra-subpackage wiring: ``lancedb -> records`` # and ``index -> records``. # ``records/`` holds the table declarations every index backend reads # (TABLE_NAME / BM25_FIELDS / PRIMARY_KEY); it is the one shared schema # module inside ``persistence/`` (docs/architecture.md, dependency table). ignore_imports = [ "everos.infra.persistence.sqlite -> everos.infra.persistence.sqlite._tables", "everos.infra.persistence.sqlite -> everos.infra.persistence.sqlite._repos", "everos.infra.persistence.sqlite -> everos.infra.persistence.sqlite.sqlite_manager", "everos.infra.persistence.sqlite -> everos.infra.persistence.sqlite.repositories", "everos.infra.persistence.lancedb -> everos.infra.persistence.records", "everos.infra.persistence.lancedb -> everos.infra.persistence.lancedb._repos", "everos.infra.persistence.lancedb -> everos.infra.persistence.lancedb.lancedb_manager", "everos.infra.persistence.lancedb -> everos.infra.persistence.lancedb.backend", "everos.infra.persistence.markdown -> everos.infra.persistence.markdown._mds", "everos.infra.persistence.markdown -> everos.infra.persistence.markdown._writers", "everos.infra.persistence.markdown -> everos.infra.persistence.markdown._readers", "everos.infra.persistence.markdown -> everos.infra.persistence.markdown.stores", "everos.infra.persistence.markdown -> everos.infra.persistence.markdown.owner_dir", "everos.infra.persistence.markdown -> everos.infra.persistence.markdown.knowledge_store", "everos.infra.persistence.markdown -> everos.infra.persistence.markdown.scope_purge", "everos.infra.persistence.sqlite -> everos.infra.persistence.sqlite.stores", "everos.infra.persistence.sqlite -> everos.infra.persistence.sqlite.knowledge_catalog", "everos.infra.persistence.index -> everos.infra.persistence.index.maintenance", "everos.infra.persistence.index -> everos.infra.persistence.index.vector_projection", "everos.infra.persistence.index -> everos.infra.persistence.index.vector_backfill", "everos.infra.persistence.index -> everos.infra.persistence.index._provenance", "everos.infra.persistence.index -> everos.infra.persistence.index.predicate", "everos.infra.persistence.index -> everos.infra.persistence.index.protocols", "everos.infra.persistence.index -> everos.infra.persistence.index.schema", "everos.infra.persistence.index -> everos.infra.persistence.index.derived_index", "everos.infra.persistence.index -> everos.infra.persistence.index.repositories", # The storage factories are persistence's own wiring: they build the # configured engine's backend (Milvus only when selected, so pymilvus # stays an optional extra) and the domain's index adapters over it. "everos.infra.persistence.factories -> everos.infra.persistence.index.adapters", "everos.infra.persistence.factories -> everos.infra.persistence.milvus", # Persistence primitives moved out of ``core`` (stage 2a): each storage # subpackage facade re-exports its own ``base`` primitives, and # ``records`` re-exports the base table it shares with every backend. "everos.infra.persistence.markdown -> everos.infra.persistence.markdown._base", "everos.infra.persistence.sqlite -> everos.infra.persistence.sqlite._base", "everos.infra.persistence.lancedb -> everos.infra.persistence.lancedb._base", "everos.infra.persistence.records -> everos.infra.persistence.records.index_record", "everos.infra.persistence.records -> everos.infra.persistence.records.base", "everos.infra.persistence.records -> everos.infra.persistence.records.vector", "everos.infra.persistence.records -> everos.infra.persistence.records._parent_type", "everos.infra.persistence.records -> everos.infra.persistence.records._provenance_key", "everos.infra.persistence.records -> everos.infra.persistence.records.agent_case", "everos.infra.persistence.records -> everos.infra.persistence.records.agent_skill", "everos.infra.persistence.records -> everos.infra.persistence.records.atomic_fact", "everos.infra.persistence.records -> everos.infra.persistence.records.episode", "everos.infra.persistence.records -> everos.infra.persistence.records.knowledge_topic", "everos.infra.persistence.records -> everos.infra.persistence.records.user_profile", # The cascade facade assembles its public surface from its own modules. "everos.infra.cascade -> everos.infra.cascade._worker", "everos.infra.cascade -> everos.infra.cascade._eraser", "everos.infra.cascade -> everos.infra.cascade._fence", "everos.infra.cascade -> everos.infra.cascade.admin", "everos.infra.cascade -> everos.infra.cascade.orchestrator", "everos.infra.cascade -> everos.infra.cascade.registry", ] [[tool.importlinter.contracts]] # The facade and the router resolve a configured backend, so they import the # engine packages by design. The port definitions must not: the moment protocols or # schema knows a concrete engine, "portable" stops being checkable and the # next adapter inherits whatever leaked in. This is the rule that keeps the # split from eroding -- moving files alone does not stop anyone moving them # back. name = "Derived-index ports know no concrete backend" type = "forbidden" source_modules = [ "everos.infra.persistence.index.protocols", "everos.infra.persistence.index.schema", "everos.infra.persistence.index.vector_projection", "everos.memory.ports", ] forbidden_modules = [ "everos.infra.persistence.lancedb", "everos.infra.persistence.milvus", ] [[tool.importlinter.contracts]] # The record models declare columns, keys and which columns are embeddings; # every backend derives its physical schema from them through ``schema_for``. # The moment a record imports an engine (or its storage format), the # declarations stop being shared and the vector width can creep back into # import time (issue #476). Indirect imports are checked, so a helper module # cannot smuggle an engine in either. name = "records-neutral: record declarations know no index backend" type = "forbidden" source_modules = ["everos.infra.persistence.records"] forbidden_modules = [ "everos.infra.persistence.lancedb", "everos.infra.persistence.milvus", "lancedb", "pymilvus", "pyarrow", ] [[tool.importlinter.contracts]] name = "OME does not depend on service/entrypoints or sibling infra subpackages" type = "forbidden" source_modules = ["everos.infra.ome"] forbidden_modules = [ "everos.infra.persistence", "everos.service", "everos.entrypoints", ] [[tool.importlinter.contracts]] # The domain declares the types OME schedules (events, triggers, gates, # StrategySpec) in ``everos.memory.ports``; OME imports those and nothing # else of the domain. Direct imports only: the ports themselves reach # ``memory.models`` (and ``memory.deps`` for an annotation), which OME # never touches by name. name = "ome-ports-only: OME reaches the domain only through its ports" type = "forbidden" source_modules = ["everos.infra.ome"] forbidden_modules = [ "everos.memory._partition_locks", "everos.memory.deps", "everos.memory.events", "everos.memory.extract", "everos.memory.get", "everos.memory.mappers", "everos.memory.models", "everos.memory.custom_instructions", "everos.memory.reflection", "everos.memory.search", "everos.memory.strategies", ] allow_indirect_imports = true [[tool.importlinter.contracts]] # The service layer has one assembler: ``service.bootstrap`` builds every # adapter and provider and injects them, so the use-case modules depend on # ports and protocols only. Direct imports only -- a use case reaching # ``bootstrap`` is the facade, not a bypass. A component protocol is # imported under ``TYPE_CHECKING`` (excluded above), which is what keeps # ``component.*.protocol`` usable here. name = "service-usecases-forbidden: only the bootstrap builds adapters" type = "forbidden" source_modules = ["everos.service"] forbidden_modules = [ "everos.infra", "everos.component.embedding", "everos.component.llm", "everos.component.parser", "everos.component.rerank", "everos.component.tokenizer", ] allow_indirect_imports = true ignore_imports = [ "everos.service.bootstrap -> everos.infra.**", "everos.service.bootstrap -> everos.component.**", ] [[tool.importlinter.contracts]] # Logging, tracing and metrics are reached through ``everos.core.observability`` # only: the backends are swapped where they are configured, not where they # are called. ``core`` itself is the facade, so it is not a source here. name = "no-bypass-facade: business layers log and trace through core.observability" type = "forbidden" source_modules = [ "everos.entrypoints", "everos.service", "everos.memory", "everos.infra", ] forbidden_modules = ["structlog", "logging", "opentelemetry"] allow_indirect_imports = true [dependency-groups] dev = [ "ruff>=0.8.0", "pytest>=8.4.0", "pytest-asyncio>=1.1.0", "pytest-cov>=6.0.0", "pytest-rerunfailures>=15.0", "import-linter>=2.0", "pre-commit>=4.0.0", "ipdb>=0.13.13", "pyinstrument>=5.0.0", # Tracing tests must actually run (no skip-when-absent), so the optional # [otel] stack is always present in the dev / CI environment. "opentelemetry-sdk>=1.27.0", "opentelemetry-exporter-otlp-proto-http>=1.27.0", "pymilvus>=3.0.0", # The NLTK tokenizer tests must run, not skip, so the [nltk] extra is present too. "nltk==3.9.4", "hypothesis>=6.100", ]