Metadata-Version: 2.4
Name: repolens-ai
Version: 0.1.0
Summary: Agentic coding CLI with code graph intelligence and cost-aware context optimization.
Project-URL: Homepage, https://github.com/ramvalicharla/RepoLens
Project-URL: Documentation, https://github.com/ramvalicharla/RepoLens/tree/main/docs
Project-URL: Issues, https://github.com/ramvalicharla/RepoLens/issues
Project-URL: Source, https://github.com/ramvalicharla/RepoLens
Author: LogicMint
License: Apache-2.0
License-File: LICENSE
Keywords: agentic-coding,code-graph,coding-cli,llm,token-optimization
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: networkx>=3.3
Requires-Dist: pydantic-settings>=2.4
Requires-Dist: pydantic>=2.8
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# RepoLens

Agentic Coding CLI with Code Graph Intelligence.

RepoLens is an open-source coding CLI focused on measurable engineering outcomes:
smaller prompts, precise patches, graph-aware repository context, cache reuse, and
cost visibility.

It is not positioned as a generic AI coding assistant. The core promise is:

> The coding CLI that understands your repo and reduces token costs.

## Current v0.1 Scope

```bash
repolens init
repolens providers
repolens graph build
repolens graph impact app/auth.py
repolens graph explain app/auth.py
repolens review "review auth security"
repolens fix "fix failing auth test" --path app/auth.py --apply
repolens agent fix "fix failing auth test" --path app/auth.py --apply
repolens stats
repolens optimize
repolens memory show
```

Implemented capabilities:

- Provider abstraction for OpenAI, Anthropic, Google AI Studio, DeepSeek, and Ollama.
- SQLite-backed usage, context, fix, failure, graph, and memory storage.
- Code graph for files, imports, classes, functions, routes, and tests.
- Graph-aware context selection with token reduction reporting.
- Surgical, unified diff, and full-file patch modes.
- Generated patch cache reuse.
- Explicit agent workflow orchestration with planner, context, coder, reviewer, test, and repair states.
- Local patch review gate before generated patches are written.
- Targeted tests after generated fixes.
- Bounded repair loop for failed targeted tests.
- Usage and cost analytics.
- Context optimization recommendations for generated files, snapshots, fixtures, lockfiles, and large files.
- Repository memory for architecture, frameworks, build/test commands, generated paths, and provider preferences.

## Install

From PyPI after release:

```bash
pip install repolens
```

From this repository:

```bash
pip install -e ".[dev]"
```

## Provider Setup

Provider, model, base URL, and API keys are resolved entirely from the
environment or the repo config — no model id is hardcoded in the application.

Set the API key for the provider(s) you use:

```bash
OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
GOOGLE_API_KEY=...
DEEPSEEK_API_KEY=...
```

Ollama uses a local server and does not require an API key.

### Choosing or auto-suggesting a provider

Resolution precedence (highest first) for both provider and model:

1. Explicit `--provider` / `--model` on the command.
2. Environment variables `REPOLENS_PROVIDER` / `REPOLENS_MODEL`.
3. The repo's `.repolens/config.toml` `[provider]` block (written by `repolens init`).
4. **Auto-suggested "best option"** — the first provider with an available
   credential, in the order set by `REPOLENS_PROVIDER_PREFERENCE`
   (default `deepseek, anthropic, openai, google, ollama`). `repolens init` writes
   this suggestion into the config so it is a sensible, editable starting point.

```bash
repolens fix "fix login bug"                                   # auto-resolved provider + model
repolens fix "fix login bug" --provider anthropic --model claude-haiku-4-5
REPOLENS_PROVIDER=openai REPOLENS_MODEL=gpt-4o-mini repolens fix "fix login bug"
```

Inspect resolution at any time (offline, read-only — no provider call):

```bash
repolens providers
```

Shows which providers have a detected credential, each provider's base URL and
default model, the auto-suggested best option, and the effective provider/model
for the current repo with the precedence layer that decided each.

### Overridable connection settings (env)

