Metadata-Version: 2.4
Name: embeadings
Version: 0.4.2
Summary: Local-first coordination review for Beads and Linear
Project-URL: Homepage, https://github.com/DyrtyJax/embeadings
Project-URL: Documentation, https://github.com/DyrtyJax/embeadings/blob/main/docs/README.md
Project-URL: Issues, https://github.com/DyrtyJax/embeadings/issues
Project-URL: Repository, https://github.com/DyrtyJax/embeadings.git
Project-URL: Changelog, https://github.com/DyrtyJax/embeadings/blob/main/CHANGELOG.md
Project-URL: Releases, https://github.com/DyrtyJax/embeadings/releases
Author: Jackson Cantrell
License: MIT
License-File: LICENSE
Keywords: beads,developer-tools,linear,semantic-search,triage
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: filelock<4,>=3.16
Requires-Dist: huggingface-hub<2,>=1.0
Requires-Dist: model2vec<0.9,>=0.8
Requires-Dist: numpy<3,>=1.26
Requires-Dist: platformdirs<5,>=4.3
Provides-Extra: benchmark
Requires-Dist: fastembed<0.9,>=0.8; extra == 'benchmark'
Requires-Dist: sqlite-vec<0.2,>=0.1.9; extra == 'benchmark'
Provides-Extra: dev
Requires-Dist: jsonschema<5,>=4.23; extra == 'dev'
Requires-Dist: pytest<10,>=8.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.12; extra == 'dev'
Description-Content-Type: text/markdown

# emBEADings

<img src="https://raw.githubusercontent.com/DyrtyJax/embeadings/v0.4.2/assets/brand/embeadings-mark.svg" width="72" alt="Two bead paths converging on a shared code surface">

