grapheinstein 0.1.0__tar.gz

grapheinstein-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Zanini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

grapheinstein-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: grapheinstein
+Version: 0.1.0
+Summary: Local-first project knowledge graph CLI
+Author-email: Joe Zanini <jozanini@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Joezanini/grapheinstein
+Project-URL: Repository, https://github.com/Joezanini/grapheinstein
+Project-URL: Issues, https://github.com/Joezanini/grapheinstein/issues
+Keywords: cli,knowledge-graph,code-analysis,local-first,offline,tree-sitter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: networkx>=3.2
+Requires-Dist: pathspec>=0.12
+Requires-Dist: rich>=13.7
+Requires-Dist: loguru>=0.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tree-sitter>=0.23
+Requires-Dist: tree-sitter-python>=0.23
+Requires-Dist: tree-sitter-javascript>=0.23
+Requires-Dist: tree-sitter-typescript>=0.23
+Requires-Dist: tree-sitter-java>=0.23
+Requires-Dist: tree-sitter-go>=0.23
+Requires-Dist: tree-sitter-rust>=0.23
+Requires-Dist: tree-sitter-cpp>=0.23
+Requires-Dist: tree-sitter-sql>=0.3
+Requires-Dist: pymupdf>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Provides-Extra: media
+Requires-Dist: pytesseract>=0.3.10; extra == "media"
+Requires-Dist: Pillow>=10.0; extra == "media"
+Requires-Dist: faster-whisper>=1.0; extra == "media"
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.115; extra == "serve"
+Requires-Dist: uvicorn[standard]>=0.30; extra == "serve"
+Dynamic: license-file
+
+# Grapheinstein
+
+Local-first CLI that maps a project folder into a portable `graph.json` knowledge graph for AI agents.
+
+Offline by design — indexing, explain, path, and query use the local filesystem and optional local models (e.g. Ollama). No cloud APIs required.
+
+Schema version: **6.0.0**.
+
+## Install
+
+```bash
+pip install grapheinstein
+# Optional local HTTP API:
+# pip install 'grapheinstein[serve]'
+# Optional OCR / audio extras:
+# pip install 'grapheinstein[media]'
+```
+
+### From source
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+# Optional local HTTP API:
+# pip install -e ".[dev,serve]"
+```
+
+## Quick start
+
+```bash
+# Create a commented starter config (~/.grapheinstein/config.yaml by default)
+grapheinstein init
+# or: grapheinstein init --output ./grapheinstein.yaml
+
+# Index a project (default command)
+grapheinstein /path/to/project --output graph.json
+
+# Explicit index with project config
+grapheinstein index /path/to/project -o graph.json --config ./grapheinstein.yaml
+
+# Explain / path / query over an existing graph
+grapheinstein explain "authentication" -i graph.json -o explain.json --no-summary
+grapheinstein path "login" "database" -i graph.json --no-llm-explain
+grapheinstein query "How does auth work?" -i graph.json -o sub.json --no-answer
+
+# Console summary / status
+grapheinstein visualize --input graph.json
+grapheinstein status --output graph.json
+
+# Optional local HTTP (requires: pip install 'grapheinstein[serve]')
+grapheinstein serve --port 8000
+```
+
+## Agent integration
+
+Agents and Cursor slash-commands should call the Python API (same semantics as the CLI):
+
+```python
+from grapheinstein.api import index, query
+```
+
+Optional HTTP: `POST /index` and `POST /query` via `grapheinstein serve` (loopback by default).
+
+See [docs/agent-integration.md](docs/agent-integration.md) for copy-paste examples and CLI ↔ Python ↔ HTTP parity.
+
+## Configuration
+
+Config precedence: CLI flags > `--config` file > `~/.grapheinstein/config.yaml` > built-ins.
+
+Key settings (see `grapheinstein init` for a full commented template):
+
+| Key | Purpose |
+|-----|---------|
+| `ignored_patterns` | Extra gitignore-style paths beyond `.gitignore` |
+| `embedding_model` | Local model for embeddings |
+| `llm_model` | Local model for enrichment / answers |
+| `max_file_size` | Skip parsing files larger than this (bytes; default 10 MiB) |
+| `cache_dir` | Local cache for ASTs / chunks / embeddings (default `~/.grapheinstein/cache`) |
+
+Re-indexing an unchanged project reuses the cache under `cache_dir` for faster runs.
+
+## Validation
+
+```bash
+pytest
+ruff check src tests
+```
+
+Feature quickstarts live under `specs/*/quickstart.md` (e.g. `specs/011-config-cache-init/quickstart.md`).
+
+## Contributing
+
+Community contributions are welcome — bug fixes, docs, tests, and features that fit the project’s local-first CLI goals.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, validation, and how to propose a change.

grapheinstein-0.1.0/README.md

@@ -0,0 +1,96 @@
+# Grapheinstein
+
+Local-first CLI that maps a project folder into a portable `graph.json` knowledge graph for AI agents.
+
+Offline by design — indexing, explain, path, and query use the local filesystem and optional local models (e.g. Ollama). No cloud APIs required.
+
+Schema version: **6.0.0**.
+
+## Install
+
+```bash
+pip install grapheinstein
+# Optional local HTTP API:
+# pip install 'grapheinstein[serve]'
+# Optional OCR / audio extras:
+# pip install 'grapheinstein[media]'
+```
+
+### From source
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+# Optional local HTTP API:
+# pip install -e ".[dev,serve]"
+```
+
+## Quick start
+
+```bash
+# Create a commented starter config (~/.grapheinstein/config.yaml by default)
+grapheinstein init
+# or: grapheinstein init --output ./grapheinstein.yaml
+
+# Index a project (default command)
+grapheinstein /path/to/project --output graph.json
+
+# Explicit index with project config
+grapheinstein index /path/to/project -o graph.json --config ./grapheinstein.yaml
+
+# Explain / path / query over an existing graph
+grapheinstein explain "authentication" -i graph.json -o explain.json --no-summary
+grapheinstein path "login" "database" -i graph.json --no-llm-explain
+grapheinstein query "How does auth work?" -i graph.json -o sub.json --no-answer
+
+# Console summary / status
+grapheinstein visualize --input graph.json
+grapheinstein status --output graph.json
+
+# Optional local HTTP (requires: pip install 'grapheinstein[serve]')
+grapheinstein serve --port 8000
+```
+
+## Agent integration
+
+Agents and Cursor slash-commands should call the Python API (same semantics as the CLI):
+
+```python
+from grapheinstein.api import index, query
+```
+
+Optional HTTP: `POST /index` and `POST /query` via `grapheinstein serve` (loopback by default).
+
+See [docs/agent-integration.md](docs/agent-integration.md) for copy-paste examples and CLI ↔ Python ↔ HTTP parity.
+
+## Configuration
+
+Config precedence: CLI flags > `--config` file > `~/.grapheinstein/config.yaml` > built-ins.
+
+Key settings (see `grapheinstein init` for a full commented template):
+
+| Key | Purpose |
+|-----|---------|
+| `ignored_patterns` | Extra gitignore-style paths beyond `.gitignore` |
+| `embedding_model` | Local model for embeddings |
+| `llm_model` | Local model for enrichment / answers |
+| `max_file_size` | Skip parsing files larger than this (bytes; default 10 MiB) |
+| `cache_dir` | Local cache for ASTs / chunks / embeddings (default `~/.grapheinstein/cache`) |
+
+Re-indexing an unchanged project reuses the cache under `cache_dir` for faster runs.
+
+## Validation
+
+```bash
+pytest
+ruff check src tests
+```
+
+Feature quickstarts live under `specs/*/quickstart.md` (e.g. `specs/011-config-cache-init/quickstart.md`).
+
+## Contributing
+
+Community contributions are welcome — bug fixes, docs, tests, and features that fit the project’s local-first CLI goals.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, validation, and how to propose a change.

grapheinstein-0.1.0/pyproject.toml

@@ -0,0 +1,115 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "grapheinstein"
+version = "0.1.0"
+description = "Local-first project knowledge graph CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Joe Zanini", email = "jozanini@users.noreply.github.com" },
+]
+keywords = [
+  "cli",
+  "knowledge-graph",
+  "code-analysis",
+  "local-first",
+  "offline",
+  "tree-sitter",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "typer>=0.12",
+  "networkx>=3.2",
+  "pathspec>=0.12",
+  "rich>=13.7",
+  "loguru>=0.7",
+  "pyyaml>=6.0",
+  "tree-sitter>=0.23",
+  "tree-sitter-python>=0.23",
+  "tree-sitter-javascript>=0.23",
+  "tree-sitter-typescript>=0.23",
+  "tree-sitter-java>=0.23",
+  "tree-sitter-go>=0.23",
+  "tree-sitter-rust>=0.23",
+  "tree-sitter-cpp>=0.23",
+  "tree-sitter-sql>=0.3",
+  "pymupdf>=1.24",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "httpx>=0.27", "ruff>=0.8"]
+media = [
+  "pytesseract>=0.3.10",
+  "Pillow>=10.0",
+  "faster-whisper>=1.0",
+]
+serve = [
+  "fastapi>=0.115",
+  "uvicorn[standard]>=0.30",
+]
+
+[project.scripts]
+grapheinstein = "grapheinstein.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/Joezanini/grapheinstein"
+Repository = "https://github.com/Joezanini/grapheinstein"
+Issues = "https://github.com/Joezanini/grapheinstein/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+exclude = [
+  ".venv",
+  "venv",
+  "build",
+  "dist",
+  "tests/fixtures",
+]
+
+[tool.ruff.lint]
+select = [
+  "E",   # pycodestyle errors
+  "W",   # pycodestyle warnings
+  "F",   # Pyflakes
+  "I",   # isort
+  "UP",  # pyupgrade
+  "B",   # flake8-bugbear
+]
+ignore = [
+  "E501",  # line length: keep readable long strings/CLI help without noisy failures
+  "B008",  # function calls in defaults (Typer / FastAPI patterns)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+  "B017",  # pytest.raises(Exception) used intentionally in a few contracts
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

grapheinstein-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

grapheinstein-0.1.0/src/grapheinstein/__init__.py

@@ -0,0 +1,3 @@
+"""Grapheinstein: local-first project knowledge graph CLI."""
+
+__version__ = "0.1.0"

grapheinstein-0.1.0/src/grapheinstein/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m grapheinstein`."""
+
+from grapheinstein.cli import app
+
+if __name__ == "__main__":
+    app()  # argv-rewriting entry (supports bare project path)

grapheinstein-0.1.0/src/grapheinstein/api.py

@@ -0,0 +1,195 @@
+"""Public Python API for agent / slash-command integration.
+
+Importing this module MUST NOT require FastAPI or Uvicorn.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import asdict, dataclass, is_dataclass
+from pathlib import Path
+from typing import Any
+
+from grapheinstein.core.cache import CacheStore
+from grapheinstein.core.graph import GraphError, GraphStats, load_artifact
+from grapheinstein.core.index import MediaExtrasError, index_project
+from grapheinstein.core.parsers import LanguageError, parse_languages_csv
+from grapheinstein.core.query import (
+    EmptyCorpusError,
+    NoEvidenceError,
+    QueryError,
+    run_query,
+)
+from grapheinstein.utils import ConfigError, load_config, setup_logging
+
+__all__ = [
+    "IndexResult",
+    "index",
+    "query",
+    "stats_to_dict",
+    "ConfigError",
+    "GraphError",
+    "MediaExtrasError",
+    "QueryError",
+    "EmptyCorpusError",
+    "NoEvidenceError",
+]
+
+
+@dataclass(frozen=True)
+class IndexResult:
+    """Result of a successful API index call."""
+
+    output_path: Path
+    stats: GraphStats | dict[str, Any]
+    artifact: dict[str, Any] | None = None
+
+
+def _stats_as_dict(stats: GraphStats | dict[str, Any]) -> dict[str, Any]:
+    if isinstance(stats, dict):
+        return dict(stats)
+    if is_dataclass(stats):
+        return asdict(stats)
+    return {
+        "total_nodes": getattr(stats, "total_nodes", 0),
+        "graph_path": str(getattr(stats, "graph_path", "")),
+    }
+
+
+def _normalize_languages(
+    languages: str | Sequence[str] | None,
+) -> list[str] | None:
+    if languages is None:
+        return None
+    if isinstance(languages, str):
+        try:
+            return list(parse_languages_csv(languages))
+        except LanguageError as exc:
+            raise ConfigError(str(exc)) from exc
+    try:
+        return list(languages)
+    except TypeError as exc:
+        raise ConfigError("languages must be a string or sequence of strings") from exc
+
+
+def index(
+    project_path: str | Path,
+    *,
+    output: str | Path | None = None,
+    config: str | Path | None = None,
+    languages: str | Sequence[str] | None = None,
+    include_docs: bool = False,
+    include_pdfs: bool = False,
+    transcribe_media: bool = False,
+    enrich_llm: bool = False,
+    llm_model: str | None = None,
+    llm_base_url: str | None = None,
+    embedding_model: str | None = None,
+    compress: bool = False,
+    versioned: bool = False,
+    include_artifact: bool = False,
+    show_progress: bool = False,
+) -> IndexResult:
+    """
+    Index a project folder into a portable graph (CLI `index` semantics).
+
+    Raises FileNotFoundError, NotADirectoryError, OSError, ConfigError,
+    GraphError, MediaExtrasError on hard failures — never returns an empty success.
+    """
+    languages_override = _normalize_languages(languages)
+    cfg = load_config(
+        config_path=Path(config).expanduser() if config is not None else None,
+        output_override=Path(output).expanduser() if output is not None else None,
+        languages_override=languages_override,
+        llm_model_override=llm_model,
+        llm_base_url_override=llm_base_url,
+        embedding_model_override=embedding_model,
+        compress_override=True if compress else None,
+        versioned_override=True if versioned else None,
+    )
+    setup_logging(cfg.log_level)
+    output_path = Path(cfg.output)
+
+    written, stats = index_project(
+        Path(project_path),
+        output_path,
+        languages=list(cfg.languages),
+        include_docs=include_docs,
+        include_pdfs=include_pdfs,
+        transcribe_media=transcribe_media,
+        enrich_llm=enrich_llm,
+        llm_model=cfg.llm_model,
+        llm_base_url=cfg.llm_base_url,
+        llm_confidence_threshold=cfg.llm_confidence_threshold,
+        compress=cfg.compress,
+        versioned=cfg.versioned,
+        ignored_patterns=list(cfg.ignored_patterns),
+        max_file_size=cfg.max_file_size,
+        cache_dir=cfg.cache_dir,
+        embedding_model=cfg.embedding_model,
+        show_progress=show_progress,
+    )
+
+    artifact: dict[str, Any] | None = None
+    if include_artifact:
+        artifact = load_artifact(written)
+
+    return IndexResult(output_path=written, stats=stats, artifact=artifact)
+
+
+def query(
+    question: str,
+    *,
+    input: str | Path,
+    output: str | Path | None = None,
+    config: str | Path | None = None,
+    k: int | None = None,
+    hops: int | None = None,
+    match_threshold: float | None = None,
+    no_answer: bool = False,
+    llm_model: str | None = None,
+    llm_base_url: str | None = None,
+    embedding_model: str | None = None,
+) -> dict[str, Any]:
+    """
+    Answer a natural-language question over a graph (CLI `query` semantics).
+
+    Returns the query-answer JSON envelope (schema_version 1.0.0).
+    """
+    input_path = Path(input).expanduser()
+    if output is not None:
+        output_path = Path(output).expanduser()
+    else:
+        output_path = input_path.parent / "subgraph.json"
+
+    cfg = load_config(
+        config_path=Path(config).expanduser() if config is not None else None,
+        llm_model_override=llm_model,
+        llm_base_url_override=llm_base_url,
+        embedding_model_override=embedding_model,
+        query_k_override=k,
+        query_hops_override=hops,
+        query_match_threshold_override=match_threshold,
+    )
+    setup_logging(cfg.log_level)
+
+    result = run_query(
+        question,
+        input_path,
+        output_path,
+        k=cfg.query_k,
+        hops=cfg.query_hops,
+        match_threshold=cfg.query_match_threshold,
+        node_cap=cfg.query_node_cap,
+        want_answer=not no_answer,
+        llm_model=cfg.llm_model,
+        llm_base_url=cfg.llm_base_url,
+        embedding_model=cfg.embedding_model,
+        cache=CacheStore(cfg.cache_dir),
+    )
+    return dict(result.answer_envelope)
+
+
+def stats_to_dict(stats: GraphStats | dict[str, Any]) -> dict[str, Any]:
+    """Serialize index stats for HTTP / agents."""
+    return _stats_as_dict(stats)