Metadata-Version: 2.4
Name: alphacodin
Version: 0.55.0
Summary: The codebase intelligence layer for your AI coding agent — dependency graph, git history, dead code, decisions, and code health, exposed over MCP
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/DeejayAI/alphacodin
Project-URL: Repository, https://github.com/DeejayAI/alphacodin
Project-URL: Issues, https://github.com/DeejayAI/alphacodin/issues
Project-URL: Documentation, https://github.com/DeejayAI/alphacodin/blob/main/docs/start/USER_GUIDE.md
Keywords: documentation,codebase,wiki,llm,ai,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Requires-Dist: tree-sitter<1,>=0.25
Requires-Dist: tree-sitter-python<1,>=0.23
Requires-Dist: tree-sitter-typescript<1,>=0.23
Requires-Dist: tree-sitter-javascript<1,>=0.23
Requires-Dist: tree-sitter-go<1,>=0.23
Requires-Dist: tree-sitter-rust<1,>=0.23
Requires-Dist: tree-sitter-java<1,>=0.23
Requires-Dist: tree-sitter-cpp<1,>=0.23
Requires-Dist: tree-sitter-dart<1,>=0.1
Requires-Dist: tree-sitter-kotlin<2,>=1
Requires-Dist: tree-sitter-ruby<1,>=0.23
Requires-Dist: tree-sitter-c-sharp<1,>=0.23
Requires-Dist: tree-sitter-swift>=0.0.1
Requires-Dist: tree-sitter-scala<1,>=0.23
Requires-Dist: tree-sitter-php<1,>=0.23
Requires-Dist: tree-sitter-pascal<1,>=0.11
Requires-Dist: tree-sitter-language-pack<2,>=1.14
Requires-Dist: tree-sitter-luau<2,>=1.2
Requires-Dist: tree-sitter-bash<1,>=0.23
Requires-Dist: tree-sitter-gdscript<7,>=6.1
Requires-Dist: tree-sitter-vb-dotnet<1,>=0.3
Requires-Dist: tree-sitter-elixir<1,>=0.3.5
Requires-Dist: tree-sitter-fsharp<1,>=0.3.11
Requires-Dist: tree-sitter-objc<4,>=3.0.2
Requires-Dist: tree-sitter-svelte<2,>=1
Requires-Dist: tree-sitter-html<1,>=0.23
Requires-Dist: sqlglot<28,>=26
Requires-Dist: networkx<4,>=3.3
Requires-Dist: scipy<2,>=1.11
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: pathspec<1,>=0.12
Requires-Dist: structlog<25,>=24
Requires-Dist: sqlalchemy[asyncio]<3,>=2.0
Requires-Dist: aiosqlite<1,>=0.20
Requires-Dist: alembic<2,>=1.13
Requires-Dist: pydantic<3,>=2.8
Requires-Dist: tenacity<10,>=9
Requires-Dist: gitpython<4,>=3.1
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: lancedb<1,>=0.12
Requires-Dist: click<8.2,>=8.1
Requires-Dist: rich<14,>=13
Requires-Dist: watchdog<5,>=4
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: uvicorn[standard]<1,>=0.32
Requires-Dist: mcp<2,>=1.0
Requires-Dist: apscheduler<4,>=3.10
Requires-Dist: cryptography<51,>=50.0.0
Requires-Dist: anthropic<1,>=0.40
Requires-Dist: openai<3,>=1.50
Requires-Dist: google-genai<2,>=1.0
Requires-Dist: litellm<2,>=1.84.0
Provides-Extra: postgres
Requires-Dist: pgvector<1,>=0.3; extra == "postgres"
Requires-Dist: asyncpg<1,>=0.29; extra == "postgres"
Provides-Extra: graph-extra
Requires-Dist: graspologic<4,>=3.4; extra == "graph-extra"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: pytest-asyncio<1,>=0.23; extra == "dev"
Requires-Dist: pytest-snapshot<1,>=0.9; extra == "dev"
Requires-Dist: respx<1,>=0.21; extra == "dev"
Requires-Dist: time-machine<3,>=2.14; extra == "dev"
Requires-Dist: ruff<1,>=0.6; extra == "dev"
Requires-Dist: mypy<2,>=1.11; extra == "dev"
Requires-Dist: types-networkx<4,>=3.3; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# Alpha CodIn

