Metadata-Version: 2.4
Name: openground
Version: 0.8.3
Summary: Ingest official documentation into a local vector database and expose it via MCP for AI coding agents
Project-URL: Homepage, https://github.com/poweroutlet2/openground
Project-URL: Repository, https://github.com/poweroutlet2/openground
Project-URL: Issues, https://github.com/poweroutlet2/openground/issues
License-Expression: MIT
License-File: LICENSE
Keywords: ai,coding-assistant,documentation,embeddings,mcp,vector-database
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Requires-Dist: aiohttp<4.0.0,>=3.8.0
Requires-Dist: fastmcp<3.0.0,>=2.13.3
Requires-Dist: lancedb<1.0.0,>=0.1.0
Requires-Dist: langchain-text-splitters<2.0.0,>=1.0.0
Requires-Dist: nbformat<6.0.0,>=5.0.0
Requires-Dist: pandas<3.0.0,>=2.3.3
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: rich<15.0.0,>=14.0.0
Requires-Dist: sentence-transformers<6.0.0,>=5.0.0
Requires-Dist: torch<3.0.0,>=2.0.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: trafilatura<3.0.0,>=2.0.0
Requires-Dist: typer<1.0.0,>=0.9.0
Provides-Extra: fastembed-gpu
Requires-Dist: fastembed-gpu<1.0.0,>=0.2.0; extra == 'fastembed-gpu'
Description-Content-Type: text/markdown

# openground

[![PyPI version](https://img.shields.io/pypi/v/openground?logo=pypi)](https://pypi.org/project/openground/)

tldr: openground lets you give controlled access to documentation to AI agents. Everything happens on-device.

openground is an on-device RAG system that extracts documentation from git repos and sitemaps, embeds it for semantic search, and exposes it to AI agents via MCP. It uses a local embedding model, and local lancedb for storing embeddings and for hybrid vector similarity and BM25 full-text search.

## Architecture

```
      ┌─────────────────────────────────────────────────────────────────────┐
      │                           OPENGROUND                                │
      ├─────────────────────────────────────────────────────────────────────┤
      │                                                                     │
      │       SOURCE                  PROCESS              STORAGE/CLIENT   │
      │                                                                     │
      │    ┌──────────┐      ┌───────────┐   ┌──────────┐   ┌──────────┐    │
      │    │ git repo ├─────>│  Extract  ├──>│  Chunk   ├──>│ LanceDB  │    │
      │    |   -or-   |      │ (raw_data)│   │   Text   │   │ (vector  │    │
      │    │ sitemap  │      └───────────┘   └──────────┘   │  +BM25)  │    │
      │    └──────────┘                           │         └────┬─────┘    │
      │                                           ▼              │          │
      │                                    ┌───────────┐         │          │
      │                                    │   Local   |<────────┘          │
      │                                    │ Embedding │         │          │
      │                                    │   Model   │         ▼          │
      │                                    └───────────┘  ┌─────────────┐   │
      │                                                   │ CLI / MCP   │   │
      │                                                   │  (hybrid    │   │
      |                                                   |   search)   |   |
      │                                                   └─────────────┘   │
      │                                                                     │
      └─────────────────────────────────────────────────────────────────────┘
```

## Quick Start

### Installation

Recommended to install with [uv](https://docs.astral.sh/uv/):

```bash
uv tool install openground
```

or

```bash
pip install openground
```

### Add Documentation

Openground can source documentation from git repos or sitemaps.

To add documentation from a git repo to openground, run:

```bash
openground add library-name \
  --source https://github.com/example/example.git \
  --docs-path docs/ \
  --version v1.0.0 \
  -y
```

The `--version` flag specifies a git tag to checkout (defaults to latest).

To add documentation from a sitemap to openground, run:

```bash
openground add library-name \
  --source https://docs.example.com/sitemap.xml \
  --filter-keyword docs/ \
  --filter-keyword blog/ \
  -y
```

This will download the docs, embed them, and store them into lancedb. All locally.

Multiple versions of the same library can be stored and queried independently.

### Use with AI Agents

To install the MCP server:

```bash
# For Cursor
openground install-mcp --cursor

# For Claude Code
openground install-mcp --claude-code

# For OpenCode
openground install-mcp --opencode

# For any other agent
openground install-mcp
```

Now your AI assistant can search your stored documentation automatically!

## Example Workflow

Here's how to add the fastembed documentation and make it available to Claude Code:

```bash
# 1. Install openground
uv tool install openground

# 2. Add fastembed to openground
openground add fastembed --source https://github.com/qdrant/fastembed.git --docs-path docs/ --version v0.7.4 -y

# 3. Configure Claude Code to use openground MCP
openground install-mcp --claude-code

# 4. Restart Claude Code
# Now you can ask: "What models are available in fastembed?"
# Claude will search the fastembed docs automatically!
```

## MCP Usage Statistics
To see how many times each tool in the MCP server has been called:

```bash
openground stats show # show stats
openground stats clear # reset stats
```
## Development

To contribute or work on openground locally:

```bash
git clone https://github.com/poweroutlet2/openground.git
cd openground
uv sync .
```

## License

MIT
