Metadata-Version: 2.4
Name: repository-cognition-engine
Version: 0.1.0
Summary: Repository Cognition Engine (rce) - A Python CLI project
Author-email: Deep-SkyLabs Authors <contact@deepskylabs.in>
License: Proprietary
Project-URL: Homepage, https://github.com/Deep-SkyLabs/Repository-Cognition-Engine
Project-URL: Repository, https://github.com/Deep-SkyLabs/Repository-Cognition-Engine
Project-URL: Bug Tracker, https://github.com/Deep-SkyLabs/Repository-Cognition-Engine/issues
Keywords: mcp,ai,llm,ast,cli,static-analysis,code-cognition
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
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 :: Code Generators
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click
Requires-Dist: gitpython
Requires-Dist: anthropic
Requires-Dist: google-genai
Requires-Dist: rich
Requires-Dist: networkx
Requires-Dist: python-dotenv
Requires-Dist: pyperclip
Requires-Dist: pathspec
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings
Requires-Dist: mcp
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: numpy>=1.24.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# Repository Cognition Engine (`rce`)

A premium command-line engine for semantic understanding, AST analysis, Git-based coupling, and structural reasoning over code repositories. Built with `tree-sitter`, `rich`, and Claude-powered semantic synthesis.

---

## Features

- **Multi-language AST Parser**: Analyzes symbols, functions, classes, imports, and exports using Tree-sitter.
- **Git Coupling Matrix**: Computes file churn, co-change coupling scores, and author activity.
- **Structural Codebase Model**: Automatically detects project frameworks, languages, entrypoints, and architectural layers.
- **AI-Powered Synthesis**: Leverages Claude to summarize codebase architecture, key workflows, conventions, and coupling insights.
- **Offline Mode (`--no-llm`)**: Runs entirely locally without network requests, creating a structural index.
- **Agent Context Packager**: Generates high-density context blocks to feed downstream LLMs or coding agents.

---

## Installation

### Prerequisites

- Python 3.10+
- Git

### Development Installation

1. Clone or navigate to the repository directory:
   ```bash
   cd Repository-Cognition-Engine
   ```

2. Create a virtual environment and install the package in editable mode:
   ```bash
   python -m venv .venv
   .venv\Scripts\activate
   pip install -e .
   ```

### Standalone Packaging & Global Distribution

To package the CLI into standalone distribution archives (`.whl` and `.tar.gz`) or install it globally on another system or project, refer to the comprehensive **[Packaging & Distribution Guide](distribution_guide.md)**.

---

## Environment Setup & Configuration

You can configure the Repository Cognition Engine (`rce`) using standard production-grade methods: shell environments, workspace `.env` files, or a central configuration.

### 1. Global Production Config (Recommended)
You can set and manage your API keys globally across all projects using the built-in `rce config` manager. Settings are securely stored in your user profile folder at `~/.rce/config.json`.

**Step-by-Step Setup:**

1. **Set your Default Gemini API Key (Required for reasoning & Q&A)**:
   ```bash
   rce config set GEMINI_API_KEY "your_gemini_api_key_here"
   ```
2. **Set your Anthropic API Key (Optional)**:
   ```bash
   rce config set ANTHROPIC_API_KEY "your_anthropic_api_key_here"
   ```
3. **Verify the global configuration is written securely**:
   ```bash
   rce config show
   ```
   *Secrets will automatically be masked in the terminal output to prevent security leaks.*

4. **Retrieve or verify individual keys if needed**:
   ```bash
   rce config get GEMINI_API_KEY
   ```
5. **Delete or unset key configurations**:
   ```bash
   rce config unset GEMINI_API_KEY
   ```

### 2. Shell Environment Variables
Production systems and CI/CD pipelines can directly export API keys into the environment:
```bash
# Windows (PowerShell)
$env:GEMINI_API_KEY="your_api_key"

# Linux / MacOS
export GEMINI_API_KEY="your_api_key"
```

### 3. Local Workspace & User Directory `.env` Files
`rce` automatically scans and loads configuration from the following `.env` files in order of priority:
1. **Local Workspace**: Current working directory (`.env`).
2. **User Home Directory**: `~/.env` and `~/.rce/.env` for system-wide dotenv files.

To set up a local workspace `.env` file, copy the provided template:
```bash
copy .env.example .env
```
And specify the keys:
```env
GEMINI_API_KEY=your_gemini_api_key_here
# Optional if using Anthropic models instead
ANTHROPIC_API_KEY=your_anthropic_api_key_here
```

---

## CLI Command Usage

Once installed, the `rce` command is globally available in your environment.

### 1. `rce analyze`
Orchestrates structural analyzers to build a comprehensive codebase cognitive index.

- **Usage**: `rce analyze [PATH]`
- **Arguments**:
  - `PATH`: Path to the repository directory (default: `.`)
- **Options**:
  - `--force`: Force a full rebuild of the index (bypassing the cache).
  - `--no-llm`: Skip LLM synthesis entirely (Offline / Structural-only mode, no API key required).
  - `--format [human|agent|json]`: Specify the output format (default: `human`).

**Examples**:
```bash
# Standard analysis with LLM synthesis
rce analyze .

# Offline/Local AST-only analysis
rce analyze . --no-llm

# Force rebuild
rce analyze . --force

# Output as agent-digestible text block
rce analyze . --format agent
```

---

### 2. `rce ask`
Answers conceptual and architectural questions about your codebase, leveraging AI-powered reasoning over relevant files.

- **Usage**: `rce ask [QUESTION]`
- **Arguments**:
  - `QUESTION`: The conceptual or implementation question to ask.
- **Options**:
  - `--path PATH`: Path to the repository directory (default: `.`)
  - `--format [human|agent|json]`: Specify the output format (default: `human`).