<p align="center">
  <a href="https://www.alphacodin.dev"><img src=".github/assets/banner-v2.png" alt="Alpha CodIn — evidence-backed codebase intelligence" width="100%" /></a>
</p>

<p align="center">
  <strong>The codebase intelligence layer for developers and AI coding agents.</strong><br/>
  A continuously updated local index of your code, git history, tests, and decisions —<br/>
  with cited answers, change-impact analysis, and code-health improvements across
  your editor, your pull requests, and your dashboard.
</p>

<p align="center">
  <a href="https://pypi.org/project/alphacodin/"><img src="https://img.shields.io/pypi/v/alphacodin?color=DC2626&style=flat-square" alt="PyPI — alphacodin" /></a>
  <a href="https://www.npmjs.com/org/ltm-blueverse"><img src="https://img.shields.io/badge/npm-@ltm--blueverse-DC2626?style=flat-square" alt="npm — ltm-blueverse" /></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%2B-DC2626?style=flat-square" alt="Python 3.12+" /></a>
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-20%2B-DC2626?style=flat-square" alt="Node 20+" /></a>
  <a href="https://github.com/DeejayAI/alphacodin/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-DC2626?style=flat-square" alt="AGPL-3.0" /></a>
</p>

---

## What is Alpha CodIn?

Alpha CodIn builds a **local knowledge graph** of your repository — symbols, calls, imports, tests, ownership, architectural decisions — and keeps it continuously updated as you work. On top of that graph it serves:

- **A documentation wiki** generated from your code's actual structure, refreshed on every save.
- **An MCP server** that gives AI agents (Claude Code, Codex, Cursor, VS Code Copilot, OpenCode, Hermes) cited, graph-aware answers instead of stale grep results.
- **A web dashboard** for code health, architecture maps, drift detection, and refactoring opportunities.
- **Agent tooling hooks** that let every AI tool call resolve against the real graph.

Everything runs **locally on your machine**. Your code never leaves it unless you point Alpha CodIn at a hosted LLM provider.

---

## Packages

Alpha CodIn ships as one PyPI package and a set of npm packages.

### Python (PyPI)

