Metadata-Version: 2.1
Name: ai-change-vault
Version: 0.3.0
Summary: Local snapshots, turn indexing, and configurable semantic embeddings for AI-assisted coding.
Requires-Python: >=3.10
Author: AI Change Vault contributors
License: MIT
Keywords: ai, cli, backup, rag, snapshots, developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Version Control
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/aicv/ai-change-vault
Project-URL: Repository, https://github.com/aicv/ai-change-vault
Project-URL: Issues, https://github.com/aicv/ai-change-vault/issues
Project-URL: Documentation, https://github.com/aicv/ai-change-vault#readme
Requires-Dist: typer>=0.12
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0 ; extra == "dev"
Requires-Dist: pytest-cov>=5.0 ; extra == "dev"
Requires-Dist: ruff>=0.6 ; extra == "dev"
Requires-Dist: mypy>=1.10 ; extra == "dev"
Provides-Extra: embeddings-local
Requires-Dist: sentence-transformers>=3.0 ; extra == "embeddings-local"
Provides-Extra: embeddings-openai
Requires-Dist: openai>=1.0 ; extra == "embeddings-openai"
Provides-Extra: embeddings
Requires-Dist: openai>=1.0 ; extra == "embeddings"
Requires-Dist: sentence-transformers>=3.0 ; extra == "embeddings"
Description-Content-Type: text/markdown; charset=UTF-8

# AI Change Vault

AI Change Vault (`aicv`) is a local-first CLI for saving, indexing, and reverting AI-assisted code changes.
Its main job is to keep each turn searchable, compact, and recoverable without depending on Git or GitHub.

At a glance, `aicv`:

- creates local backups before and after a change
- indexes the turn, changed files, and validation result
- can generate embeddings with a configurable model for semantic search
- restores a whole project or a single file when a turn goes wrong

## What it solves

When an AI changes code, the result is not always what the user expected.
`aicv` gives every turn a local backup, a structured index entry, searchable metadata, and a reversible snapshot.

## Install

`aicv` is a Python CLI for any repository type, including Node.js repos.
Install it into a Python environment on your machine, then point it at the project you want to track.

```bash
pip install ai-change-vault
```

Local embeddings for that same Python environment:

```bash
pip install "ai-change-vault[embeddings-local]"
```

OpenAI embeddings:

```bash
pip install "ai-change-vault[embeddings-openai]"
```

If your Python environment is system-managed, you may need `--break-system-packages`, or you can use a
virtual environment instead.

## Core flow

1. Create a snapshot before touching files.
2. Make the AI-driven code changes.
3. Validate with tests, lint, or build.
4. Create a second snapshot after validation.
5. Index the turn with request, changed files, and validation result.
6. Search later by turn, file, or request.
7. Revert the full project or a single file if needed.

## Commands

```bash
aicv init .
aicv --version
aicv doctor
aicv backup --message "before refactor navbar"
aicv index --turn 1 --request "Change login button color" --files "src/components/Navbar.tsx" --validation "lint + tests OK"
aicv list
aicv search "navbar login"
aicv search --turn turn-1
aicv search --file Navbar.tsx
aicv revert --turn turn-1
aicv revert --turn turn-1 --file src/components/Navbar.tsx
aicv config
aicv embeddings status
aicv embeddings rebuild
```

## What it stores

- Deduplicated snapshot manifests in `.aicv/backups/`
- Shared file contents in `.aicv/objects/`
- Turn documents in `.aicv/rag/turns/`
- Keyword index in `.aicv/rag/index.json`
- Optional turn, diff, and snippet embedding vectors in `.aicv/rag/embeddings.json`
- Human-readable session log in `AI_SESSION_LOG.md`
- Compact turn backups in `.aicv/backups/` when both before and after snapshots are indexed

By default, snapshots are content-addressed: each backup stores a manifest and each unique file
content is written once under `.aicv/objects/`. This keeps later backups close to the size of the
files that changed instead of copying the whole project every time.

## Search modes

`aicv` uses a hybrid retrieval model:

- **Keyword search** is always available.
- **Embeddings** are optional and only used when configured.

Keyword search is exact and fast.
Embeddings improve semantic recall, for example when the user asks for "header spacing" and the turn was indexed as "navbar layout".
If a local embedding model cannot be downloaded, `aicv` keeps the rest of the workflow usable and falls back to keyword-only behavior.


## Indexing And Embeddings

Each turn stores a canonical document with the request, changed files, validation result, and
backup references. When embeddings are enabled, `aicv` also generates vectors for the turn summary
and for changed-file diffs/snippets using the configured model.

## Embeddings

Embeddings are opt-in. The default install uses keyword search only.

### Providers

- `none`: keyword-only mode
- `sentence-transformers`: local semantic embeddings
- `openai`: hosted embeddings
- `ollama`: local HTTP embedding endpoint

### Recommended models

Use the model name configured in `.aicv.config.yaml` or `AICV_EMBEDDING_MODEL`.
Good starting points are modern retrieval-oriented models from the BGE, E5, or OpenAI embeddings families.

### Example config

```yaml
backup_dir: .aicv/backups
backup_retention: 20
backup_storage: deduplicated
object_dir: .aicv/objects
rag_dir: .aicv/rag
embedding_provider: sentence-transformers
embedding_model: BAAI/bge-base-en-v1.5
embedding_weight: 0.7
keyword_weight: 0.3
auto_index: false
excludes:
  - .git/
  - .aicv/
  - node_modules/
  - dist/
  - build/
```

### Behavior

- Each turn stores a canonical text representation in the embedding index.
- Changed files also generate diff and snippet payloads when a before snapshot is available.
- Search ranks results using keywords first and semantic similarity second.
- If embeddings are misconfigured or unavailable, `aicv` falls back to keyword search.
- `aicv embeddings rebuild` reports model download or provider errors without crashing the rest of the CLI.

## Reverting

Full project:

```bash
aicv revert --turn turn-1
```

Single file:

```bash
aicv revert --turn turn-1 --file src/components/Navbar.tsx
```

Use `--state after` to restore the post-change backup when available.

## Configuration

Create `.aicv.config.yaml` in the project root:

```yaml
backup_dir: .aicv/backups
backup_retention: 20
backup_storage: deduplicated
object_dir: .aicv/objects
rag_dir: .aicv/rag
embedding_provider: none
embedding_model: sentence-transformers/all-MiniLM-L6-v2
embedding_base_url: http://localhost:11434
embedding_endpoint: /api/embed
embedding_batch_size: 16
embedding_weight: 0.65
keyword_weight: 0.35
auto_index: false
```

Environment variables with the `AICV_` prefix override config values:

```bash
AICV_BACKUP_DIR=.vault/backups aicv backup "custom dir"
```

Use `backup_storage: copy` or `AICV_BACKUP_STORAGE=copy` to keep the legacy full-directory
snapshot behavior.

If you are migrating an older project, `.aicv.yaml` is still accepted as a legacy fallback.

## List stored data

```bash
aicv list
aicv list --kind turns
aicv list --kind backups
aicv list --json
```

## Migrate old backups

If a project already has legacy full-copy backups, convert them to deduplicated manifests:

```bash
aicv backups migrate --yes
```

Existing compact or deduplicated backups are skipped. Legacy backups are rewritten as manifests and
their file contents are stored once in `.aicv/objects/`.
