swift-kg 0.2.0__tar.gz

swift_kg-0.2.0/LICENSE

@@ -0,0 +1,94 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+**You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.**
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to the
+software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms or the URL for them above, as well as copies of
+any plain-text lines beginning with "Required Notice:" that the licensor provided
+with the software. For example:
+
+Required Notice: Copyright (c) 2026 Eric G. Suchanek, PhD
+
+## No Other Rights
+
+These terms do not imply any other licenses not expressly granted in this
+license.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you with
+a notice of your violation, and you cease all violation of this license no later
+than 30 days after you receive that notice, your licenses will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any
+additional violation of these terms will cause your licenses to terminate
+automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising out
+of these terms or the use or nature of the software, under any kind of legal
+claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion of
+it.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+Control means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.
+
+**Trademark** means trademarks, service marks, and similar rights.

swift_kg-0.2.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: swift-kg
+Version: 0.2.0
+Summary: Knowledge graph for Swift codebases -- AST extraction, hybrid semantic+structural search
+License-Expression: Elastic-2.0
+License-File: LICENSE
+Keywords: knowledge-graph,swift,ios,ast,sqlite-vec,sqlite,semantic-search
+Author: Eric G. Suchanek, PhD
+Author-email: suchanek@mac.com
+Requires-Python: >=3.12,<3.14
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: click (>=8.1.0,<9)
+Requires-Dist: kgmodule-utils[semantic,sqlite-vec] (>=0.21.0)
+Requires-Dist: mcp (>=1.0.0,<2)
+Requires-Dist: networkx (>=3.0)
+Requires-Dist: rich (>=14.3.3,<15)
+Requires-Dist: tree-sitter (>=0.25.0)
+Requires-Dist: tree-sitter-swift (>=0.7.0)
+Project-URL: Homepage, https://github.com/Flux-Frontiers/swift_kg
+Project-URL: Repository, https://github.com/Flux-Frontiers/swift_kg
+Description-Content-Type: text/markdown
+
+# SwiftKG
+
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
+[![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
+[![PyPI](https://img.shields.io/pypi/v/swift-kg.svg)](https://pypi.org/project/swift-kg/)
+[![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)](https://github.com/Flux-Frontiers/swift_kg/releases)
+[![CI](https://github.com/Flux-Frontiers/swift_kg/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/swift_kg/actions/workflows/ci.yml)
+[![Docs](https://github.com/Flux-Frontiers/swift_kg/actions/workflows/docs.yml/badge.svg)](https://github.com/Flux-Frontiers/swift_kg/actions/workflows/docs.yml)
+[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
+
+Knowledge graph for Swift codebases -- deterministic AST extraction, hybrid semantic + structural search.
+
+## Overview
+
+SwiftKG builds a queryable knowledge graph from Swift source using:
+
+- **tree-sitter** for deterministic, parser-level AST extraction (no LLM inference during indexing)
+- **SQLite** for the structural graph (nodes, edges, provenance)
+- **sqlite-vec** for the semantic vector index (embeddings via `BAAI/bge-small-en-v1.5`)
+- **Hybrid retrieval**: semantic seed → graph hop expansion → lexical re-ranking
+
+It needs no Swift toolchain, no Xcode, and no buildable project. Point it at
+any checkout, on macOS or on Linux CI, and it indexes.
+
+## What Swift makes different
+
+Three things about Swift are not cosmetic differences from the Python and
+TypeScript modules in this fleet, and they shape the whole graph.
+
+**Inheritance and conformance are written identically.** `: Base, Proto` gives
+no syntactic signal about which is which:
+
+```swift
+final class DiskStorage: Storage<Data> {}   // superclass
+struct Point: Equatable, Hashable {}        // two protocols
+class Storage<T>: NSObject, Repository {}   // superclass, then protocol
+```
+
+SwiftKG runs two passes. The first builds a repository-wide table of every
+declared type and its kind; the second resolves each specifier against it, so
+a protocol target becomes `CONFORMS` and a class or actor target becomes
+`INHERITS`. When the target is external — `NSObject`, `Codable`, anything from
+a dependency — it falls back to the language's own rule: only a class or actor
+may have a superclass, and it must be written first.
+
+**There are no per-file imports within a module.** Every file in a target sees
+every other file's declarations without an import statement. That makes the
+repository the correct resolution scope rather than an approximation of one,
+so calls and type references resolve across files. A name declared twice
+resolves to nothing rather than to an arbitrary one of the two — an honest
+`sym:` stub beats a confidently wrong edge.
+
+**Extensions are a unit of authorship.** A type's conformances and much of its
+behaviour routinely live in an extension in a different file. Each extension
+gets its own node and an `EXTENDS` edge to the type, with members qualified
+under the type (`Point.scaled`), so `swiftkg` can answer "where is the rest of
+this type" without losing where the code actually is. Since it is idiomatic to
+write one extension per conformance, an extension's own ID carries its
+conformance list (`ext:…:Point+Codable`) rather than colliding on the type name.
+
+Swift also states access level with a keyword, so `public` / `open` /
+`internal` / `private` is recorded as a fact rather than guessed from a naming
+convention. The public-API report, the centrality penalty for private symbols,
+and `explain`'s reasoning about zero-caller declarations all read it directly.
+
+## Node types
+
+| Kind | Description |
+|------|-------------|
+| `module` | Every indexed `.swift` file |
+| `class` | Class declaration |
+| `struct` | Struct declaration |
+| `enum` | Enum declaration |
+| `protocol` | Protocol declaration |
+| `actor` | Actor declaration |
+| `extension` | Extension declaration |
+| `function` | Free function at file scope |
+| `method` | Function, initializer, deinitializer or subscript inside a type |
+| `property` | Stored or computed property, enum case, or file-scope `let`/`var` |
+| `typealias` | Type alias, and `associatedtype` inside a protocol |
+| `symbol` | Unresolved import or call stub |
+
+## Edge types
+
+| Relation | Description |
+|----------|-------------|
+| `CONTAINS` | module → type/function, type → member |
+| `IMPORTS` | module → `sym:<Module>` (a Swift import names a module, not a file) |
+| `CALLS` | function/method → function, method, or type initializer |
+| `INHERITS` | class or actor → superclass |
+| `CONFORMS` | type or extension → protocol |
+| `EXTENDS` | extension → the type it extends |
+
+## Quick start
+
+```bash
+pip install swift-kg
+
+# First-time setup (downloads model, builds graph, installs hooks, snapshots)
+swiftkg init --repo /path/to/swift-repo
+
+# Build the KG for a Swift repo
+swiftkg build --repo /path/to/swift-repo
+
+# Query
+swiftkg query "networking layer"
+swiftkg pack "request error handling" --hop 2
+
+# Understand the repository
+swiftkg analyze /path/to/swift-repo
+swiftkg centrality --top 20
+swiftkg explain "proto:Sources/Networking/Client.swift:HTTPClienting"
+```
+
+`build` wipes and rebuilds; `update` upserts without wiping. The split is
+deliberate — a rebuild is correct after renames or deletions, where an upsert
+leaves phantom nodes behind, so the safe operation is the bare verb and the
+surprising one has to be asked for by name.
+
+## MCP tools
+
+`swiftkg mcp --repo /path/to/swift-repo` exposes 21 tools. Two exist only in
+this module:
+
+| Tool | Purpose |
+|------|---------|
+| `type_hierarchy(node_id)` | Conformers, subclasses, extensions and declared supertypes of one type, together — for a Swift type these are one question |
+| `public_api(module_path, limit)` | The declared `public` / `open` surface, read from access levels |
+
+The rest match the fleet: `graph_stats`, `query_codebase`, `pack_snippets`,
+`callers`, `get_node`, `list_nodes`, `find_node`, `centrality`,
+`bridge_centrality`, `framework_nodes`, `find_definition_at`, `analyze_repo`,
+`explain`, `rank_nodes`, `query_ranked`, `explain_rank`, `snapshot_list`,
+`snapshot_show`, `snapshot_diff`.
+
+See [`docs/MCP.md`](docs/MCP.md) for client configuration.
+
+## Snapshots & git hook
+
+`swiftkg snapshot save` records graph metrics under `.swiftkg/snapshots/`, and
+`swiftkg install-hooks` installs a pre-commit hook that keeps them current.
+Alongside the shared metrics, SwiftKG records what actually characterises a
+Swift codebase: counts by type kind, conformance and inheritance counts, and
+extensions-per-type — how much behaviour is declared away from the type it
+belongs to.
+
+Snapshots, not per-node timestamps, are how a code KG answers temporal
+questions. Git already owns when the code changed.
+
+## Python API
+
+```python
+from swift_kg import SwiftKG
+
+with SwiftKG(repo_root="/path/to/swift-repo") as kg:
+    kg.build(wipe=True)
+
+    result = kg.query("networking layer", k=8)
+    pack = kg.pack("request error handling")
+    pack.save("context.md")
+
+    protocol_id = "proto:Sources/Networking/Client.swift:HTTPClienting"
+    kg.conformers(protocol_id)      # every conforming type and extension
+    kg.subclasses(class_id)         # direct subclasses
+    kg.extensions_of(type_id)       # extensions, wherever they are declared
+```
+
+## Configuration
+
+When the target repository has a `pyproject.toml`, SwiftKG reads
+`[tool.swiftkg]`:
+
+```toml
+[tool.swiftkg]
+include = ["Sources"]     # top-level dirs to index (unset = all)
+exclude = ["Vendor"]      # extra dirs to skip at every depth
+```
+
+Most Swift repositories have no `pyproject.toml`, which is fine: with no
+config, everything is indexed. `.build`, `.swiftpm`, `DerivedData`, `Pods`,
+`Carthage`, `xcuserdata` and `*.xcodeproj` / `*.xcworkspace` bundles are always
+skipped.
+
+## Architecture
+
+```
+Swift source ─► tree-sitter ─► pass 1: symbol table
+                            └► pass 2: NodeSpec / EdgeSpec
+                                      │
+                                      ├─► SQLite   (authoritative graph)
+                                      └─► sqlite-vec (semantic index)
+                                                │
+                              hybrid query ◄────┘
+                                    │
+                        CLI · MCP server · Python API
+```
+
+Everything below the extractor — persistence, indexing, hybrid retrieval,
+snippet packing, snapshots — comes from
+[`kgmodule-utils`](https://pypi.org/project/kgmodule-utils/). This package
+implements the Swift-specific layer and nothing else.
+
+## Status
+
+The visualizers (`swiftkg viz`, `viz3d`, `viz-timeline`) are registered and
+report that they are not yet available; see the CHANGELOG's Unreleased
+section. Everything else is complete.
+
+## Author
+
+Eric G. Suchanek, PhD — [Flux-Frontiers](https://github.com/Flux-Frontiers)
+
+## Citation
+
+See [`CITATION.cff`](CITATION.cff).
+
+## License
+
+[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license). See
+[`LICENSE`](LICENSE).
+

swift_kg-0.2.0/README.md

@@ -0,0 +1,220 @@
+# SwiftKG
+
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
+[![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
+[![PyPI](https://img.shields.io/pypi/v/swift-kg.svg)](https://pypi.org/project/swift-kg/)
+[![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)](https://github.com/Flux-Frontiers/swift_kg/releases)
+[![CI](https://github.com/Flux-Frontiers/swift_kg/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/swift_kg/actions/workflows/ci.yml)
+[![Docs](https://github.com/Flux-Frontiers/swift_kg/actions/workflows/docs.yml/badge.svg)](https://github.com/Flux-Frontiers/swift_kg/actions/workflows/docs.yml)
+[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
+
+Knowledge graph for Swift codebases -- deterministic AST extraction, hybrid semantic + structural search.
+
+## Overview
+
+SwiftKG builds a queryable knowledge graph from Swift source using:
+
+- **tree-sitter** for deterministic, parser-level AST extraction (no LLM inference during indexing)
+- **SQLite** for the structural graph (nodes, edges, provenance)
+- **sqlite-vec** for the semantic vector index (embeddings via `BAAI/bge-small-en-v1.5`)
+- **Hybrid retrieval**: semantic seed → graph hop expansion → lexical re-ranking
+
+It needs no Swift toolchain, no Xcode, and no buildable project. Point it at
+any checkout, on macOS or on Linux CI, and it indexes.
+
+## What Swift makes different
+
+Three things about Swift are not cosmetic differences from the Python and
+TypeScript modules in this fleet, and they shape the whole graph.
+
+**Inheritance and conformance are written identically.** `: Base, Proto` gives
+no syntactic signal about which is which:
+
+```swift
+final class DiskStorage: Storage<Data> {}   // superclass
+struct Point: Equatable, Hashable {}        // two protocols
+class Storage<T>: NSObject, Repository {}   // superclass, then protocol
+```
+
+SwiftKG runs two passes. The first builds a repository-wide table of every
+declared type and its kind; the second resolves each specifier against it, so
+a protocol target becomes `CONFORMS` and a class or actor target becomes
+`INHERITS`. When the target is external — `NSObject`, `Codable`, anything from
+a dependency — it falls back to the language's own rule: only a class or actor
+may have a superclass, and it must be written first.
+
+**There are no per-file imports within a module.** Every file in a target sees
+every other file's declarations without an import statement. That makes the
+repository the correct resolution scope rather than an approximation of one,
+so calls and type references resolve across files. A name declared twice
+resolves to nothing rather than to an arbitrary one of the two — an honest
+`sym:` stub beats a confidently wrong edge.
+
+**Extensions are a unit of authorship.** A type's conformances and much of its
+behaviour routinely live in an extension in a different file. Each extension
+gets its own node and an `EXTENDS` edge to the type, with members qualified
+under the type (`Point.scaled`), so `swiftkg` can answer "where is the rest of
+this type" without losing where the code actually is. Since it is idiomatic to
+write one extension per conformance, an extension's own ID carries its
+conformance list (`ext:…:Point+Codable`) rather than colliding on the type name.
+
+Swift also states access level with a keyword, so `public` / `open` /
+`internal` / `private` is recorded as a fact rather than guessed from a naming
+convention. The public-API report, the centrality penalty for private symbols,
+and `explain`'s reasoning about zero-caller declarations all read it directly.
+
+## Node types
+
+| Kind | Description |
+|------|-------------|
+| `module` | Every indexed `.swift` file |
+| `class` | Class declaration |
+| `struct` | Struct declaration |
+| `enum` | Enum declaration |
+| `protocol` | Protocol declaration |
+| `actor` | Actor declaration |
+| `extension` | Extension declaration |
+| `function` | Free function at file scope |
+| `method` | Function, initializer, deinitializer or subscript inside a type |
+| `property` | Stored or computed property, enum case, or file-scope `let`/`var` |
+| `typealias` | Type alias, and `associatedtype` inside a protocol |
+| `symbol` | Unresolved import or call stub |
+
+## Edge types
+
+| Relation | Description |
+|----------|-------------|
+| `CONTAINS` | module → type/function, type → member |
+| `IMPORTS` | module → `sym:<Module>` (a Swift import names a module, not a file) |
+| `CALLS` | function/method → function, method, or type initializer |
+| `INHERITS` | class or actor → superclass |
+| `CONFORMS` | type or extension → protocol |
+| `EXTENDS` | extension → the type it extends |
+
+## Quick start
+
+```bash
+pip install swift-kg
+
+# First-time setup (downloads model, builds graph, installs hooks, snapshots)
+swiftkg init --repo /path/to/swift-repo
+
+# Build the KG for a Swift repo
+swiftkg build --repo /path/to/swift-repo
+
+# Query
+swiftkg query "networking layer"
+swiftkg pack "request error handling" --hop 2
+
+# Understand the repository
+swiftkg analyze /path/to/swift-repo
+swiftkg centrality --top 20
+swiftkg explain "proto:Sources/Networking/Client.swift:HTTPClienting"
+```
+
+`build` wipes and rebuilds; `update` upserts without wiping. The split is
+deliberate — a rebuild is correct after renames or deletions, where an upsert
+leaves phantom nodes behind, so the safe operation is the bare verb and the
+surprising one has to be asked for by name.
+
+## MCP tools
+
+`swiftkg mcp --repo /path/to/swift-repo` exposes 21 tools. Two exist only in
+this module:
+
+| Tool | Purpose |
+|------|---------|
+| `type_hierarchy(node_id)` | Conformers, subclasses, extensions and declared supertypes of one type, together — for a Swift type these are one question |
+| `public_api(module_path, limit)` | The declared `public` / `open` surface, read from access levels |
+
+The rest match the fleet: `graph_stats`, `query_codebase`, `pack_snippets`,
+`callers`, `get_node`, `list_nodes`, `find_node`, `centrality`,
+`bridge_centrality`, `framework_nodes`, `find_definition_at`, `analyze_repo`,
+`explain`, `rank_nodes`, `query_ranked`, `explain_rank`, `snapshot_list`,
+`snapshot_show`, `snapshot_diff`.
+
+See [`docs/MCP.md`](docs/MCP.md) for client configuration.
+
+## Snapshots & git hook
+
+`swiftkg snapshot save` records graph metrics under `.swiftkg/snapshots/`, and
+`swiftkg install-hooks` installs a pre-commit hook that keeps them current.
+Alongside the shared metrics, SwiftKG records what actually characterises a
+Swift codebase: counts by type kind, conformance and inheritance counts, and
+extensions-per-type — how much behaviour is declared away from the type it
+belongs to.
+
+Snapshots, not per-node timestamps, are how a code KG answers temporal
+questions. Git already owns when the code changed.
+
+## Python API
+
+```python
+from swift_kg import SwiftKG
+
+with SwiftKG(repo_root="/path/to/swift-repo") as kg:
+    kg.build(wipe=True)
+
+    result = kg.query("networking layer", k=8)
+    pack = kg.pack("request error handling")
+    pack.save("context.md")
+
+    protocol_id = "proto:Sources/Networking/Client.swift:HTTPClienting"
+    kg.conformers(protocol_id)      # every conforming type and extension
+    kg.subclasses(class_id)         # direct subclasses
+    kg.extensions_of(type_id)       # extensions, wherever they are declared
+```
+
+## Configuration
+
+When the target repository has a `pyproject.toml`, SwiftKG reads
+`[tool.swiftkg]`:
+
+```toml
+[tool.swiftkg]
+include = ["Sources"]     # top-level dirs to index (unset = all)
+exclude = ["Vendor"]      # extra dirs to skip at every depth
+```
+
+Most Swift repositories have no `pyproject.toml`, which is fine: with no
+config, everything is indexed. `.build`, `.swiftpm`, `DerivedData`, `Pods`,
+`Carthage`, `xcuserdata` and `*.xcodeproj` / `*.xcworkspace` bundles are always
+skipped.
+
+## Architecture
+
+```
+Swift source ─► tree-sitter ─► pass 1: symbol table
+                            └► pass 2: NodeSpec / EdgeSpec
+                                      │
+                                      ├─► SQLite   (authoritative graph)
+                                      └─► sqlite-vec (semantic index)
+                                                │
+                              hybrid query ◄────┘
+                                    │
+                        CLI · MCP server · Python API
+```
+
+Everything below the extractor — persistence, indexing, hybrid retrieval,
+snippet packing, snapshots — comes from
+[`kgmodule-utils`](https://pypi.org/project/kgmodule-utils/). This package
+implements the Swift-specific layer and nothing else.
+
+## Status
+
+The visualizers (`swiftkg viz`, `viz3d`, `viz-timeline`) are registered and
+report that they are not yet available; see the CHANGELOG's Unreleased
+section. Everything else is complete.
+
+## Author
+
+Eric G. Suchanek, PhD — [Flux-Frontiers](https://github.com/Flux-Frontiers)
+
+## Citation
+
+See [`CITATION.cff`](CITATION.cff).
+
+## License
+
+[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license). See
+[`LICENSE`](LICENSE).