**Example**:
```bash
rce ask "How does the index builder store data?" --path .
```

---

### 3. `rce similar`
Ranks and displays matching codebase files based on multi-dimensional similarity metrics (shared AST patterns, imports, parent folders, and historical co-changes).

- **Usage**: `rce similar [FILEPATH]`
- **Arguments**:
  - `FILEPATH`: Path to the file to find similarities for.
- **Options**:
  - `--path PATH`: Path to the repository directory (default: `.`)
  - `--top INTEGER`: Number of top similar files to retrieve (default: `10`).
  - `--format [human|json]`: Specify the output format (default: `human`).

**Example**:
```bash
rce similar rce/indexer/builder.py --top 5
```

---

### 4. `rce impact`
Evaluates direct dependencies, dependents, co-change partners, and pattern couplings to assess regression risk when modifying a target file.

- **Usage**: `rce impact [FILEPATH]`
- **Arguments**:
  - `FILEPATH`: Target file to analyze impact on.
- **Options**:
  - `--path PATH`: Path to the repository directory (default: `.`)
  - `--format [human|json]`: Specify the output format (default: `human`).

**Example**:
```bash
rce impact rce/indexer/builder.py
```

---

### 5. `rce build`
Gets step-by-step implementation guidance using repository context.

- **Usage**: `rce build [TASK]`
- **Arguments**:
  - `TASK`: Description of the feature or bug to implement.
- **Options**:
  - `--path PATH`: Path to the repository directory (default: `.`)
  - `--format [human|agent]`: Specify the output format (default: `human`).
  - `--copy`: Automatically copy the generated agent prompt to the clipboard.
  - `--save PATH`: Save the output to a specified file.

**Example**:
```bash
rce build "Add a new command to the CLI" --copy --save guide.txt
```

---

### 6. `rce status`
Displays the active indexing status, last analyzed timestamp, repo info, file count, and environment configurations.

- **Usage**: `rce status`
- **Options**:
  - `--path PATH`: Path to the repository directory (default: `.`)

**Example**:
```bash
rce status --path .
```

---

### 7. `rce docs`
Generates comprehensive codebase documentation from the repository index.

- **Usage**: `rce docs`
- **Options**:
  - `--path PATH`: Path to the repository directory (default: `.`)
  - `--output-dir / --output PATH`: The output directory for the generated markdown files (default: `docs/rce`).
  - `--type [all|architecture|agent-rules|api|onboarding|antigravity]`: The type of documentation to generate (default: `all`).

**Generates the following files**:
- `ARCHITECTURE.md`: Technical breakdown of the project structure and patterns.
- `CLAUDE.md`: Quickstart instructions, design goals, and command mappings.
- `API.md`: Comprehensive API reference & contract specifications.
- `ONBOARDING.md`: Dev setup, local environment guides, and dependency walkthrough.
- `ANTIGRAVITY.md`: Antigravity rules and environment specific agent guidelines.
- `antigravity_rules.json`: Machine-readable agent rules and instruction profiles.

**Example**:
```bash
rce docs --output docs/rce
```

---

## What is inside `.rce/`?

The `rce analyze` command synthesizes structural data and saves it under the `.rce/` directory at your project root:

- **`meta.json`**: Tracking metadata including the repository path, indexing timestamp, and `rce` engine version.
- **`index.json`**: The main unified index containing framework details, entry points, architecture layers, and Claude-synthesized modules, workflows, and conventions.
- **`symbols.json`**: Extracted AST symbols (functions, classes, imports, exports, detected design patterns) for every file.
- **`cochange.json`**: Historical Git co-change coupling metrics and churn vectors.

---

## MCP Server Configuration

The Repository Cognition Engine includes an official Model Context Protocol (MCP) server that exposes codebase intelligence directly to MCP-enabled clients (such as Claude Desktop or Cursor).

Add the following configuration blocks to connect `rce` as an MCP server.

### Claude Desktop

Add this to your Claude Desktop configuration (`~/.config/claude/claude_desktop_config.json` on macOS/Linux or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "rce": {
      "command": "rce-mcp",
      "args": []
    }
  }
}
```

### Cursor

Add this to your Cursor MCP settings or `.cursor/mcp.json`:

```json
{
  "rce": {
    "command": "rce-mcp",
    "args": []
  }
}
```

### Exposed MCP Tools

The `rce-mcp` server exposes the following tools directly to LLMs and agents to query your codebase natively:

| Tool Name | Arguments | Description |
| :--- | :--- | :--- |
| `analyze_repository` | `repo_path` (str, absolute), `force` (bool, default `False`) | Builds or refreshes the structural and cognitive index for a codebase. |
| `ask_repository` | `question` (str), `repo_path` (str, absolute) | Answers questions regarding architecture, conventions, or design patterns. |
| `trace_call_chain` | `method_name` (str), `class_name` (str, optional), `repo_path` (str, optional) | Computes and traces call/flow chains for a specific method or function. |
| `get_implementations` | `interface_name` (str), `repo_path` (str, absolute) | Finds all concrete classes or functions implementing a given interface/abstract contract. |
| `get_api_surface` | `repo_path` (str, absolute), `domain` (str, optional) | Returns all endpoints, HTTP methods, controllers, and authorization schemas. |
| `get_feature_context` | `task` (str), `repo_path` (str, absolute) | Recommends context packs (files, patterns, changes) for starting a specific implementation task. |
| `get_conventions` | `repo_path` (str, absolute), `category` (str, optional) | Retrieves conventions used in the codebase (naming, error formats, validation, structural). |
| `find_similar` | `filepath` (str), `repo_path` (str, absolute), `top_n` (int, default `5`) | Resolves files that are structurally or AST-similar to a target file. |


