Metadata-Version: 2.4
Name: code-knowledge-graph-tool
Version: 0.1.11
Summary: Code Structure with Graph — graph-powered code intelligence
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: fastapi>=0.135.2
Requires-Dist: jsonpatch>=1.33
Requires-Dist: kreuzberg>=4.7
Requires-Dist: kuzu>=0.8
Requires-Dist: langchain-community>=0.3
Requires-Dist: langchain-core>=0.3
Requires-Dist: langchain-mcp-adapters>=0.2.2
Requires-Dist: langchain-openai>=1.1.11
Requires-Dist: langgraph-checkpoint>=4.0.1
Requires-Dist: langgraph>=0.2
Requires-Dist: langmem>=0.0.30
Requires-Dist: leidenalg>=0.10
Requires-Dist: mcp>=1.0
Requires-Dist: numpy>=1.26
Requires-Dist: pathspec>=0.12
Requires-Dist: pydantic>=2.0
Requires-Dist: python-docx>=1.2.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: python-igraph>=0.11
Requires-Dist: python-multipart>=0.0.22
Requires-Dist: rich>=13.0
Requires-Dist: starlette>=0.36
Requires-Dist: tiktoken>=0.12.0
Requires-Dist: tree-sitter-ada>=0.1.0
Requires-Dist: tree-sitter-c-sharp>=0.23
Requires-Dist: tree-sitter-c>=0.24
Requires-Dist: tree-sitter-commonlisp>=0.4.1
Requires-Dist: tree-sitter-cpp>=0.23
Requires-Dist: tree-sitter-delphi>=0.1.0
Requires-Dist: tree-sitter-fortran>=0.5.1
Requires-Dist: tree-sitter-go>=0.24
Requires-Dist: tree-sitter-java>=0.23
Requires-Dist: tree-sitter-javascript>=0.24
Requires-Dist: tree-sitter-kotlin>=1.0
Requires-Dist: tree-sitter-matlab>=1.3.0
Requires-Dist: tree-sitter-objc>=3.0.2
Requires-Dist: tree-sitter-php>=0.24
Requires-Dist: tree-sitter-python>=0.24
Requires-Dist: tree-sitter-ruby>=0.23
Requires-Dist: tree-sitter-rust>=0.24
Requires-Dist: tree-sitter-scala>=0.24.0
Requires-Dist: tree-sitter-solidity>=1.2.13
Requires-Dist: tree-sitter-swift>=0.0.1
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter>=0.24
Requires-Dist: uvicorn[standard]>=0.42.0
Requires-Dist: watchfiles>=1.1
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: ocr-gemini
Requires-Dist: google-genai>=1.0; extra == 'ocr-gemini'
Provides-Extra: ocr-paddle
Requires-Dist: kreuzberg[paddle]; extra == 'ocr-paddle'
Description-Content-Type: text/markdown

# CSG - Code Structure with Graph

CSG is a local code intelligence tool for building a graph index of a source
repository and exposing that index to AI coding agents through MCP.

It parses source code with deterministic AST tooling, stores symbols and
relationships in an embedded Kuzu graph database, and provides MCP tools for
code exploration, impact analysis, change review, and graph-aware navigation.

## Install

```bash
uv tool install --python 3.12 --index-url https://pypi.org/simple --refresh code-knowledge-graph-tool
```

Upgrade later with:

```bash
uv tool upgrade code-knowledge-graph-tool
```

## One-Time OpenAI Setup

Semantic embeddings use OpenAI embeddings. Configure your key once:

```bash
csg config set openai-api-key sk-your-openai-api-key
```

This key is stored in CSG's local user config and is reused by:

- `csg analyze --embeddings`
- `csg watch`
- `csg mcp` launched by Claude Code, Codex, or VS Code MCP clients

You can also use `OPENAI_API_KEY` or `CSG_OPENAI_API_KEY` as environment
overrides. If no key is configured, CSG still builds the graph and skips
embeddings with a clear reminder.

## Basic Workflow

Run these commands from the repository you want to index:

```bash
cd /path/to/your/repo
csg analyze . --embeddings
csg setup .
```

`csg analyze` builds the local graph index. `csg setup` installs repo-local
agent guidance files and registers the CSG MCP server for supported agent CLIs.

To keep indexed repositories fresh while you work:

```bash
csg watch
```

## MCP Usage

After setup, AI agents can use CSG MCP tools automatically:

- `csg_list_repos`: discover indexed repositories
- `csg_explore`: search and explore graph layers
- `csg_context`: inspect a symbol with callers, callees, and source context
- `csg_impact`: check blast radius before edits
- `csg_detect_changes`: map git changes to affected symbols and flows
- `csg_rename`: preview graph-aware symbol renames
- `csg_analyze`: index a repository from the MCP client

Manual MCP registration is also possible:

```bash
claude mcp add --transport stdio --scope user csg -- csg mcp
codex mcp add csg -- csg mcp
```

MCP clients that use JSON configuration can launch:

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

## Common Commands

```bash
csg analyze .                    # Build graph index
csg analyze . --force            # Rebuild index
csg analyze . --embeddings       # Build graph plus OpenAI embeddings
csg setup .                      # Install agent files and register MCP
csg setup-agents .               # Install repo-local agent files only
csg status                       # Show index status for current repo
csg list                         # List indexed repositories
csg watch                        # Watch indexed repos for changes
csg logs                         # Show MCP logs
csg clean                        # Delete current repo index
```

## Data Storage

For normal local repositories, CSG stores graph data inside the target checkout:

```text
<repo>/.csg/
  meta.json
  lbug/
  cache/
```

A small global registry is also maintained so MCP clients can discover indexed
repositories.

## Notes

- Indexing does not require an LLM.
- Embeddings require an OpenAI key.
- No local PyTorch, CUDA, or Hugging Face embedding model is installed by the
  package.
- If embeddings are skipped, graph navigation, context, impact analysis, and
  BM25 search still work.
