sciogen 0.1.0__tar.gz

sciogen-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# sciogen index (generated per-project; never committed)
+.sciogen/
+
+# Python build / packaging
+build/
+dist/
+*.egg-info/
+__pycache__/
+*.py[cod]
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Local tool settings
+.claude/settings.local.json
+
+# OS / editor
+.DS_Store
+Thumbs.db
+*.swp
+.idea/
+.vscode/
+
+#MD Files
+CLAUDE.md
+RELEASING.md
+site/_artifact_body.html

sciogen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sciogen contributors
+
+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.

sciogen-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: sciogen
+Version: 0.1.0
+Summary: Codebase intelligence layer — a queryable knowledge graph over your code.
+Project-URL: Homepage, https://github.com/ayanbag/sciogen
+Project-URL: Repository, https://github.com/ayanbag/sciogen
+Project-URL: Documentation, https://github.com/ayanbag/sciogen/tree/main/docs
+Project-URL: Issues, https://github.com/ayanbag/sciogen/issues
+Author: sciogen contributors
+License: MIT
+License-File: LICENSE
+Keywords: code-search,knowledge-graph,mcp,static-analysis,tree-sitter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: chromadb>=0.5
+Requires-Dist: kuzu>=0.7
+Requires-Dist: mcp>=1.0
+Requires-Dist: rich>=13.7
+Requires-Dist: tree-sitter-language-pack<1.0,>=0.6
+Requires-Dist: tree-sitter<0.26,>=0.22
+Requires-Dist: typer>=0.12
+Requires-Dist: watchdog>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest-timeout; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: embeddings
+Requires-Dist: einops; extra == 'embeddings'
+Requires-Dist: sentence-transformers>=3.0; extra == 'embeddings'
+Description-Content-Type: text/markdown
+
+<img src="site/public/logo.png" alt="Image" width="100%" />
+
+<div align="center">
+  <p>
+    <a href="https://pypi.org/project/sciogen/"><img alt="PyPI" src="https://img.shields.io/pypi/v/sciogen.svg"></a>
+    <a href="https://pypi.org/project/sciogen/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/sciogen.svg"></a>
+    <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  </p>
+</div>
+
+**Codebase intelligence layer** — a queryable knowledge graph over your code.
+
+sciogen parses a codebase once, resolves every reference to the exact definition it
+points to, and materializes the result into an embedded triple store. After that,
+questions like *"who calls `AuthService.login`?"*, *"what breaks if I change
+`UserModel.find_by_email`?"*, or *"where is the password hashing logic?"* are
+sub-second index lookups that return **typed objects with file/line locations** —
+not grep results, not raw source dumps.
+
+sciogen is a **static analysis and indexing tool**. It never calls an LLM, never
+counts tokens, and has no concept of a context window. It is to codebases what
+Elasticsearch is to documents: precomputed, queryable structure.
+
+```
+pip install sciogen
+sciogen index .
+```
+
+```
+  ███████╗ ██████╗██╗ ██████╗  ██████╗ ███████╗███╗   ██╗
+  ██╔════╝██╔════╝██║██╔═══██╗██╔════╝ ██╔════╝████╗  ██║
+  ███████╗██║     ██║██║   ██║██║  ███╗█████╗  ██╔██╗ ██║
+  ╚════██║██║     ██║██║   ██║██║   ██║██╔══╝  ██║╚██╗██║
+  ███████║╚██████╗██║╚██████╔╝╚██████╔╝███████╗██║ ╚████║
+  ╚══════╝ ╚═════╝╚═╝ ╚═════╝  ╚═════╝ ╚══════╝╚═╝  ╚═══╝
+  Codebase Intelligence Layer  v0.1.0
+
+✓ Scanning project structure...
+✓ Reading 143 files...
+✓ Parsing Python, TypeScript...
+✓ Building knowledge graph...
+✓ Embedding 1,204 symbols...
+✓ Linking dependencies...
+✓ Done! 1,204 nodes · 3,456 edges · indexed in 4.2s
+  Ready. Your codebase is now queryable.
+```
+
+## Why
+
+A coding agent understands a codebase by **reading files** — and files are the
+wrong granularity. To learn one function's callers it reads thousands of lines
+of source into its context window, burning tokens on noise. sciogen precomputes
+the structure once, so the same answer is a handful of typed records with exact
+`file:line` locations.
+
+You run `sciogen index .` once. The knowledge graph is written to a `.sciogen/`
+directory **inside the codebase**. From then on, an agent working in that repo
+reads the graph instead of the raw files — the callers of a symbol, the blast
+radius of a change, where a concept lives — for a fraction of the tokens a
+file-by-file crawl would cost. sciogen itself never calls an LLM and is unaware
+of tokens; the savings are a consequence of returning structure instead of
+source.
+
+```
+  index once  ─────────────►  .sciogen/  (graph stored in the repo)
+  (sciogen index .)                │
+                                   ▼
+  agent asks: "who calls login?"  →  typed records + file:line
+  agent asks: "what breaks if …?"  →  impact subgraph, not 40 files
+```
+
+## The two ways it's used
+
+**You — from the terminal.** `sciogen index .` builds the graph; `sciogen
+explore` opens it as an interactive browser GUI to inspect the codebase
+visually.
+
+**Your coding agent — over MCP.** `sciogen mcp .` exposes the graph to any
+agent (Claude Code, etc.) through the Model Context Protocol, so it can query
+callers, dependencies, impact, and semantic search directly instead of reading
+files. See [docs/mcp.md](docs/mcp.md).
+
+## What the graph gives an agent
+
+- **Exact call graphs** — a call to `login()` resolves to
+  `src/auth/service.py:AuthService.login`, not the string `"login"`. References
+  static analysis cannot prove (dynamic dispatch, injected dependencies) are kept
+  with a **low confidence score** rather than silently dropped, so the caller
+  chooses how much to trust each edge.
+- **Impact analysis** — everything that may break if a symbol changes:
+  transitive callers with hop counts, subclasses, implementors, tests, mutators —
+  and the same for a whole PR at once from a unified diff.
+- **Semantic + hybrid search** — local embeddings at four granularities (file,
+  class, function, chunk); hybrid mode expands vector hits through the graph.
+- **Incremental by design** — SHA256 differ with a stat fast path; a single-file
+  change re-indexes in under a second, and dependent files are re-linked without
+  being re-parsed.
+- **Interactive visualization** — `sciogen explore` renders the graph in your
+  browser from one self-contained HTML file. No server.
+
+## Getting started
+
+```bash
+pip install sciogen
+# optional, for real code-optimized semantic search (larger, one model download):
+pip install "sciogen[embeddings]"
+
+cd your-project
+sciogen index .          # build the graph (stored in ./.sciogen; incremental after)
+sciogen explore          # inspect it visually in the browser
+sciogen mcp .            # serve it to your coding agent over MCP
+```
+
+Add `.sciogen/` to your `.gitignore` — it's machine-local and regenerable.
+
+You can also query directly from the terminal for a quick look:
+
+```bash
+sciogen search "password hashing"      # semantic search
+sciogen callers AuthService.login      # who calls this?
+sciogen impact UserModel.find_by_email # what breaks if this changes?
+sciogen deps src/auth/service.py       # imports, transitive deps
+```
+
+See [docs/cli.md](docs/cli.md) for every command.
+
+## Architecture in one paragraph
+
+`sciogen index` runs a five-stage pipeline per file: **tree-sitter** parses
+(100+ languages, one API), a **normalizer** converts the language-specific AST
+into a universal IR (only this layer knows languages), the **symbol resolver**
+traces every reference to its exact definition with a confidence score, the
+**graph builder** materializes typed nodes/edges into **KuzuDB** (Cypher), and a
+**SHA256 differ** backed by **SQLite** makes re-runs incremental. Embeddings of
+normalized symbol summaries (never raw code) go to **ChromaDB** at four
+granularities. Queries are deterministic: structural queries hit KuzuDB, semantic
+queries hit ChromaDB, hybrid uses vector hits as seeds for graph expansion. The
+full design — including the performance architecture (parallel parsing, batched
+transactional writes, embed deduplication, incremental re-resolution) — is in
+[docs/architecture.md](docs/architecture.md).
+
+## Storage
+
+Everything is embedded — no servers, no ports, one `.sciogen/` directory:
+
+| Store | Role |
+|-------|------|
+| KuzuDB | Graph topology — nodes, typed edges, confidence scores |
+| ChromaDB | Vector embeddings at file/class/function/chunk granularity |
+| SQLite | File hashes, symbol table, reference records, schema version |
+
+Add `.sciogen/` to your `.gitignore`.
+
+## Documentation
+
+| Doc | Contents |
+|-----|----------|
+| [docs/quickstart.md](docs/quickstart.md) | Install, first index, first queries |
+| [docs/cli.md](docs/cli.md) | Every command and flag |
+| [docs/mcp.md](docs/mcp.md) | MCP tools and agent setup — how an agent consumes the graph |
+| [docs/schema.md](docs/schema.md) | Node types, edge types, confidence model |
+| [docs/architecture.md](docs/architecture.md) | The two phases, every design decision, performance architecture |
+| [docs/api.md](docs/api.md) | Embedded Python API — only if you're building tooling *on top of* sciogen |
+
+## Supported languages
+
+Full symbol extraction: **Python**, **JavaScript**, **TypeScript/TSX**.
+File-level indexing (parse check + file search): Go, Rust, Java, Ruby, PHP, C,
+C++, C#, Kotlin, Swift, Scala, Lua. Adding full support for a language means
+writing one normalizer — see [docs/architecture.md](docs/architecture.md#ast-normalizer).
+
+## Development
+
+```bash
+git clone <repo> && cd sciogen
+python -m venv .venv && .venv/Scripts/activate   # or bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+MIT license.

sciogen-0.1.0/README.md

@@ -0,0 +1,181 @@
+<img src="site/public/logo.png" alt="Image" width="100%" />
+
+<div align="center">
+  <p>
+    <a href="https://pypi.org/project/sciogen/"><img alt="PyPI" src="https://img.shields.io/pypi/v/sciogen.svg"></a>
+    <a href="https://pypi.org/project/sciogen/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/sciogen.svg"></a>
+    <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  </p>
+</div>
+
+**Codebase intelligence layer** — a queryable knowledge graph over your code.
+
+sciogen parses a codebase once, resolves every reference to the exact definition it
+points to, and materializes the result into an embedded triple store. After that,
+questions like *"who calls `AuthService.login`?"*, *"what breaks if I change
+`UserModel.find_by_email`?"*, or *"where is the password hashing logic?"* are
+sub-second index lookups that return **typed objects with file/line locations** —
+not grep results, not raw source dumps.
+
+sciogen is a **static analysis and indexing tool**. It never calls an LLM, never
+counts tokens, and has no concept of a context window. It is to codebases what
+Elasticsearch is to documents: precomputed, queryable structure.
+
+```
+pip install sciogen
+sciogen index .
+```
+
+```
+  ███████╗ ██████╗██╗ ██████╗  ██████╗ ███████╗███╗   ██╗
+  ██╔════╝██╔════╝██║██╔═══██╗██╔════╝ ██╔════╝████╗  ██║
+  ███████╗██║     ██║██║   ██║██║  ███╗█████╗  ██╔██╗ ██║
+  ╚════██║██║     ██║██║   ██║██║   ██║██╔══╝  ██║╚██╗██║
+  ███████║╚██████╗██║╚██████╔╝╚██████╔╝███████╗██║ ╚████║
+  ╚══════╝ ╚═════╝╚═╝ ╚═════╝  ╚═════╝ ╚══════╝╚═╝  ╚═══╝
+  Codebase Intelligence Layer  v0.1.0
+
+✓ Scanning project structure...
+✓ Reading 143 files...
+✓ Parsing Python, TypeScript...
+✓ Building knowledge graph...
+✓ Embedding 1,204 symbols...
+✓ Linking dependencies...
+✓ Done! 1,204 nodes · 3,456 edges · indexed in 4.2s
+  Ready. Your codebase is now queryable.
+```
+
+## Why
+
+A coding agent understands a codebase by **reading files** — and files are the
+wrong granularity. To learn one function's callers it reads thousands of lines
+of source into its context window, burning tokens on noise. sciogen precomputes
+the structure once, so the same answer is a handful of typed records with exact
+`file:line` locations.
+
+You run `sciogen index .` once. The knowledge graph is written to a `.sciogen/`
+directory **inside the codebase**. From then on, an agent working in that repo
+reads the graph instead of the raw files — the callers of a symbol, the blast
+radius of a change, where a concept lives — for a fraction of the tokens a
+file-by-file crawl would cost. sciogen itself never calls an LLM and is unaware
+of tokens; the savings are a consequence of returning structure instead of
+source.
+
+```
+  index once  ─────────────►  .sciogen/  (graph stored in the repo)
+  (sciogen index .)                │
+                                   ▼
+  agent asks: "who calls login?"  →  typed records + file:line
+  agent asks: "what breaks if …?"  →  impact subgraph, not 40 files
+```
+
+## The two ways it's used
+
+**You — from the terminal.** `sciogen index .` builds the graph; `sciogen
+explore` opens it as an interactive browser GUI to inspect the codebase
+visually.
+
+**Your coding agent — over MCP.** `sciogen mcp .` exposes the graph to any
+agent (Claude Code, etc.) through the Model Context Protocol, so it can query
+callers, dependencies, impact, and semantic search directly instead of reading
+files. See [docs/mcp.md](docs/mcp.md).
+
+## What the graph gives an agent
+
+- **Exact call graphs** — a call to `login()` resolves to
+  `src/auth/service.py:AuthService.login`, not the string `"login"`. References
+  static analysis cannot prove (dynamic dispatch, injected dependencies) are kept
+  with a **low confidence score** rather than silently dropped, so the caller
+  chooses how much to trust each edge.
+- **Impact analysis** — everything that may break if a symbol changes:
+  transitive callers with hop counts, subclasses, implementors, tests, mutators —
+  and the same for a whole PR at once from a unified diff.
+- **Semantic + hybrid search** — local embeddings at four granularities (file,
+  class, function, chunk); hybrid mode expands vector hits through the graph.
+- **Incremental by design** — SHA256 differ with a stat fast path; a single-file
+  change re-indexes in under a second, and dependent files are re-linked without
+  being re-parsed.
+- **Interactive visualization** — `sciogen explore` renders the graph in your
+  browser from one self-contained HTML file. No server.
+
+## Getting started
+
+```bash
+pip install sciogen
+# optional, for real code-optimized semantic search (larger, one model download):
+pip install "sciogen[embeddings]"
+
+cd your-project
+sciogen index .          # build the graph (stored in ./.sciogen; incremental after)
+sciogen explore          # inspect it visually in the browser
+sciogen mcp .            # serve it to your coding agent over MCP
+```
+
+Add `.sciogen/` to your `.gitignore` — it's machine-local and regenerable.
+
+You can also query directly from the terminal for a quick look:
+
+```bash
+sciogen search "password hashing"      # semantic search
+sciogen callers AuthService.login      # who calls this?
+sciogen impact UserModel.find_by_email # what breaks if this changes?
+sciogen deps src/auth/service.py       # imports, transitive deps
+```
+
+See [docs/cli.md](docs/cli.md) for every command.
+
+## Architecture in one paragraph
+
+`sciogen index` runs a five-stage pipeline per file: **tree-sitter** parses
+(100+ languages, one API), a **normalizer** converts the language-specific AST
+into a universal IR (only this layer knows languages), the **symbol resolver**
+traces every reference to its exact definition with a confidence score, the
+**graph builder** materializes typed nodes/edges into **KuzuDB** (Cypher), and a
+**SHA256 differ** backed by **SQLite** makes re-runs incremental. Embeddings of
+normalized symbol summaries (never raw code) go to **ChromaDB** at four
+granularities. Queries are deterministic: structural queries hit KuzuDB, semantic
+queries hit ChromaDB, hybrid uses vector hits as seeds for graph expansion. The
+full design — including the performance architecture (parallel parsing, batched
+transactional writes, embed deduplication, incremental re-resolution) — is in
+[docs/architecture.md](docs/architecture.md).
+
+## Storage
+
+Everything is embedded — no servers, no ports, one `.sciogen/` directory:
+
+| Store | Role |
+|-------|------|
+| KuzuDB | Graph topology — nodes, typed edges, confidence scores |
+| ChromaDB | Vector embeddings at file/class/function/chunk granularity |
+| SQLite | File hashes, symbol table, reference records, schema version |
+
+Add `.sciogen/` to your `.gitignore`.
+
+## Documentation
+
+| Doc | Contents |
+|-----|----------|
+| [docs/quickstart.md](docs/quickstart.md) | Install, first index, first queries |
+| [docs/cli.md](docs/cli.md) | Every command and flag |
+| [docs/mcp.md](docs/mcp.md) | MCP tools and agent setup — how an agent consumes the graph |
+| [docs/schema.md](docs/schema.md) | Node types, edge types, confidence model |
+| [docs/architecture.md](docs/architecture.md) | The two phases, every design decision, performance architecture |
+| [docs/api.md](docs/api.md) | Embedded Python API — only if you're building tooling *on top of* sciogen |
+
+## Supported languages
+
+Full symbol extraction: **Python**, **JavaScript**, **TypeScript/TSX**.
+File-level indexing (parse check + file search): Go, Rust, Java, Ruby, PHP, C,
+C++, C#, Kotlin, Swift, Scala, Lua. Adding full support for a language means
+writing one normalizer — see [docs/architecture.md](docs/architecture.md#ast-normalizer).
+
+## Development
+
+```bash
+git clone <repo> && cd sciogen
+python -m venv .venv && .venv/Scripts/activate   # or bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+MIT license.

sciogen-0.1.0/docs/api.md

@@ -0,0 +1,127 @@
+# Python API
+
+The whole library is one facade class, `SciogenGraph`, reached through
+`sciogen.open()`. The CLI and MCP server are thin adapters over it.
+
+```python
+import sciogen
+
+graph = sciogen.open("path/to/repo")   # opens (creates) the .sciogen index
+graph.index()                          # incremental build; returns IndexStats
+```
+
+`SciogenGraph` is a context manager; stores open lazily on first use.
+
+```python
+with sciogen.open(".") as graph:
+    graph.index()
+    info = graph.get_symbol("AuthService.login")
+```
+
+## Indexing
+
+### `graph.index(reporter=None, rebuild=False) -> IndexStats`
+
+Build or incrementally update the index. `rebuild=True` wipes `.sciogen/` first.
+`reporter` is an optional progress sink (the CLI passes a Rich adapter; omit for
+silence).
+
+```python
+stats = graph.index()
+stats.nodes, stats.edges, stats.seconds
+stats.files_indexed, stats.files_unchanged, stats.files_deleted, stats.files_failed
+stats.errors   # list[(path, error_message)]
+```
+
+## Structural queries
+
+All return typed dataclasses with `.to_dict()`. Every node reference carries an
+exact `file` / `line_start` / `line_end`.
+
+### `get_symbol(name, file=None) -> SymbolInfo`
+
+```python
+info = graph.get_symbol("AuthService.login")
+info.node.kind            # "FunctionNode"
+info.node.file            # "src/auth/service.py"
+info.node.params          # ["self", "username: str", "password: str"]
+info.node.line_start
+info.relations            # [Relation(kind, other, direction, confidence), ...]
+```
+
+Pass `file=` to disambiguate a name defined in several places. Raises
+`sciogen.query.engine.SymbolNotFound` if nothing matches.
+
+### `get_callers(symbol, depth=1, min_confidence=0.0) -> ImpactGraph`
+
+```python
+result = graph.get_callers("hash_password", depth=2)
+for item in result.impacted:                 # sorted by (hops, -confidence)
+    item.node.id, item.hops, item.confidence, item.relation
+```
+
+`confidence` is the path confidence — the weakest edge along the best path.
+
+### `analyze_impact(symbol, max_depth=5, min_confidence=0.0) -> ImpactGraph`
+
+Everything that may break if `symbol` changes: transitive callers (up to
+`max_depth`) plus one-hop subclasses, implementors, tests, and mutators.
+
+### `get_dependencies(file) -> DependencyInfo`
+
+```python
+deps = graph.get_dependencies("src/auth/service.py")
+deps.direct_files          # files directly imported
+deps.transitive_files      # reachable beyond direct
+deps.external_modules      # third-party / stdlib module names
+```
+
+### `get_diff_impact(unified_diff) -> DiffImpact`
+
+Feed a unified diff; get the union impact of every symbol it touches.
+
+```python
+result = graph.get_diff_impact(open("pr.diff").read())
+result.changed_symbols     # symbols whose lines the diff overlaps
+result.unmatched_files     # files in the diff not in the index
+result.impact              # ImpactGraph over all changed symbols at once
+```
+
+## Semantic & hybrid queries
+
+### `search(query, mode="semantic", granularity=None, k=10) -> SearchResults`
+
+```python
+graph.search("password hashing logic")
+graph.search("all code related to auth", mode="hybrid")
+graph.search("classes that manage sessions", granularity="class")
+
+for hit in results.hits:
+    hit.node, hit.score, hit.granularity, hit.via   # via: "semantic" | "graph"
+```
+
+`hybrid` mode uses vector hits as seeds and expands through the graph;
+graph-expanded hits are marked `via="graph"`.
+
+### `get_context_for_task(description, k=15) -> ContextBundle`
+
+Broad intent → curated subgraph.
+
+```python
+bundle = graph.get_context_for_task("add rate limiting to login")
+bundle.files       # ranked most-relevant first
+bundle.symbols     # SearchHit list
+```
+
+## Result types
+
+All defined in `sciogen.query.results`, all plain dataclasses with `.to_dict()`:
+`SymbolNode`, `SymbolInfo`, `Relation`, `ImpactedSymbol`, `ImpactGraph`,
+`DependencyInfo`, `SearchHit`, `SearchResults`, `DiffImpact`, `ContextBundle`.
+
+## Notes
+
+- Query results are memoized in an LRU keyed by the index version; a re-index
+  invalidates the whole cache at once.
+- Queries never return raw source code — only typed nodes with locations. The
+  caller decides whether to open the file.