| Variable | Purpose |
| --- | --- |
| `REPOLENS_PROVIDER`, `REPOLENS_MODEL` | Default provider / model |
| `REPOLENS_PROVIDER_PREFERENCE` | Comma-separated auto-suggest order |
| `REPOLENS_<PROVIDER>_MODEL` | Per-provider default model (e.g. `REPOLENS_ANTHROPIC_MODEL`) |
| `<PROVIDER>_BASE_URL` | Per-provider base URL (e.g. `ANTHROPIC_BASE_URL`, `OLLAMA_BASE_URL`) |

## Typical Workflow

Initialize repository memory and storage:

```bash
repolens init
```

Build the graph:

```bash
repolens graph build
```

Inspect impact before changing a file:

```bash
repolens graph impact app/auth.py
repolens graph explain app/auth.py
```

Review with compact context:

```bash
repolens review "review auth security" --path app/auth.py
```

Generate and validate a fix without writing files:

```bash
repolens fix "fix expired JWT login failure" --path app/auth.py
```

Apply a generated fix:

```bash
repolens fix "fix expired JWT login failure" --path app/auth.py --apply
```

Run the explicit agent workflow with state trace:

```bash
repolens agent fix "fix expired JWT login failure" --path app/auth.py --apply
```

Generated apply path:

1. Selects graph-aware compact context.
2. Generates a patch through the provider.
3. Validates the patch locally (parses and applies in memory, confirms targets stay inside the repo).
4. Runs a deterministic patch review. This is a heuristic scan of the
   introduced lines for secret/risk patterns (hardcoded credentials, `eval`,
   `shell=True`, etc.) plus an oversized-patch check — it is a safety lint, not
   a correctness check, and does not verify that the fix is right.
5. Writes the patch only if that review finds no blocking (critical/high) issues.
6. Runs graph-related targeted tests. This is the real correctness gate — a
   patch that breaks the targeted tests is reported as failed.
7. Runs a bounded repair loop if targeted tests fail.
8. Records usage, cost, patch, test, and repair metadata.

Manual patch application remains available:

```bash
repolens fix "apply reviewed patch" --patch-mode diff --patch-file change.diff
```

## Cost Visibility

```bash
repolens stats
```

Reports:

- Usage events
- Input/output/cached tokens
- Estimated cost
- Cache reuse
- Provider and model usage

## Context Optimization

```bash
repolens optimize
```

Reports token-heavy generated files, snapshots, fixtures, lockfiles, and large
files with recommendations for exclusion or compression.

## Repository Memory

```bash
repolens memory refresh
repolens memory show
repolens memory set provider.default deepseek
```

Stores durable repo facts such as frameworks, package managers, test commands,
build commands, generated paths, and preferred provider/model. `repolens init`
refreshes memory automatically.

## Patch Modes

```bash
--patch-mode surgical
--patch-mode diff
--patch-mode full
```

Default is `surgical`.

Generated patches default to dry-run validation. Use `--apply` to write. Cached
generated patches are still validated and reviewed before apply.

## Safety Controls

```bash
--allow-dirty
--unsafe-skip-review
--test / --no-test
--repair / --no-repair
--repair-attempts 1
```

Defaults are conservative:

- Dirty git targets are blocked unless `--allow-dirty` is used.
- Generated patches are reviewed before writing.
- Targeted tests run after generated apply.
- One bounded repair attempt is allowed after targeted test failure.

## Documentation

- [Command reference](docs/commands/README.md)
- [Generated-fix safety policy](docs/safety.md)
- [Benchmarks](docs/benchmarks/README.md)
- [Provider smoke checks](docs/provider-smoke.md)
- [Release checklist](docs/release-checklist.md)
- [Changelog](CHANGELOG.md)
- [Roadmap](ROADMAP.md)

## Contributing

- [Contributing guide](CONTRIBUTING.md)
- [Security policy](SECURITY.md)
- [Example repo](examples/repos/fullstack-lite/README.md)

## License

Apache-2.0.
