openace 0.1.6b1
AI-native Contextual Code Engine
License: MIT
Requires Python: >=3.10
Keywords: code-intelligence, code-search, mcp, tree-sitter

# OpenACE

AI-native Contextual Code Engine. Rust core with Python bindings, exposing a CLI, Python SDK, and MCP server for Claude Code / Codex CLI.

OpenACE combines multi-signal retrieval (BM25 full-text + vector kNN + exact match + graph expansion + AST chunk search) with Reciprocal Rank Fusion to deliver high-quality code search across Python, TypeScript, JavaScript, Rust, Go, and Java.

## Quick Start

```bash
pip install "openace[mcp,openai]"

# Index a project
openace index /path/to/project --embedding siliconflow

# Search
openace search "user authentication" -p /path/to/project --embedding siliconflow

# Start MCP server
openace serve /path/to/project --embedding siliconflow
```

## Use with Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "openace": {
      "command": "openace",
      "args": ["serve", ".", "--embedding", "siliconflow"],
      "env": {
        "OPENACE_EMBEDDING_API_KEY": "your-api-key"
      }
    }
  }
}
```

Or use `uvx` for zero-install (once published to PyPI):

```json
{
  "mcpServers": {
    "openace": {
      "command": "uvx",
      "args": ["openace", "serve", ".", "--embedding", "siliconflow"],
      "env": {
        "OPENACE_EMBEDDING_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Use with Codex CLI

```bash
codex mcp add openace -- uvx openace serve . --embedding siliconflow
```

## Custom API Providers

OpenACE supports any OpenAI-compatible embedding/reranking API. Configure via CLI flags or environment variables:

```json
{
  "mcpServers": {
    "openace": {
      "command": "openace",
      "args": [
        "serve", ".",
        "--embedding", "openai",
        "--reranker", "siliconflow"
      ],
      "env": {
        "OPENACE_EMBEDDING_API_KEY": "your-embedding-key",
        "OPENACE_EMBEDDING_BASE_URL": "https://api.your-provider.com/v1",
        "OPENACE_RERANKER_API_KEY": "your-reranker-key",
        "OPENACE_RERANKER_BASE_URL": "https://api.your-reranker.com/v1"
      }
    }
  }
}
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `OPENACE_EMBEDDING_API_KEY` | API key for embedding provider |
| `OPENACE_EMBEDDING_BASE_URL` | Custom base URL for embedding API |
| `OPENACE_EMBEDDING_DIM` | Override embedding vector dimension |
| `OPENACE_RERANKER_API_KEY` | API key for reranker provider |
| `OPENACE_RERANKER_BASE_URL` | Custom base URL for reranker API |
| `OPENACE_EMBEDDING` | Default embedding provider for `serve` |
| `OPENACE_RERANKER` | Default reranker for `serve` |

### Embedding Providers

| Name | Model | Requires |
|------|-------|----------|
| `siliconflow` | Qwen/Qwen3-Embedding-8B (1024-dim) | `openace[openai]` + API key |
| `openai` | text-embedding-3-small | `openace[openai]` + API key |
| `local` | all-MiniLM-L6-v2 (384-dim) | `openace[onnx]` |
| `none` | BM25 only, no vector search | (default) |

### Reranker Providers

| Name | Backend | Requires |
|------|---------|----------|
| `auto` | Matches embedding provider | (default) |
| `siliconflow` | Qwen/Qwen3-Reranker-8B | `openace[openai]` + API key |
| `cohere` | Cohere Rerank | `openace[rerank-cohere]` + API key |
| `cross_encoder` | Local cross-encoder model | `openace[rerank-local]` |
| `rule_based` | Heuristic (no API needed) | (built-in) |

## MCP Tools

### semantic_search

Search for code by natural language query. Returns file-level results with code snippets, match signals, and file outlines.

### find_symbol

Look up symbols by exact name. Returns definitions with file path, line range, and signature.

### get_file_outline

Get all symbols defined in a file. Returns a structural overview with symbol kinds, names, and line ranges.

## Python SDK

```python
from openace import Engine

engine = Engine("/path/to/project")
engine.index()

# Semantic search
results = engine.search("parse XML", limit=10)
for r in results:
    print(f"{r.file_path}:{r.line_range[0]} {r.name} ({r.kind})")

# Exact lookup
symbols = engine.find_symbol("MyClass")

# File outline
outline = engine.get_file_outline("src/main.py")
```

## Installation

```bash
# Default install (includes MCP server, OpenAI/SiliconFlow embedding & reranking)
pip install openace

# With local ONNX embedding (no API key needed)
pip install "openace[onnx]"

# With Cohere reranker
pip install "openace[rerank-cohere]"

# Development
pip install -e ".[dev]"
```

## Architecture

```
Source files --> Scanner --> Parser (tree-sitter) --> Indexer --> Storage
                                                                   |
                                                     SQLite (graph/relations)
                                                     Tantivy (BM25 full-text)
                                                     usearch (vector kNN)
                                                                   |
Query --> CLI/SDK/MCP --> Retrieval (BM25 + vector + exact + graph + chunk)
                              |
                          RRF Fusion --> Reranker --> Results
```

- **Rust core** handles all performance-critical operations (parsing, indexing, storage, retrieval)
- **Python layer** provides the SDK, CLI, MCP server, and pluggable embedding/reranking providers
- **tree-sitter** for multi-language AST parsing
- **Triple-backend storage**: SQLite for graph/relations, Tantivy for BM25, usearch for HNSW vector search
- **CJK bigram tokenization** in BM25 for Chinese/Japanese/Korean query support

## Supported Languages

Python, TypeScript, JavaScript, Rust, Go, Java.

## Building from Source

Requires Rust >= 1.85.0 and Python >= 3.10.

```bash
git clone https://github.com/Kosthi/OpenACE.git
cd OpenACE
pip install maturin
maturin develop --release
pip install -e ".[dev]"
```

## License

MIT