| Package | Version | Description | Install |
|---|---|---|---|
| [`alphacodin`](https://pypi.org/project/alphacodin/) | [0.54.1](https://pypi.org/project/alphacodin/0.54.1/) | CLI + core + server — everything you need | `pip install alphacodin` |

The single PyPI package bundles all three Python layers (\`alphacodin-core\`, \`alphacodin-cli\`, \`alphacodin-server\`). Extras: \`pip install "alphacodin[all]"\` for server + UI dependencies.

### JavaScript / TypeScript (npm — private, \`@ltm-blueverse\` org)

| Package | Version | Description | Access |
|---|---|---|---|
| [`@ltm-blueverse/types`](https://www.npmjs.com/package/@ltm-blueverse/types) | 0.0.1 | Shared TypeScript types | restricted |
| [`@ltm-blueverse/api-client`](https://www.npmjs.com/package/@ltm-blueverse/api-client) | 0.1.0 | Typed API client for the server | restricted |
| [`@ltm-blueverse/ui`](https://www.npmjs.com/package/@ltm-blueverse/ui) | 0.1.0 | React component library (dashboard + webviews) | restricted |

> **npm packages are private (restricted access).** Installing them requires an npm access token: \`npm_xxxxxx\`. See [npm installation](#npm-packages).

### Install on every platform

| Platform | Command | Detailed guide |
|---|---|---|
| **macOS / Linux — pip** | \`pip install alphacodin\` | [PyPI install guide](#python-pypi) |
| **macOS / Linux — uv** | \`uv tool install alphacodin\` | [PyPI install guide](#python-pypi) |
| **macOS / Linux — uvx (no install)** | \`uvx alphacodin --help\` | [PyPI install guide](#python-pypi) |
| **Windows — pip** | \`py -m pip install alphacodin\` | [PyPI install guide](#python-pypi) |
| **Windows — pipx** | \`pipx install alphacodin\` | [PyPI install guide](#python-pypi) |
| **Docker — any OS** | \`docker run alphacodin\` | [Docker deployment](#docker-deployment) |
| **From source** | \`pip install -e ".[all]"\` | [Contributing](#contributing) |

---

## Installation

### Python (PyPI)

**Requirements:** Python 3.12+ and \`git\`.

\`\`\`bash
# pip (macOS, Linux, Windows)
pip install alphacodin

# pipx (isolated CLI install)
pipx install alphacodin

# uv tool (fast, isolated)
uv tool install alphacodin

# uvx — run without installing
uvx alphacodin --help

# Windows via the py launcher
py -m pip install alphacodin
\`\`\`

Verify:

\`\`\`bash
alphacodin --version    # alphacodin, version 0.54.1
alphacodin doctor       # environment health check
\`\`\`

### npm packages

The \`@ltm-blueverse\` packages are **restricted**: org members install them with an npm access token (\`npm_xxxxxx\`).

\`\`\`bash
# 1. Get a token from npmjs.com → Access Tokens (or ask the org owner).
# 2. Authenticate — either via environment:
export NPM_TOKEN=npm_xxxxxx

# ...or write it to ~/.npmrc:
echo "//registry.npmjs.org/:_authToken=npm_xxxxxx" >> ~/.npmrc

# 3. Install
npm install @ltm-blueverse/types @ltm-blueverse/api-client @ltm-blueverse/ui
\`\`\`

For CI, set the token as the \`NPM_TOKEN\` secret and use \`.npmrc\`:

\`\`\`ini
@ltm-blueverse:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=npm_xxxxxx
\`\`\`

> The packages ship TypeScript source (\`main\` → \`./src/index.ts\`); consume them through a bundler or a TypeScript compiler, the way the monorepo does.

---

## Quick Start

\`\`\`bash
# 1. Index a repository (no API key needed — structural wiki)
cd /path/to/your-repo
alphacodin init

# 2. (optional) Add prose pages with an LLM
export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY / GEMINI_API_KEY
alphacodin generate

# 3. Open the dashboard
alphacodin serve
# → http://localhost:3000 (Web UI)
# → http://localhost:7337 (API)

# 4. Wire up your AI agents
alphacodin agents add --target auto
\`\`\`

## Docker Deployment

Run the **full local server + Web UI** in a single container. The image bundles the FastAPI backend, the MCP server, and the Next.js dashboard.

\`\`\`bash
# Build
git clone https://github.com/DeejayAI/alphacodin.git
cd alphacodin
docker build -t alphacodin -f docker/Dockerfile .

# Index a repo on the host first
alphacodin init /path/to/repo

# Run — repo mounted read-only, index written to the /data volume
docker run -p 127.0.0.1:7337:7337 -p 127.0.0.1:3000:3000 \\
  -v /path/to/repo/.alphacodin:/data \\
  -e ALPHACODIN_API_KEY=change-me \\
  alphacodin
\`\`\`

Or with Docker Compose:

\`\`\`bash
export ALPHACODIN_DATA=/path/to/repo/.alphacodin
export REPO_PATH=/path/to/repo            # optional — omit to clone remotes into a volume instead
export ALPHACODIN_API_KEY=change-me
export ALPHACODIN_GIT_TOKEN_GITHUB=ghp_xxxx    # for private clone-from-URL
export ALPHACODIN_CONFLUENCE_URL=https://yourorg.atlassian.net
export ALPHACODIN_CONFLUENCE_EMAIL=you@company.com
export ALPHACODIN_CONFLUENCE_TOKEN=ATATT...
export ALPHACODIN_CONFLUENCE_SPACE=DOC
export ALPHACODIN_JIRA_URL=https://yourorg.atlassian.net
export ALPHACODIN_JIRA_EMAIL=you@company.com
export ALPHACODIN_JIRA_TOKEN=ATATT...
docker compose -f docker/docker-compose.yml up
\`\`\`

Without \`REPO_PATH\`, server-side \`clone_from\` checkouts land in a writable \`repos-clones\` volume; the Confluence and JIRA sections under Settings drive wiki sync and issue linking once these variables are set.

| Service | URL | Notes |
|---|---|---|
| **Web UI** | http://localhost:3000 | Next.js dashboard |
| **API** | http://localhost:7337 | FastAPI + MCP over HTTP |

An MCP-over-stdio image for CI and MCP hosts is also available: \`docker/Dockerfile.mcp\`.

---

## The Web UI

The dashboard renders the generated wiki, the code-health map, architecture pages, decision records, and an AI chat grounded in the same index your agents use. Start it with \`alphacodin serve\` or the Docker image above.

## Editor & Agent Integration

Alpha CodIn wires itself into every major AI coding tool with one command:

\`\`\`bash
alphacodin agents add --target auto
\`\`\`

| Agent | What gets installed | Notes |
|---|---|---|
| **Claude Code** | MCP server registration + \`CLAUDE.md\` instructions + hooks | [guide](website/claude-code-plugin.md) |
| **Codex CLI** | MCP config + \`AGENTS.md\` guidance | [guide](website/codex.md) |
| **Cursor** | \`.cursor/mcp.json\` + project rules | — |
| **VS Code / Copilot** | \`.vscode/mcp.json\` + the \`alphacodin.alphacodin\` extension | — |
| **OpenCode** | Native config + plugin | [guide](website/opencode.md) |
| **Hermes** | MCP transport registration | — |

\`\`\`bash
# explicit targets
alphacodin agents add --target claude-code,codex,cursor,vscode,opencode

# write to user-level config instead of repo-local
alphacodin agents add --target cursor --scope user
\`\`\`

### MCP Server

Start it standalone (stdio) or over HTTP/SSE:

\`\`\`bash
alphacodin mcp                     # stdio — Claude Code, Codex, Cursor
alphacodin mcp --transport http    # streamable HTTP
alphacodin mcp --transport sse     # legacy SSE
\`\`\`

**Default tools (10)** — every MCP client gets these:

| Tool | What it answers |
|---|---|
| \`get_answer\` | Cited natural-language questions about the codebase |
| \`get_context\` | Triage card for a file, module, or symbol |
| \`get_symbol\` | One symbol's body with live-verified line bounds |
| \`search_codebase\` | Keyword, meaning, or symbol-name search |
| \`get_risk\` / \`get_change_risk\` | Review priority for code and pending changes |
| \`get_health\` | Code-health scores, hotspots, trends |
| \`get_dead_code\` | Unused and unreachable code |
| \`get_why\` | Why the code is shaped this way — decisions, history |
| \`get_overview\` | The repo in one payload |

Workspace mode adds \`list_repos\` and cross-repo reach. Seven specialist tools (blast radius, dependency paths, execution flows, conformance, architecture, and more) are opt-in via \`--tools\` or the \`mcp.tools\` config block.

## The CLI at a Glance

\`\`\`bash
alphacodin ask "where do we validate API keys?"    # cited answers
alphacodin context src/auth/login.ts                # triage a file
alphacodin risk --branch feature/x                  # review priority
alphacodin impacted-tests src/auth/                 # tests to run
alphacodin dead-code                                # unused code
alphacodin why                                      # decisions & history
alphacodin health                                   # code-health scores
alphacodin doc-drift                                # stale documentation
alphacodin watch                                    # auto-update on save
alphacodin next                                     # ranked next actions
\`\`\`

Full reference: [website/cli-reference.md](website/cli-reference.md).

---

## Architecture

![Alpha CodIn architecture — sources feed the local index, which powers the dashboard, MCP server, and CLI](.github/assets/product-map-dark.png)

Five subsystems, one continuously updated local index:

| Package | Role |
|---|---|
| \`packages/core\` | Ingestion, parsing (30+ languages), knowledge graph, health scoring |
| \`packages/server\` | FastAPI app + MCP server behind the API and dashboard |
| \`packages/cli\` | The \`alphacodin\` CLI and agent integrations |
| \`packages/ui\` | Shared React component library (dashboard + webviews) |
| \`packages/web\` | The Next.js dashboard |

## Configuration

\`\`\`bash
# repo-level
.alphacodin/config.yaml      # wiki style, providers, MCP tools, filters

# environment
ALPHACODIN_API_KEY=          # required for non-loopback deployments
ALPHACODIN_EMBEDDER=mock     # gemini | openai | openrouter | ollama | edenai | mock
ANTHROPIC_API_KEY=           # or OPENAI_API_KEY / GEMINI_API_KEY

# phone-home (off by default)
ALPHACODIN_CHECK_UPDATES=1   # opt in to update checks


### OpenAI-compatible gateway (custom endpoint)

Point Alpha CodIn at any OpenAI-shaped endpoint — an LLM gateway, LiteLLM,
vLLM, or a corporate proxy — with your own key and model:

```bash
export OPENAI_COMPATIBLE_BASE_URL=https://tokenhub.example.com/v1
export OPENAI_COMPATIBLE_API_KEY=ltmaigateway_xxxx   # optional for open proxies
export ALPHACODIN_PROVIDER=openai_compatible
export ALPHACODIN_MODEL=auto                         # any model your gateway serves
```

In the Web UI: **Settings → Provider → OpenAI-compatible endpoint** — set the
Base URL, paste an API key, pick or type a model, then **Test**. Chat,
generation, and the model defaults all ride the gateway.

# clone-from-URL (private repositories)
ALPHACODIN_REPOS_ROOT=/repos             # where server-cloned checkouts land
ALPHACODIN_GIT_TOKEN_GITHUB=ghp_xxxx     # applied only to github.com remotes
ALPHACODIN_GIT_TOKEN_GITLAB=glpat-xxxx   # applied only to gitlab.com remotes
ALPHACODIN_GIT_CREDENTIAL_<NAME>=user:token   # named credential for credential_ref

# Confluence wiki sync
ALPHACODIN_CONFLUENCE_URL=https://yourorg.atlassian.net
ALPHACODIN_CONFLUENCE_EMAIL=you@company.com
ALPHACODIN_CONFLUENCE_TOKEN=ATATT...     # Atlassian API token
ALPHACODIN_CONFLUENCE_SPACE=DOC

# JIRA issue linking (read-only)
ALPHACODIN_JIRA_URL=https://yourorg.atlassian.net
ALPHACODIN_JIRA_EMAIL=you@company.com
ALPHACODIN_JIRA_TOKEN=ATATT...
ALPHACODIN_JIRA_PROJECT=ABC
\`\`\`

### Clone from a URL (GitHub / GitLab, public or private)

Register a remote and the server clones it into `ALPHACODIN_REPOS_ROOT` before indexing — no manual `git clone` step:

\`\`\`bash
# public
curl -X POST http://localhost:7337/api/repos -H "Authorization: Bearer $ALPHACODIN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"mini","clone_from":"https://github.com/owner/repo.git"}'

# private (token read from ALPHACODIN_GIT_TOKEN_GITHUB on the server)
curl -X POST http://localhost:7337/api/repos -H "Authorization: Bearer $ALPHACODIN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"private","clone_from":"git@github.com:owner/private.git","credential_ref":"work"}'
\`\`\`

SSH remotes (`git@host:owner/repo`) are normalized to HTTPS. Tokens reach git through a one-shot
`credential.helper` — never in the clone URL, so they cannot leak through `git remote -v`, logs, or
error output. Re-registering the same remote reuses the existing checkout.

### Confluence wiki sync & JIRA

Under **Settings → Confluence / JIRA**. Confluence pushes the generated wiki into a space: *Test
connection*, *Dry run* (shows the create/update/skip/archive plan), then *Sync now*. Pages carry an
`alphacodin:<page_id>` label plus a content hash, so re-syncs are idempotent and unchanged pages are
skipped rather than version-churned.

JIRA is **read-only**: it resolves issue keys (`ABC-123`) to live title/status for link enrichment and
can scan the last 500 commits for referenced keys. Alpha CodIn never creates or transitions issues.

## Security

- Local-first: the index and wiki live in \`.alphacodin/\` inside your repo.
- Docker deployments mount the repository **read-only** and default ports to loopback.
- Non-loopback API access requires \`ALPHACODIN_API_KEY\`; the container runs as a non-root user.
- Telemetry: none. The update check is **off by default** (\`ALPHACODIN_CHECK_UPDATES=1\` to enable).

## Self-Hosting & CI

- [website/self-hosting.md](website/self-hosting.md) — full server deployments.
- [ci/gitlab/alphacodin.gitlab-ci.yml](ci/gitlab/alphacodin.gitlab-ci.yml) — GitLab CI template.
- [.github/workflows](.github/workflows/) — GitHub Actions for wiki sync on PRs.

## Contributing

\`\`\`bash
git clone https://github.com/DeejayAI/alphacodin.git
cd alphacodin
cp .env.example .env
pip install -e ".[dev]" && npm install
pytest tests/unit -q                       # python suite
npm run build --workspace packages/web     # web build
\`\`\`

Please read [website/contributing.md](website/contributing.md) first. PRs welcome.

## License

[AGPL-3.0](LICENSE) — see [LICENSE](LICENSE) for the full text.
