Add RAG basic implementation

This commit is contained in:
2026-11-09 08:43:30 +03:00
parent 447464c16c
commit 7fa1d774a0
76 changed files with 3030 additions and 124 deletions
View File
+95
View File
@@ -0,0 +1,95 @@
"""The container entry point, run with a stub `python` that records how it was called."""
import os
import stat
import subprocess
from pathlib import Path
import pytest
ROOT = Path(__file__).resolve().parents[3]
ENTRYPOINT = ROOT / "docker" / "entrypoint.sh"
STUB = """#!/bin/sh
echo "$*" >> "$STUB_LOG"
if [ -n "${STUB_FAIL_ON:-}" ]; then
case "$*" in *"$STUB_FAIL_ON"*) exit 3;; esac
fi
exit 0
"""
@pytest.fixture
def run(tmp_path):
bin_dir = tmp_path / "bin"
bin_dir.mkdir()
stub = bin_dir / "python"
stub.write_text(STUB)
stub.chmod(stub.stat().st_mode | stat.S_IEXEC)
log = tmp_path / "calls.log"
def go(*args, **env):
full = {"PATH": f"{bin_dir}:/usr/bin:/bin", "STUB_LOG": str(log), **env}
proc = subprocess.run(["sh", str(ENTRYPOINT), *args], env=full, capture_output=True, text=True, cwd=tmp_path, check=False)
calls = log.read_text().splitlines() if log.exists() else []
if log.exists():
log.unlink()
return proc.returncode, calls
return go
def test_serve_is_the_default_and_does_not_touch_the_database_by_itself(run):
assert run() == (0, ["-m estimator serve"])
assert run("serve") == (0, ["-m estimator serve"])
@pytest.mark.parametrize("value", ["false", "", "yes", "1", "TRUE"])
def test_only_the_exact_value_true_turns_migrate_on_start_on(run, value):
assert run("serve", MIGRATE_ON_START=value) == (0, ["-m estimator serve"])
def test_migrations_run_before_the_service_starts(run):
code, calls = run("serve", MIGRATE_ON_START="true")
assert code == 0
assert calls == ["-m estimator wait-db --timeout 60", "-m estimator migrate", "-m estimator serve"] # in this order
def test_the_wait_time_is_configurable(run):
_, calls = run("serve", MIGRATE_ON_START="true", DB_WAIT_TIMEOUT="5")
assert calls[0] == "-m estimator wait-db --timeout 5"
def test_a_failed_migration_stops_the_start(run):
code, calls = run("serve", MIGRATE_ON_START="true", STUB_FAIL_ON="migrate")
assert code == 3
assert "-m estimator serve" not in calls and calls[-1] == "-m estimator migrate"
def test_an_unreachable_database_stops_the_start_before_any_migration(run):
code, calls = run("serve", MIGRATE_ON_START="true", STUB_FAIL_ON="wait-db")
assert code == 3 and calls == ["-m estimator wait-db --timeout 60"]
def test_the_migrate_job_waits_then_applies_and_exits(run):
assert run("migrate") == (0, ["-m estimator wait-db --timeout 60", "-m estimator migrate head"])
assert run("migrate", "0001")[1][-1] == "-m estimator migrate 0001" # an explicit revision can be given
def test_the_migrate_job_fails_when_the_database_never_comes_up(run):
code, calls = run("migrate", STUB_FAIL_ON="wait-db")
assert code == 3 and calls == ["-m estimator wait-db --timeout 60"]
@pytest.mark.parametrize(
"args",
[("rag", "import", "/data/refs.csv", "--project", "P"), ("hash-password",), ("rag", "stats")],
)
def test_other_commands_pass_through_unchanged(run, args):
assert run(*args) == (0, ["-m estimator " + " ".join(args)])
def test_the_script_is_executable_and_posix_sh():
assert os.access(ENTRYPOINT, os.X_OK)
first = ENTRYPOINT.read_text().splitlines()[0]
assert first == "#!/bin/sh" # the slim image has no bash
assert "set -eu" in ENTRYPOINT.read_text()
+161
View File
@@ -0,0 +1,161 @@
"""Static checks of the Dockerfile and the compose file, since an image cannot be built in every
environment. They pin the properties that matter: the start order, a non-root user, what is copied,
and that every dependency the code imports is declared (an image installs only what is declared)."""
import ast
import importlib.metadata as md
import re
import sys
import tomllib
from pathlib import Path
import yaml
ROOT = Path(__file__).resolve().parents[3]
DOCKERFILE = (ROOT / "Dockerfile").read_text()
COMPOSE = yaml.safe_load((ROOT / "docker-compose.yml").read_text())
# ----------------------------------------------------------------------- compose
def test_compose_has_a_database_a_migration_job_and_the_service():
assert set(COMPOSE["services"]) == {"db", "migrate", "app"}
def test_the_start_order_is_database_then_migrations_then_service():
s = COMPOSE["services"]
assert s["migrate"]["depends_on"]["db"]["condition"] == "service_healthy"
assert s["app"]["depends_on"]["migrate"]["condition"] == "service_completed_successfully"
assert "db" not in s["app"]["depends_on"] # the service reaches the database only through the job
assert s["migrate"]["command"] == ["migrate"] and s["migrate"]["restart"] == "no"
assert s["app"]["restart"] == "unless-stopped"
def test_the_database_is_postgres_with_pgvector_and_a_healthcheck_and_a_volume():
db = COMPOSE["services"]["db"]
assert db["image"].startswith("pgvector/pgvector:pg") and ":latest" not in db["image"]
check = " ".join(db["healthcheck"]["test"])
assert "pg_isready" in check and "-h 127.0.0.1" in check # a TCP check: see the comment in the compose file
assert any(v.startswith("dbdata:") for v in db["volumes"]) and "dbdata" in COMPOSE["volumes"]
def test_migrate_and_service_use_the_same_image_and_the_same_settings():
s = COMPOSE["services"]
assert s["migrate"]["image"] == s["app"]["image"] and "build" in s["migrate"] and "build" not in s["app"]
assert s["migrate"]["environment"] == s["app"]["environment"] # one source of truth for the connection
def test_the_password_is_required_and_the_connection_points_at_the_db_service():
env = COMPOSE["services"]["app"]["environment"]
assert "@db:5432/estimator" in env["EST_DATABASE__DSN"]
for value in (env["EST_DATABASE__DSN"], COMPOSE["services"]["db"]["environment"]["POSTGRES_PASSWORD"]):
assert "${POSTGRES_PASSWORD:?" in value # compose refuses to start without it
def test_the_service_is_hardened_and_exposes_only_its_port():
app = COMPOSE["services"]["app"]
assert app["cap_drop"] == ["ALL"] and "no-new-privileges:true" in app["security_opt"]
assert not app.get("privileged") and "ports" in app and app["ports"][0].endswith(":8000")
assert "ports" not in COMPOSE["services"]["db"] # the database is not published to the host
assert not any("docker.sock" in str(v) for v in app.get("volumes", []))
# -------------------------------------------------------------------- Dockerfile
def test_dockerfile_is_multi_stage_on_a_pinned_slim_python():
froms = re.findall(r"^FROM (\S+)", DOCKERFILE, flags=re.MULTILINE)
assert froms == ["python:3.12-slim", "python:3.12-slim"]
def test_the_service_runs_as_a_non_root_user():
assert re.search(r"^USER app$", DOCKERFILE, flags=re.MULTILINE)
assert DOCKERFILE.index("USER app") < DOCKERFILE.index("ENTRYPOINT")
assert "10001" in DOCKERFILE and "nologin" in DOCKERFILE
def test_entrypoint_command_and_healthcheck_are_declared():
assert 'ENTRYPOINT ["/app/docker/entrypoint.sh"]' in DOCKERFILE and 'CMD ["serve"]' in DOCKERFILE
assert "HEALTHCHECK" in DOCKERFILE and "/health" in DOCKERFILE
assert "chmod 0755 /app/docker/entrypoint.sh" in DOCKERFILE # does not depend on the file mode in the checkout
def test_what_the_service_reads_at_run_time_is_copied_into_the_image():
# only copies from the build context (a copy --from=builder takes files from the earlier stage)
context_copies = [ln for ln in DOCKERFILE.splitlines() if ln.startswith("COPY ") and "--from=" not in ln]
copied = [re.match(r"COPY (?:--\S+ )*(\S+) (\S+)", ln).groups() for ln in context_copies]
sources = {src for src, _ in copied}
assert {"config", "prompts", "migrations", "alembic.ini", "docker/entrypoint.sh", "pyproject.toml", "src"} <= sources
ignored = {line.strip() for line in (ROOT / ".dockerignore").read_text().splitlines()}
for src in sources:
assert (ROOT / src).exists(), src
assert src not in ignored and src.split("/")[0] not in ignored, f"{src} is excluded by .dockerignore"
def test_the_image_is_not_built_from_an_editable_install_and_holds_no_secrets():
assert "-e " not in DOCKERFILE and "pip install -e" not in DOCKERFILE
assert not re.search(r"^\s*(ENV|ARG)\s+\S*(KEY|PASSWORD|SECRET|TOKEN)", DOCKERFILE, flags=re.MULTILINE | re.IGNORECASE)
def test_env_files_and_tests_stay_out_of_the_build_context():
ignored = (ROOT / ".dockerignore").read_text().splitlines()
for item in (".env", "tests", ".git", ".venv"):
assert item in ignored
assert "!.env.example" in ignored
def test_app_directories_match_what_the_code_expects_relative_to_the_working_directory():
default = tomllib.loads((ROOT / "config" / "default.toml").read_text())
assert default["agent"]["prompts_dir"] == "prompts" # /app/prompts
assert "script_location = migrations" in (ROOT / "alembic.ini").read_text() # /app/migrations
assert default["api"]["host"] == "0.0.0.0" # reachable from outside the container
# ----------------------------------------------------- dependencies are declared
_TRANSITIVE_OK = {"starlette"} # always installed with fastapi, which is declared
def _declared() -> set[str]:
deps = tomllib.loads((ROOT / "pyproject.toml").read_text())["project"]["dependencies"]
return {re.split(r"[\[<>=!~ ;]", d, maxsplit=1)[0].lower().replace("_", "-") for d in deps}
def _imported_top_level_modules() -> set[str]:
found: set[str] = set()
for path in (ROOT / "src" / "estimator").rglob("*.py"):
for node in ast.walk(ast.parse(path.read_text())):
if isinstance(node, ast.Import):
found.update(a.name.split(".")[0] for a in node.names)
elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
found.add(node.module.split(".")[0])
return found - set(sys.stdlib_module_names) - {"estimator"}
def test_every_third_party_package_the_code_imports_is_a_declared_dependency():
owners = md.packages_distributions()
declared = _declared()
missing = {}
for module in _imported_top_level_modules():
dists = {d.lower().replace("_", "-") for d in owners.get(module, [])}
if not dists & declared and module not in _TRANSITIVE_OK:
missing[module] = sorted(dists) or ["not installed"]
assert not missing, f"imported but not declared in pyproject.toml: {missing}"
def test_pgvector_is_declared_because_the_schema_needs_it():
assert "pgvector" in _declared()
def test_the_migration_imports_only_declared_packages():
modules = set()
for node in ast.walk(ast.parse((ROOT / "migrations" / "versions" / "0001_initial.py").read_text())):
if isinstance(node, ast.ImportFrom) and node.module:
modules.add(node.module.split(".")[0])
elif isinstance(node, ast.Import):
modules.update(a.name.split(".")[0] for a in node.names)
owners = md.packages_distributions()
declared = _declared()
for module in modules - set(sys.stdlib_module_names):
assert {d.lower().replace("_", "-") for d in owners.get(module, [])} & declared, module