Metadata-Version: 2.4
Name: csegraph
Version: 1.8.0
Summary: Repository context engine for coding agents with CLI, MCP server, and Python facade.
Author: Rishabh Shah, Hitanshu Oza
License-Expression: MIT
Project-URL: Repository, https://github.com/RishiiShah/CseGraph
Project-URL: Issues, https://github.com/RishiiShah/CseGraph/issues
Project-URL: Documentation, https://github.com/RishiiShah/CseGraph/tree/main/docs
Project-URL: Changelog, https://github.com/RishiiShah/CseGraph/blob/main/CHANGELOG.md
Keywords: code graph,context,coding agents,mcp,tree-sitter
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.0.0
Requires-Dist: watchfiles<2,>=1.0.0
Requires-Dist: tomlkit<1,>=0.12.0
Requires-Dist: tree-sitter>=0.23
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter-javascript>=0.23
Provides-Extra: test
Requires-Dist: pytest>=9.0.3; extra == "test"
Requires-Dist: setuptools>=68; extra == "test"
Provides-Extra: benchmark
Requires-Dist: tiktoken<1,>=0.13; extra == "benchmark"
Provides-Extra: dev
Requires-Dist: coverage[toml]>=7.6; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: pre-commit>=4.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=1.7.1; extra == "embeddings"
Provides-Extra: go
Requires-Dist: tree-sitter-go>=0.23; extra == "go"
Provides-Extra: rust
Requires-Dist: tree-sitter-rust>=0.23; extra == "rust"
Provides-Extra: java
Requires-Dist: tree-sitter-java>=0.23; extra == "java"
Provides-Extra: c
Requires-Dist: tree-sitter-c>=0.23; extra == "c"
Provides-Extra: cpp
Requires-Dist: tree-sitter-cpp>=0.23; extra == "cpp"
Provides-Extra: ruby
Requires-Dist: tree-sitter-ruby>=0.23; extra == "ruby"
Provides-Extra: csharp
Requires-Dist: tree-sitter-c-sharp>=0.23; extra == "csharp"
Provides-Extra: kotlin
Requires-Dist: tree-sitter-kotlin>=0.23; extra == "kotlin"
Provides-Extra: groovy
Requires-Dist: tree-sitter-groovy>=0.1.2; extra == "groovy"
Provides-Extra: scala
Requires-Dist: tree-sitter-scala>=0.23; extra == "scala"
Provides-Extra: php
Requires-Dist: tree-sitter-php>=0.23; extra == "php"
Provides-Extra: swift
Requires-Dist: tree-sitter-swift>=0.7; extra == "swift"
Provides-Extra: lua
Requires-Dist: tree-sitter-lua>=0.2; extra == "lua"
Provides-Extra: zig
Requires-Dist: tree-sitter-zig>=0.1; extra == "zig"
Provides-Extra: powershell
Requires-Dist: tree-sitter-powershell>=0.1; extra == "powershell"
Provides-Extra: elixir
Requires-Dist: tree-sitter-elixir>=0.3; extra == "elixir"
Provides-Extra: objc
Requires-Dist: tree-sitter-objc>=0.23; extra == "objc"
Provides-Extra: julia
Requires-Dist: tree-sitter-julia>=0.23; extra == "julia"
Provides-Extra: verilog
Requires-Dist: tree-sitter-verilog>=0.23; extra == "verilog"
Provides-Extra: fortran
Requires-Dist: tree-sitter-fortran>=0.6; extra == "fortran"
Provides-Extra: all
Requires-Dist: tree-sitter-go>=0.23; extra == "all"
Requires-Dist: tree-sitter-rust>=0.23; extra == "all"
Requires-Dist: tree-sitter-java>=0.23; extra == "all"
Requires-Dist: tree-sitter-c>=0.23; extra == "all"
Requires-Dist: tree-sitter-cpp>=0.23; extra == "all"
Requires-Dist: tree-sitter-ruby>=0.23; extra == "all"
Requires-Dist: tree-sitter-c-sharp>=0.23; extra == "all"
Requires-Dist: tree-sitter-kotlin>=0.23; extra == "all"
Requires-Dist: tree-sitter-groovy>=0.1.2; extra == "all"
Requires-Dist: tree-sitter-scala>=0.23; extra == "all"
Requires-Dist: tree-sitter-php>=0.23; extra == "all"
Requires-Dist: tree-sitter-swift>=0.7; extra == "all"
Requires-Dist: tree-sitter-lua>=0.2; extra == "all"
Requires-Dist: tree-sitter-zig>=0.1; extra == "all"
Requires-Dist: tree-sitter-powershell>=0.1; extra == "all"
Requires-Dist: tree-sitter-elixir>=0.3; extra == "all"
Requires-Dist: tree-sitter-objc>=0.23; extra == "all"
Requires-Dist: tree-sitter-julia>=0.23; extra == "all"
Requires-Dist: tree-sitter-verilog>=0.23; extra == "all"
Requires-Dist: tree-sitter-fortran>=0.6; extra == "all"
Dynamic: license-file

