Skip to content

Getting Started

This tutorial walks you through installing axm-echo and verifying your setup.

Prerequisites

  • Python 3.12+
  • uv (recommended) or pip

Installation

Bash
uv add axm-echo

Or with pip:

Bash
pip install axm-echo

The neural st backend (torch + sentence-transformers, MiniLM) ships in the base install and is the default — there is no extra to enable. The tfidf backend stays pure-CPU for callers that want to skip loading torch.

Step 1: Embed a Few Texts

The neural st backend (MiniLM) is the default. The tfidf backend is pure-CPU (numpy + scikit-learn) and never imports torch, used here so the snippet stays fast and deterministic:

Python
from axm_echo import embed, neighbors

texts = [
    "raise an error when the API rate limit is exceeded",
    "raise an error when the request quota is exceeded",
    "read rows from a CSV file into a list of dicts",
]
matrix = embed(texts, backend="tfidf")

# Nearest neighbours of the first text (exact cosine top-k).
for idx, score in neighbors(matrix[0], matrix, k=2):
    print(f"{score:.3f}  {texts[idx]}")

Step 2: Extract a Corpus From Code

extract_package walks a package via axm-ast and returns one record per public function/class:

Python
from pathlib import Path

from axm_echo import extract_package

for sym in extract_package(Path("packages/axm-echo")):
    print(sym["qualname"], "->", sym["doc_first_line"])

Only first-party source is extracted: the walk skips test trees and any vendored or generated subtree (a committed .venv, site-packages, __pycache__, node_modules, .tox, build, dist, .git), so third-party libraries installed inside a checked-in virtualenv never leak into the corpus.

extract_monorepo() does the same across every package declared in ~/axm/echo.toml (workspace_roots), degrading gracefully to the current directory when no config is present. Each listed root is treated as a workspace, so packages are discovered at <root>/packages/<pkg> (the monorepo convention) as well as in the flat other/<pkg> layout. A directory only counts as a package when it carries a real marker — a src/ directory or a pyproject.toml — so doc folders such as docs/gen_ref_pages.py are never mistaken for packages.

Step 3: Run the Tests

Bash
# Run this package's tests (from anywhere in the workspace).
uv run pytest --package axm-echo

# Or, from the workspace root, the full lint + type-check + tests gate:
make check

uv run pytest --package axm-echo runs the package test suite; make check (a workspace-root target — there is no per-package Makefile) runs lint (ruff + mypy) plus the whole workspace test run.

Next Steps