Metadata-Version: 2.5
Name: axm-echo
Version: 0.2.0
Summary: Neural similarity & echo detection over code corpora (MiniLM + scikit-learn).
Project-URL: Homepage, https://github.com/axm-protocols/axm-forge-workspace
Project-URL: Documentation, https://axm-protocols.github.io/axm-forge-workspace/
Project-URL: Repository, https://github.com/axm-protocols/axm-forge-workspace.git
Project-URL: Issues, https://github.com/axm-protocols/axm-forge-workspace/issues
Author-email: Gabriel Jarry <gabriel@axm-protocols.io>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: axm
Requires-Dist: axm-ast
Requires-Dist: axm-config
Requires-Dist: numpy>=2.5.1
Requires-Dist: scikit-learn>=1.9.0
Requires-Dist: sentence-transformers>=5.6.0
Requires-Dist: torch>=2.12.1
Description-Content-Type: text/markdown

# axm-echo

Neural similarity & echo detection over code corpora (MiniLM + scikit-learn).

<p align="center">
  <a href="https://forge.axm-protocols.io/audit/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge-workspace/gh-pages/badges/axm-echo/axm-audit.json" alt="axm-audit"></a>
  <a href="https://forge.axm-protocols.io/init/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge-workspace/gh-pages/badges/axm-echo/axm-init.json" alt="axm-init"></a>
  <a href="https://github.com/axm-protocols/axm-forge-workspace/actions/workflows/axm-quality.yml"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge-workspace/gh-pages/badges/axm-echo/coverage.json" alt="Coverage"></a>
  <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+">
</p>

---

## Overview

Neural similarity & echo detection over code corpora (MiniLM + scikit-learn).

## Features

- **Neural by default** — the `st` (MiniLM) backend ships in the base install
  (`torch` + `sentence-transformers`) and runs in-process; no extra to enable.
- **`tfidf` opt-out** — the pure-CPU `numpy` + `scikit-learn` backend stays
  available (`--backend tfidf`) for callers that want to avoid loading torch.
- Built on `axm-ast` for code-corpus extraction — the corpus feeding both
  `echo_code` (cross-package dedup) and `echo_check` (reuse retrieval).

## Installation

```bash
# echo is neural by default — the install ships torch + sentence-transformers.
uv add axm-echo
```

Or as a workspace dependency in `pyproject.toml`:

```toml
[project]
dependencies = ["axm-echo"]

[tool.uv.sources]
axm-echo = { workspace = true }
```

## Quick Start

```python
from axm_echo import embed, extract_monorepo, neighbors

symbols = extract_monorepo()  # public symbols across the configured scope
matrix = embed([s["embed_text"] for s in symbols], backend="tfidf")
for idx, score in neighbors(matrix[0], matrix, k=5):
    print(f"{score:.3f}  {symbols[idx]['qualname']}")
```

See the [documentation site](https://axm-protocols.github.io/axm-forge-workspace/)
for the `echo_code` / `echo_check` tools and the scope how-to.

## Development

This package is part of the **axm-forge-workspace** uv workspace.

```bash
# Run tests for this package
uv run --package axm-echo pytest

# From workspace root
make test-axm-echo
```

## License

MIT — © 2026 Gabriel Jarry