# csegraph

[![CI](https://github.com/RishiiShah/CseGraph/actions/workflows/ci.yml/badge.svg)](https://github.com/RishiiShah/CseGraph/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/csegraph.svg)](https://pypi.org/project/csegraph/)
[![Python](https://img.shields.io/pypi/pyversions/csegraph.svg)](https://pypi.org/project/csegraph/)
[![License](https://img.shields.io/pypi/l/csegraph.svg)](LICENSE)
[![VS Code installs](https://img.shields.io/visual-studio-marketplace/i/rishiishah.csegraph-vscode?label=VS%20Code%20installs)](https://marketplace.visualstudio.com/items?itemName=rishiishah.csegraph-vscode)

CseGraph is a **context engine for coding agents**. Its only job is to hand an agent the accurate, minimal slice of code context needed to make a correct retrieval or edit, so the agent spends fewer tokens and skips tool calls it would otherwise make (broad grep, full-file read, repeated lookups).

It indexes source code into a SQLite-backed dependency graph, then returns compact, task-specific context bundles before an agent edits.

The product loop is:

```text
index -> refresh -> context -> optional inspect/path/analyze
```

Use csegraph when you want an agent to see the target code, direct dependencies, imports, nearby tests, and a short explanation of why each node was selected without repeatedly scanning the repository.

## Install

Current release: `1.8.0`.

```bash
pip install csegraph
```

To pin this release exactly:

```bash
pip install csegraph==1.8.0
```

The base package includes Python, JavaScript, and TypeScript grammars. Install
extra grammars only when you need them:

```bash
pip install "csegraph[go,rust]"
pip install "csegraph[all]"
```

Then run `csegraph --help` to confirm the CLI is on your PATH.

## Five Minute Quickstart

```bash
cd /path/to/your/repo
csegraph index .
csegraph context "explain how authentication refresh works" --detail-level standard --format markdown
```

The default index lives at `.csegraph/index.db`. It is local runtime state and
should not be committed.

For VS Code extension install and setup, see
[csegraph-vscode/README.md](csegraph-vscode/README.md).

## Benchmarks & Performance

The native MCP cross-repo benchmarking suite (`tools/cross_repo_benchmark.py`)
evaluates CseGraph against 10 major open-source repositories, generating 100
unique architectural queries per repository through the same stdio JSON-RPC path
used by coding agents. Current `auto`, `small`, `medium`, and `large` profile
results are recorded in the [Agent Context Benchmarks](docs/benchmarks.md).

## Package Layout

| Package | Location | Purpose |
|---|---|---|
| `csegraph` | repo root | One Python distribution containing the public CLI, MCP server, SDK facade, and private engine internals. |
| `csegraph-vscode` | `csegraph-vscode/` | VS Code extension source. See [extension README](csegraph-vscode/README.md). |

Public Python imports use `csegraph`. Internal implementation modules live under `csegraph._core` and `csegraph._cli`; they are not documented as public API.

## Install From Source

```bash
env/bin/pip install -e .
```

For local development and test runs, install the test extra:

```bash
env/bin/python -m pip install -e ".[test,all]"
```

For benchmark reports with OpenAI proxy token counts, include the benchmark
extra:

```bash
env/bin/python -m pip install -e ".[benchmark,test,all]"
```

`requirements.txt` contains the product-only editable install.

This repository is source-first. The public project is distributed as one Python
package and the VS Code extension source; generated binaries, local graph
databases, build outputs, and dashboard artifacts are not committed.

## Project Hygiene

- Security policy: [SECURITY.md](SECURITY.md)
- Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- Support guide: [SUPPORT.md](SUPPORT.md)
- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
- Release checklist: [RELEASE.md](RELEASE.md)
- Changelog: [CHANGELOG.md](CHANGELOG.md)
- CLI, MCP, and SDK reference: [docs/csegraph.md](docs/csegraph.md)
- Architecture reference: [docs/architecture.md](docs/architecture.md)

## Privacy and Local Files

CseGraph is local-first. Indexes are written under the target repository's
`.csegraph/` directory, while registry and daemon metadata use `~/.csegraph/`
for registered repository paths, database paths, daemon PID files, and logs.

No network request is required for normal indexing, retrieval, or MCP stdio. The
optional embeddings workflow can call an OpenAI-compatible endpoint only when
explicitly configured and allowed with
`CSEGRAPH_ALLOW_CLOUD_EMBEDDINGS`; that sends symbol text to the configured
endpoint.

## Development

```bash
pytest                              # Full test suite
pytest tests/unit/                  # Unit tests only
pytest tests/integration/           # Integration tests only
pytest -x -q                        # Stop on first failure, quiet
python -m compileall -q csegraph tools csegraph-vscode
csegraph --help
```

## License

CseGraph is released under the MIT License. See [LICENSE](LICENSE).