[![CI](https://github.com/DyrtyJax/embeadings/actions/workflows/ci.yml/badge.svg)](https://github.com/DyrtyJax/embeadings/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/DyrtyJax/embeadings?include_prereleases)](https://github.com/DyrtyJax/embeadings/releases/tag/v0.4.2)

Find engineering work that may trip over the same code—without changing the tracker or sending issue
text to an embedding API.

emBEADings is a read-only coordination CLI for
[Beads](https://github.com/gastownhall/beads) and Linear. It combines typed tracker relationships,
local semantic retrieval, explicit code pointers, and genuine Git worktree changes into a bounded,
deterministic review queue.

Dependencies answer “what blocks this?” emBEADings asks “what else should I inspect before these
changes merge?” It provides evidence, not an automatic verdict.

> **Status:** v0.4 technical preview. The CLI and GitHub release are public; the bundled Codex and
> Claude Code plugin is still a local developer preview.

## Quick start

Python 3.11 or later is required. The default Beads source also requires an installed `bd` CLI.

```bash
pipx install embeadings
# or: uv tool install embeadings

# Check the environment without loading issue text
embead doctor

# Produce a bounded coordination packet
embead triage

# Find active work touching the same files or modules
embead collisions

# Inspect semantic neighbors for one record
embead neighbors ISSUE_ID --include-closed
```

For an immutable GitHub fallback, install the verified release wheel directly:

```bash
python -m pip install \
  "https://github.com/DyrtyJax/embeadings/releases/download/v0.4.2/embeadings-0.4.2-py3-none-any.whl"
```

The first semantic command downloads the pinned
[`minishlab/potion-base-8M`](https://huggingface.co/minishlab/potion-base-8M) model. Embedding happens
locally. `collisions` does not load an embedding model.

Release assets include a source archive and `SHA256SUMS`. See the
[v0.4.2 release](https://github.com/DyrtyJax/embeadings/releases/tag/v0.4.2) for versioned artifacts and
checksums.

## What a lead looks like

![Synthetic terminal example of an observed exact-file collision](https://raw.githubusercontent.com/DyrtyJax/embeadings/v0.4.2/assets/brand/synthetic-collision-evidence.svg)

This shortened example is derived from the committed synthetic collision fixture:

```json
{
  "issue_id": "demo-1",
  "related_issue_id": "demo-2",
  "kind": "exact-file",
  "confidence": "observed",
  "shared_paths": ["src/cache/index.py"],
  "evidence_sources": ["active-worktree-diff"],
  "what_to_verify": "Verify whether concurrent work will modify the shared file paths before implementation or merge."
}
```

The full report also records repository provenance, revision relation, hub suppression, warnings, and
the read-only policy. It contains pointers rather than source snippets. See
[`examples/collisions.json`](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/examples/collisions.json)
and the
[example guide](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/examples/README.md).

## Why trust it?

| Evidence | Result | Boundary |
| --- | --- | --- |
| Concurrent-worktree release gate | Recovered all 3 known exact-file collisions across 4 genuine active worktrees | One repository; not universal recall |
| Dogfooding | Found 2 real association/scope defects before v0.4.0 | Demonstrates workflow value, not broad precision |
| Ruff scale surrogate | 17/20 top-packet pairs were at least contextually useful across 8,143 public issues | Converted GitHub corpus; no native Beads graph or worktrees |
| Release validation | Full CI passed across Linux, macOS, Windows, Python 3.11 and 3.14; wheel/sdist checksums and provenance published | Supply-chain and test evidence, not semantic quality |
| Repeatability | Evaluation outputs were byte-stable and non-mutating | Determinism does not make a weak lead correct |

Read the [dogfood release-gate story](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/docs/articles/dogfooding-v040-worktree-gate.md),
[aggregate v0.4.0 worktree gate](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/docs/research/code-surface-v040-release-gate.md),
[Ruff scale review](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/docs/research/ruff-scale-surrogate-01.md),
and the
[research index](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/docs/research/README.md)
for methods, failure patterns, and limitations.

## How it works

```text
Beads or one Linear team
        │
        ├── typed relationships and lifecycle
        ├── explicit paths and observed worktree changes
        └── local whole-record and field-level embeddings
                              │
                              ▼
                   bounded candidate union
                              │
                              ▼
                evidence receipts + review packet
```

`triage` is the opinionated front door. It admits at most 20 semantic candidates by default, includes
code-surface analysis when genuine local Git evidence exists, and writes a complete audit report to
external user state. Use `sweep` for experimental policy controls and `neighbors` for one-record
inspection. The default is a reviewer-capacity budget, not corpus coverage; see the
[review-budget decision](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/docs/decisions/review-budget-default.md).

`collisions` reviews `open`, `in_progress`, and `blocked` work by default. It associates Git worktrees
when a branch contains a full Bead ID or unambiguous `bead-N` suffix. Explicitly map an otherwise
unassociated worktree with:

```bash
embead collisions --worktree-map embead-42=../feature-worktree
```

Never fabricate a mapping: observed evidence must describe genuine active implementation work.
Shared paths are coordination evidence, not proof that two tasks conflict.

## Linear

Create a personal API key in Linear's Security & access settings and load it without placing the value
directly in a shell-history entry:

```bash
LINEAR_API_KEY="$(python -c 'import getpass; print(getpass.getpass("Linear API key: "))')"
export LINEAR_API_KEY

embead --source linear --linear-team ENG triage
embead --source linear --linear-team ENG collisions
```

`LINEAR_ACCESS_TOKEN` accepts an OAuth token instead; set only one credential. The CLI queries one
selected team through Linear GraphQL and does not reuse credentials held by an MCP or agent host. See
the [Linear adapter contract](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/docs/linear.md).

## Privacy and data boundary

- Tracker adapters contain no mutation operations.
- The default model embeds issue text locally; issue text is not sent to Hugging Face.
- Linear mode sends tracker queries only to Linear itself.
- Models and vectors use the platform user cache; reports use the platform user state directory.
- Neither cache nor reports are written into the analyzed repository by default.
- Collision reports contain code pointers, not source snippets.
- A human or coordinator must verify every lead before changing tracker or source state.

The first model download is network activity. Prepare it before loading private issues when evaluating
under OS-level network denial. See the
[safe offline evaluation guide](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/docs/evaluation.md).

## Good fit / poor fit

emBEADings is most useful when a tracker is too large for repeated full-context review, several people
or agents work concurrently, and the team values a reproducible offline shortlist.

It is less useful for a small tracker that one reviewer can read directly, repositories without
meaningful tracker-to-code evidence, or teams seeking automatic issue mutation, orchestration, a
dashboard, or a general memory system. Typed dependencies remain tracker truth; semantics complement
them rather than re-deriving authority.

## Development

Every clone or Git worktree must own its virtual environment:

```bash
python3 scripts/worktree_env.py
. .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
python scripts/validate.py
```

The bootstrap refuses to reuse an active environment from another checkout. Validation checks the
editable `embead` import target before formatting, lint, tests, and release checks. Read
[`CONTRIBUTING.md`](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/CONTRIBUTING.md)
before submitting fixtures or reports; private tracker content
must never be committed.

## Agent plugin preview

[`plugins/embeadings`](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/plugins/embeadings/README.md)
packages `triage`, `collisions`, and `evaluate`
skills for local Codex and Claude Code development. It delegates to the installed CLI, forces schema-v1
JSON, and verifies the read-only policy. It is not yet a marketplace release and grants no tracker-write
authority.

## Documentation

- [Documentation index](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/docs/README.md)
- [CLI and product specification](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/docs/spec.md)
- [Consumer and schema contract](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/docs/consumer-contract.md)
- [Performance and scale evaluation](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/docs/performance.md)
- [Research and evaluation ledger](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/docs/research/README.md)
- [Versioned JSON Schemas](https://github.com/DyrtyJax/embeadings/tree/v0.4.2/schemas/v1) and
  [synthetic examples](https://github.com/DyrtyJax/embeadings/blob/v0.4.2/examples/README.md)

## Principles

- **Read-only means read-only.** Analysis never closes, edits, labels, or reprioritizes work.
- **The tracker remains authoritative.** Structure and lifecycle stay tracker data.
- **Local-first and private.** The default semantic provider sends no issue content to a network API.
- **Bounded and auditable.** A stable receipt explains what entered or was omitted from the queue.
- **Agent-neutral.** Core analysis does not depend on Codex, Claude Code, Cursor, or another runtime.

MIT licensed. emBEADings is not affiliated with Beads or Linear.
