ue-knowledge-base 0.1.0__tar.gz

ue_knowledge_base-0.1.0/LICENSE

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

ue_knowledge_base-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: ue-knowledge-base
+Version: 0.1.0
+Summary: Offline semantic search over Unreal Engine development knowledge (BGE + ChromaDB)
+Author: Dong
+License: MIT
+Keywords: unreal-engine,rag,semantic-search,chromadb,knowledge-base
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sentence-transformers>=2.6
+Requires-Dist: chromadb>=0.5
+Dynamic: license-file
+
+# UE Knowledge Base
+
+Offline semantic search over Unreal Engine development knowledge — a curated
+**Chinese-language knowledge corpus** (29 topics: GAS, animation, AI,
+networking, UMG, Niagara, PCG, ...) plus a local RAG pipeline that indexes it
+with `BAAI/bge-small-zh-v1.5` embeddings into ChromaDB.
+
+**Zero API cost. Fully offline after a one-time model download.** Built for
+Chinese-speaking UE developers, and ready to plug into any AI agent, IDE, or
+CLI workflow.
+
+```
+knowledge/  (29 topics, ~84 markdown docs)
+    │  ue-kb build          chunk + embed (BGE small, local)
+    ▼
+.chroma_db/  (vector index)
+    │  ue-kb query "GAS cooldown"
+    ▼
+top-k semantic hits with source + heading
+```
+
+## Features
+
+- 📚 **Curated corpus**: hand-written UE development docs in Chinese, covering
+  Gameplay Ability System, character movement, animation, physics/collision,
+  AI navigation, networking/replication, UMG/Slate, Niagara, Mass Entity,
+  State Trees, PCG/procedural generation, materials/rendering, module build
+  system, editor tools, and more.
+- 🧠 **Local semantic search**: `BAAI/bge-small-zh-v1.5` (multilingual, ~100MB)
+  + ChromaDB — no cloud APIs, no cost, works on a laptop CPU.
+- 🖥️ **Simple CLI** (`ue-kb`): `build`, `query`, `info`, `download-model`,
+  plus `--json` output for agent integration.
+- 🔌 **Extensible**: index any extra UE docs with `--source`, or add engine
+  source-indexing scripts under `scripts/`.
+
+## Quick start
+
+```bash
+# 1. Install
+pip install -e .                 # or: pip install ue-knowledge-base
+
+# 2. Download the embedding model once (~100MB)
+ue-kb download-model
+#    In China:  export HF_ENDPOINT=https://hf-mirror.com  then retry
+
+# 3. Build the index
+ue-kb build
+
+# 4. Search
+ue-kb query "GAS ability cooldown" --top-k 5
+ue-kb query "角色移动 速度衰减" --json   # machine-readable for agents
+```
+
+### Example
+
+```text
+$ ue-kb query "GAS 技能冷却"
+🔍 UE 知识库检索：GAS 技能冷却
+
+[1] ue-gameplay-abilities/references/gas-input-integration.md › 问题 (匹配度: 21.1%)
+    UE 项目同时使用 GAS (GameplayAbilitySystem) 和 Enhanced Input 时，容易陷入
+    两个极端：- **全 GAS** → 所有输入走 GAS，但 WASD 轴输入不适合 GAS 的事件
+    模型，且 CommitAbility 的 GC 延迟影响跳跃手感 ...
+[2] ue-gameplay-abilities/references/gas-input-integration.md › Jump — GAS 即时技能 (匹配度: 14.2%)
+    ...
+```
+
+## Python API
+
+```python
+from ue_knowledge.query import query
+
+for hit in query("GAS cooldown", top_k=5):
+    print(hit["source"], hit["heading"], hit["score"])
+```
+
+## Extending the corpus
+
+1. Add a markdown file under `knowledge/<topic>/` (use `##`/`###` headings —
+   the indexer chunks on heading boundaries).
+2. `ue-kb build --force` to rebuild.
+
+For indexing **Unreal Engine C++ header comments** or **Epic official docs**,
+see `scripts/index_engine_source.py` and `scripts/crawl_epic_docs.py`
+(they expect local engine/UE paths — the extracted index data is generated
+locally and is not redistributed, out of respect for Epic's copyright).
+
+## License
+
+MIT. The knowledge documents are original writing; no engine source code or
+verbatim Epic documentation is included.

ue_knowledge_base-0.1.0/README.md

@@ -0,0 +1,91 @@
+# UE Knowledge Base
+
+Offline semantic search over Unreal Engine development knowledge — a curated
+**Chinese-language knowledge corpus** (29 topics: GAS, animation, AI,
+networking, UMG, Niagara, PCG, ...) plus a local RAG pipeline that indexes it
+with `BAAI/bge-small-zh-v1.5` embeddings into ChromaDB.
+
+**Zero API cost. Fully offline after a one-time model download.** Built for
+Chinese-speaking UE developers, and ready to plug into any AI agent, IDE, or
+CLI workflow.
+
+```
+knowledge/  (29 topics, ~84 markdown docs)
+    │  ue-kb build          chunk + embed (BGE small, local)
+    ▼
+.chroma_db/  (vector index)
+    │  ue-kb query "GAS cooldown"
+    ▼
+top-k semantic hits with source + heading
+```
+
+## Features
+
+- 📚 **Curated corpus**: hand-written UE development docs in Chinese, covering
+  Gameplay Ability System, character movement, animation, physics/collision,
+  AI navigation, networking/replication, UMG/Slate, Niagara, Mass Entity,
+  State Trees, PCG/procedural generation, materials/rendering, module build
+  system, editor tools, and more.
+- 🧠 **Local semantic search**: `BAAI/bge-small-zh-v1.5` (multilingual, ~100MB)
+  + ChromaDB — no cloud APIs, no cost, works on a laptop CPU.
+- 🖥️ **Simple CLI** (`ue-kb`): `build`, `query`, `info`, `download-model`,
+  plus `--json` output for agent integration.
+- 🔌 **Extensible**: index any extra UE docs with `--source`, or add engine
+  source-indexing scripts under `scripts/`.
+
+## Quick start
+
+```bash
+# 1. Install
+pip install -e .                 # or: pip install ue-knowledge-base
+
+# 2. Download the embedding model once (~100MB)
+ue-kb download-model
+#    In China:  export HF_ENDPOINT=https://hf-mirror.com  then retry
+
+# 3. Build the index
+ue-kb build
+
+# 4. Search
+ue-kb query "GAS ability cooldown" --top-k 5
+ue-kb query "角色移动 速度衰减" --json   # machine-readable for agents
+```
+
+### Example
+
+```text
+$ ue-kb query "GAS 技能冷却"
+🔍 UE 知识库检索：GAS 技能冷却
+
+[1] ue-gameplay-abilities/references/gas-input-integration.md › 问题 (匹配度: 21.1%)
+    UE 项目同时使用 GAS (GameplayAbilitySystem) 和 Enhanced Input 时，容易陷入
+    两个极端：- **全 GAS** → 所有输入走 GAS，但 WASD 轴输入不适合 GAS 的事件
+    模型，且 CommitAbility 的 GC 延迟影响跳跃手感 ...
+[2] ue-gameplay-abilities/references/gas-input-integration.md › Jump — GAS 即时技能 (匹配度: 14.2%)
+    ...
+```
+
+## Python API
+
+```python
+from ue_knowledge.query import query
+
+for hit in query("GAS cooldown", top_k=5):
+    print(hit["source"], hit["heading"], hit["score"])
+```
+
+## Extending the corpus
+
+1. Add a markdown file under `knowledge/<topic>/` (use `##`/`###` headings —
+   the indexer chunks on heading boundaries).
+2. `ue-kb build --force` to rebuild.
+
+For indexing **Unreal Engine C++ header comments** or **Epic official docs**,
+see `scripts/index_engine_source.py` and `scripts/crawl_epic_docs.py`
+(they expect local engine/UE paths — the extracted index data is generated
+locally and is not redistributed, out of respect for Epic's copyright).
+
+## License
+
+MIT. The knowledge documents are original writing; no engine source code or
+verbatim Epic documentation is included.

ue_knowledge_base-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ue-knowledge-base"
+version = "0.1.0"
+description = "Offline semantic search over Unreal Engine development knowledge (BGE + ChromaDB)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Dong" }]
+keywords = ["unreal-engine", "rag", "semantic-search", "chromadb", "knowledge-base"]
+dependencies = [
+    "sentence-transformers>=2.6",
+    "chromadb>=0.5",
+]
+
+[project.scripts]
+ue-kb = "ue_knowledge.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ue_knowledge_base-0.1.0/setup.cfg

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

ue_knowledge_base-0.1.0/src/ue_knowledge/__init__.py

@@ -0,0 +1,8 @@
+"""ue_knowledge — offline semantic search over Unreal Engine development docs.
+
+Build a local vector index from the bundled knowledge/ markdown corpus
+(BAAI/bge-small-zh-v1.5 embeddings + ChromaDB), then query it with a CLI
+or from Python. Zero API cost, fully offline after the one-time model download.
+"""
+
+__version__ = "0.1.0"

ue_knowledge_base-0.1.0/src/ue_knowledge/build.py

@@ -0,0 +1,90 @@
+"""Index building — embed the corpus and store it in ChromaDB."""
+
+from pathlib import Path
+
+from . import config
+from .chunking import collect_markdown
+
+
+def build_index(
+    source_dir: Path | None = None,
+    chroma_dir: Path | None = None,
+    model_name: str | None = None,
+    force: bool = False,
+    offline: bool = True,
+) -> dict:
+    """Build (or rebuild) the vector index from the markdown corpus.
+
+    Returns a summary dict: {files, chunks, collection, chroma_dir}.
+    """
+    from sentence_transformers import SentenceTransformer
+    import chromadb
+
+    source = source_dir or config.source_dir()
+    chroma = chroma_dir or config.chroma_dir()
+    model_name = model_name or config.MODEL_NAME
+
+    if not source.is_dir():
+        raise FileNotFoundError(f"corpus directory not found: {source}")
+
+    print(f"[*] Loading model: {model_name}")
+    model = SentenceTransformer(
+        model_name,
+        local_files_only=offline,
+    )
+    model.max_seq_length = 512
+    print(f"    Embedding dim: {model.get_sentence_embedding_dimension()}")
+
+    print(f"[*] Reading corpus: {source}")
+    documents = collect_markdown(source)
+    if not documents:
+        raise RuntimeError("no markdown documents found in corpus")
+    print(f"    {len(documents)} chunks")
+
+    chroma.mkdir(parents=True, exist_ok=True)
+    client = chromadb.PersistentClient(path=str(chroma))
+
+    if force:
+        try:
+            client.delete_collection(config.COLLECTION_NAME)
+        except Exception:
+            pass
+
+    collection = client.get_or_create_collection(
+        name=config.COLLECTION_NAME,
+        metadata={
+            "description": "UE Game Development Knowledge Base",
+            "hnsw:space": "cosine",
+        },
+    )
+    if collection.count() > 0 and not force:
+        raise RuntimeError(
+            f"collection already has {collection.count()} docs; use --force to rebuild"
+        )
+
+    texts = [d["text"] for d in documents]
+    ids = [d["id"] for d in documents]
+    metadatas = [{"source": d["source"], "heading": d["heading"]} for d in documents]
+
+    print(f"[*] Embedding {len(texts)} chunks...")
+    batch_size = 64
+    for i in range(0, len(texts), batch_size):
+        batch_texts = texts[i:i + batch_size]
+        embeddings = model.encode(
+            batch_texts, show_progress_bar=False, normalize_embeddings=True
+        )
+        collection.add(
+            ids=ids[i:i + batch_size],
+            embeddings=embeddings.tolist(),
+            documents=batch_texts,
+            metadatas=metadatas[i:i + batch_size],
+        )
+        print(f"    [{min(i + batch_size, len(texts)):4d}/{len(texts)}]")
+
+    print(f"[✓] Index ready: {chroma} ({collection.count()} docs)")
+    return {
+        "files": len(list(source.rglob("*.md"))),
+        "chunks": len(documents),
+        "collection": config.COLLECTION_NAME,
+        "chroma_dir": str(chroma),
+    }

ue_knowledge_base-0.1.0/src/ue_knowledge/chunking.py

@@ -0,0 +1,62 @@
+"""Markdown chunking — split docs on heading boundaries into semantic chunks."""
+
+import hashlib
+
+
+def chunk_markdown(text: str, source: str, min_chars: int = 100, max_chars: int = 800) -> list[dict]:
+    """Split markdown into chunks by heading boundaries.
+
+    Returns a list of dicts: {id, text, source, heading}.
+    """
+    chunks = []
+    lines = text.split("\n")
+    buffer = []
+    buffer_heading = "前言"
+
+    def flush():
+        nonlocal buffer, buffer_heading
+        chunk_text = "\n".join(buffer).strip()
+        if len(chunk_text) >= min_chars:
+            chunks.append({
+                "text": chunk_text,
+                "source": source,
+                "heading": buffer_heading,
+                "id": hashlib.md5(
+                    f"{source}:{buffer_heading}:{chunk_text[:50]}".encode()
+                ).hexdigest() + f":{len(chunks)}",
+            })
+
+    for line in lines:
+        if line.startswith(("## ", "### ", "# ")):
+            flush()
+            buffer_heading = line.lstrip("#").strip()
+            buffer = [line]
+        else:
+            buffer.append(line)
+
+    flush()
+
+    # Merge tiny chunks into their predecessor so the index stays useful.
+    merged = []
+    for c in chunks:
+        if merged and len(c["text"]) < 200:
+            merged[-1]["text"] += "\n\n" + c["text"]
+            merged[-1]["heading"] += " / " + c["heading"]
+        else:
+            merged.append(c)
+
+    return merged
+
+
+def collect_markdown(source_dir, min_chars: int = 100) -> list[dict]:
+    """Recursively read all .md files under source_dir into chunks."""
+    documents = []
+    files = sorted(source_dir.rglob("*.md"))
+    for fp in files:
+        try:
+            text = fp.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        rel = fp.relative_to(source_dir)
+        documents.extend(chunk_markdown(text, source=str(rel), min_chars=min_chars))
+    return documents

ue_knowledge_base-0.1.0/src/ue_knowledge/cli.py

@@ -0,0 +1,131 @@
+"""ue-kb command-line interface: build / query / info / download-model."""
+
+import argparse
+import json
+import sys
+
+from . import __version__, config
+from .build import build_index
+from .query import format_results, query
+
+
+def _model_unavailable_hint(exc: Exception) -> str:
+    return (
+        "Model 未找到或无法加载。首次使用请先运行:\n"
+        "    ue-kb download-model\n"
+        "（中国大陆网络受限时: 设置 HF_ENDPOINT=https://hf-mirror.com 再执行）\n"
+        f"原始错误: {exc}"
+    )
+
+
+def cmd_build(args: argparse.Namespace) -> int:
+    try:
+        summary = build_index(
+            source_dir=config.source_dir(args.source),
+            chroma_dir=config.chroma_dir(args.db),
+            model_name=args.model,
+            force=args.force,
+            offline=not args.online,
+        )
+    except FileNotFoundError as e:
+        print(f"[!] {e}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"[!] {_model_unavailable_hint(e)}", file=sys.stderr)
+        return 1
+    print(json.dumps(summary, ensure_ascii=False))
+    return 0
+
+
+def cmd_query(args: argparse.Namespace) -> int:
+    try:
+        results = query(
+            args.query,
+            top_k=args.top_k,
+            chroma_dir=config.chroma_dir(args.db),
+            model_name=args.model,
+            offline=not args.online,
+        )
+    except Exception as e:
+        print(f"[!] {_model_unavailable_hint(e)}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps(results, ensure_ascii=False, indent=2))
+    else:
+        print(format_results(results, args.query))
+    return 0
+
+
+def cmd_info(args: argparse.Namespace) -> int:
+    import chromadb
+
+    chroma = config.chroma_dir(args.db)
+    try:
+        client = chromadb.PersistentClient(path=str(chroma))
+        collection = client.get_collection(config.COLLECTION_NAME)
+    except Exception as e:
+        print(f"[!] 索引不存在: {chroma}（先运行 ue-kb build）\n{e}", file=sys.stderr)
+        return 1
+    meta = collection.metadata or {}
+    print(f"collection : {collection.name}")
+    print(f"documents  : {collection.count()}")
+    print(f"description: {meta.get('description', '')}")
+    print(f"chroma_dir : {chroma}")
+    return 0
+
+
+def cmd_download_model(args: argparse.Namespace) -> int:
+    from sentence_transformers import SentenceTransformer
+
+    model_name = args.model or config.MODEL_NAME
+    print(f"[*] 下载模型: {model_name}（首次约 100MB，之后完全离线）")
+    print("    网络受限时请设置: HF_ENDPOINT=https://hf-mirror.com")
+    try:
+        SentenceTransformer(model_name)  # online download
+    except Exception as e:
+        print(f"[!] 下载失败: {e}", file=sys.stderr)
+        return 1
+    print("[✓] 模型已缓存。现在可以运行: ue-kb build && ue-kb query")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="ue-kb",
+        description="UE Knowledge Base — offline semantic search over Unreal Engine dev docs",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_build = sub.add_parser("build", help="build the vector index from knowledge/")
+    p_build.add_argument("--source", help="corpus dir (default: repo knowledge/)")
+    p_build.add_argument("--db", help="chroma dir (default: repo .chroma_db/)")
+    p_build.add_argument("--model", default=config.MODEL_NAME, help="embedding model")
+    p_build.add_argument("--force", action="store_true", help="rebuild even if index exists")
+    p_build.add_argument("--online", action="store_true", help="allow model download if missing")
+    p_build.set_defaults(func=cmd_build)
+
+    p_query = sub.add_parser("query", help="semantic search")
+    p_query.add_argument("query", help="search text (e.g. \"GAS cooldown\")")
+    p_query.add_argument("--top-k", type=int, default=5)
+    p_query.add_argument("--db", help="chroma dir")
+    p_query.add_argument("--model", default=config.MODEL_NAME, help="embedding model")
+    p_query.add_argument("--online", action="store_true", help="allow model download if missing")
+    p_query.add_argument("--json", action="store_true", help="raw JSON output")
+    p_query.set_defaults(func=cmd_query)
+
+    p_info = sub.add_parser("info", help="show index stats")
+    p_info.add_argument("--db", help="chroma dir")
+    p_info.set_defaults(func=cmd_info)
+
+    p_dl = sub.add_parser("download-model", help="download the embedding model once")
+    p_dl.add_argument("--model", default=config.MODEL_NAME)
+    p_dl.set_defaults(func=cmd_download_model)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ue_knowledge_base-0.1.0/src/ue_knowledge/config.py

@@ -0,0 +1,33 @@
+"""Shared configuration: default paths and the embedding model name."""
+
+import os
+from pathlib import Path
+
+# Default model — small, multilingual (Chinese-friendly), runs on CPU.
+MODEL_NAME = "BAAI/bge-small-zh-v1.5"
+
+# Repo root (…/ue-knowledge-base)
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+# Default corpus + vector store locations inside the repo.
+DEFAULT_SOURCE_DIR = REPO_ROOT / "knowledge"
+DEFAULT_CHROMA_DIR = REPO_ROOT / ".chroma_db"
+
+# ChromaDB collection name.
+COLLECTION_NAME = "ue_knowledge"
+
+
+def source_dir(override: str | None = None) -> Path:
+    """Resolve the markdown corpus directory (CLI flag > env > default)."""
+    if override:
+        return Path(override)
+    env = os.environ.get("UE_KB_SOURCE")
+    return Path(env) if env else DEFAULT_SOURCE_DIR
+
+
+def chroma_dir(override: str | None = None) -> Path:
+    """Resolve the ChromaDB store directory (CLI flag > env > default)."""
+    if override:
+        return Path(override)
+    env = os.environ.get("UE_KB_CHROMA_DIR")
+    return Path(env) if env else DEFAULT_CHROMA_DIR

ue_knowledge_base-0.1.0/src/ue_knowledge/query.py

@@ -0,0 +1,60 @@
+"""Semantic querying against the built index."""
+
+from pathlib import Path
+
+from . import config
+
+
+def query(
+    query_text: str,
+    top_k: int = 5,
+    chroma_dir: Path | None = None,
+    model_name: str | None = None,
+    offline: bool = True,
+) -> list[dict]:
+    """Search the knowledge base. Returns [{source, heading, score, text}]."""
+    from sentence_transformers import SentenceTransformer
+    import chromadb
+
+    chroma = chroma_dir or config.chroma_dir()
+    model_name = model_name or config.MODEL_NAME
+
+    model = SentenceTransformer(model_name, local_files_only=offline)
+    client = chromadb.PersistentClient(path=str(chroma))
+    collection = client.get_collection(config.COLLECTION_NAME)
+
+    query_embedding = model.encode(
+        [query_text], normalize_embeddings=True
+    )[0]
+
+    results = collection.query(
+        query_embeddings=[query_embedding.tolist()],
+        n_results=top_k,
+        include=["documents", "metadatas", "distances"],
+    )
+
+    out = []
+    docs = results["documents"] or [[]]
+    metas = results["metadatas"] or [[]]
+    dists = results["distances"] or [[]]
+    for doc, meta, dist in zip(docs[0], metas[0], dists[0]):
+        out.append({
+            "source": meta.get("source", "?"),
+            "heading": meta.get("heading", "?"),
+            "score": round(1.0 - dist, 4),
+            "text": doc,
+        })
+    return out
+
+
+def format_results(results: list[dict], query_text: str) -> str:
+    """Human-readable rendering of query results."""
+    if not results:
+        return "没有找到相关结果。"
+    lines = [f"🔍 UE 知识库检索：{query_text}", ""]
+    for i, r in enumerate(results, 1):
+        score = f"{r['score']:.1%}"
+        lines.append(f"[{i}] {r['source']} › {r['heading']} (匹配度: {score})")
+        lines.append(f"    {r['text'][:200].replace(chr(10), ' ')}...")
+        lines.append("")
+    return "\n".join(lines)

ue_knowledge_base-0.1.0/src/ue_knowledge_base.egg-info/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: ue-knowledge-base
+Version: 0.1.0
+Summary: Offline semantic search over Unreal Engine development knowledge (BGE + ChromaDB)
+Author: Dong
+License: MIT
+Keywords: unreal-engine,rag,semantic-search,chromadb,knowledge-base
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sentence-transformers>=2.6
+Requires-Dist: chromadb>=0.5
+Dynamic: license-file
+
+# UE Knowledge Base
+
+Offline semantic search over Unreal Engine development knowledge — a curated
+**Chinese-language knowledge corpus** (29 topics: GAS, animation, AI,
+networking, UMG, Niagara, PCG, ...) plus a local RAG pipeline that indexes it
+with `BAAI/bge-small-zh-v1.5` embeddings into ChromaDB.
+
+**Zero API cost. Fully offline after a one-time model download.** Built for
+Chinese-speaking UE developers, and ready to plug into any AI agent, IDE, or
+CLI workflow.
+
+```
+knowledge/  (29 topics, ~84 markdown docs)
+    │  ue-kb build          chunk + embed (BGE small, local)
+    ▼
+.chroma_db/  (vector index)
+    │  ue-kb query "GAS cooldown"
+    ▼
+top-k semantic hits with source + heading
+```
+
+## Features
+
+- 📚 **Curated corpus**: hand-written UE development docs in Chinese, covering
+  Gameplay Ability System, character movement, animation, physics/collision,
+  AI navigation, networking/replication, UMG/Slate, Niagara, Mass Entity,
+  State Trees, PCG/procedural generation, materials/rendering, module build
+  system, editor tools, and more.
+- 🧠 **Local semantic search**: `BAAI/bge-small-zh-v1.5` (multilingual, ~100MB)
+  + ChromaDB — no cloud APIs, no cost, works on a laptop CPU.
+- 🖥️ **Simple CLI** (`ue-kb`): `build`, `query`, `info`, `download-model`,
+  plus `--json` output for agent integration.
+- 🔌 **Extensible**: index any extra UE docs with `--source`, or add engine
+  source-indexing scripts under `scripts/`.
+
+## Quick start
+
+```bash
+# 1. Install
+pip install -e .                 # or: pip install ue-knowledge-base
+
+# 2. Download the embedding model once (~100MB)
+ue-kb download-model
+#    In China:  export HF_ENDPOINT=https://hf-mirror.com  then retry
+
+# 3. Build the index
+ue-kb build
+
+# 4. Search
+ue-kb query "GAS ability cooldown" --top-k 5
+ue-kb query "角色移动 速度衰减" --json   # machine-readable for agents
+```
+
+### Example
+
+```text
+$ ue-kb query "GAS 技能冷却"
+🔍 UE 知识库检索：GAS 技能冷却
+
+[1] ue-gameplay-abilities/references/gas-input-integration.md › 问题 (匹配度: 21.1%)
+    UE 项目同时使用 GAS (GameplayAbilitySystem) 和 Enhanced Input 时，容易陷入
+    两个极端：- **全 GAS** → 所有输入走 GAS，但 WASD 轴输入不适合 GAS 的事件
+    模型，且 CommitAbility 的 GC 延迟影响跳跃手感 ...
+[2] ue-gameplay-abilities/references/gas-input-integration.md › Jump — GAS 即时技能 (匹配度: 14.2%)
+    ...
+```
+
+## Python API
+
+```python
+from ue_knowledge.query import query
+
+for hit in query("GAS cooldown", top_k=5):
+    print(hit["source"], hit["heading"], hit["score"])
+```
+
+## Extending the corpus
+
+1. Add a markdown file under `knowledge/<topic>/` (use `##`/`###` headings —
+   the indexer chunks on heading boundaries).
+2. `ue-kb build --force` to rebuild.
+
+For indexing **Unreal Engine C++ header comments** or **Epic official docs**,
+see `scripts/index_engine_source.py` and `scripts/crawl_epic_docs.py`
+(they expect local engine/UE paths — the extracted index data is generated
+locally and is not redistributed, out of respect for Epic's copyright).
+
+## License
+
+MIT. The knowledge documents are original writing; no engine source code or
+verbatim Epic documentation is included.

ue_knowledge_base-0.1.0/src/ue_knowledge_base.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/ue_knowledge/__init__.py
+src/ue_knowledge/build.py
+src/ue_knowledge/chunking.py
+src/ue_knowledge/cli.py
+src/ue_knowledge/config.py
+src/ue_knowledge/query.py
+src/ue_knowledge_base.egg-info/PKG-INFO
+src/ue_knowledge_base.egg-info/SOURCES.txt
+src/ue_knowledge_base.egg-info/dependency_links.txt
+src/ue_knowledge_base.egg-info/entry_points.txt
+src/ue_knowledge_base.egg-info/requires.txt
+src/ue_knowledge_base.egg-info/top_level.txt
+tests/test_chunking.py
+tests/test_cli.py

ue_knowledge_base-0.1.0/src/ue_knowledge_base.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ue_knowledge_base-0.1.0/src/ue_knowledge_base.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ue-kb = ue_knowledge.cli:main

ue_knowledge_base-0.1.0/src/ue_knowledge_base.egg-info/requires.txt

@@ -0,0 +1,2 @@
+sentence-transformers>=2.6
+chromadb>=0.5

ue_knowledge_base-0.1.0/src/ue_knowledge_base.egg-info/top_level.txt

@@ -0,0 +1 @@
+ue_knowledge

ue_knowledge_base-0.1.0/tests/test_chunking.py

@@ -0,0 +1,31 @@
+"""Unit tests for the markdown chunker (no external deps, runs anywhere)."""
+
+from ue_knowledge.chunking import chunk_markdown
+
+LONG = "word " * 60  # 300 chars — well above the 200-char merge threshold
+
+
+def test_chunks_by_heading():
+    doc = f"# Title\n\n{LONG}\n\n## Section A\n\n{LONG}\n\n### Sub\n\n{LONG}"
+    chunks = chunk_markdown(doc, source="test.md", min_chars=10)
+    assert len(chunks) == 3
+    headings = [c["heading"] for c in chunks]
+    assert headings[0] == "Title"
+    assert headings[1] == "Section A"
+    assert headings[2] == "Sub"
+    assert chunks[0]["source"] == "test.md"
+
+
+def test_tiny_chunks_merged():
+    doc = f"# Big\n\n{LONG}\n\n## Tiny\n\nshort\n\n## Big2\n\n{LONG}"
+    chunks = chunk_markdown(doc, source="t.md", min_chars=100)
+    # "short" is below min_chars → dropped; only Big and Big2 become chunks
+    assert len(chunks) == 2
+    assert "Tiny" not in [c["heading"] for c in chunks]
+
+
+def test_ids_unique():
+    doc = f"# A\n\n{LONG}\n\n## B\n\n{LONG}"
+    chunks = chunk_markdown(doc, source="u.md", min_chars=50)
+    ids = [c["id"] for c in chunks]
+    assert len(ids) == len(set(ids))

ue_knowledge_base-0.1.0/tests/test_cli.py

@@ -0,0 +1,19 @@
+"""CLI smoke tests — argparse wiring only (no model/index required)."""
+
+from ue_knowledge.cli import main
+
+
+def test_version(capsys):
+    try:
+        main(["--version"])
+    except SystemExit as e:
+        assert e.code == 0
+    out = capsys.readouterr().out
+    assert "ue-kb" in out
+
+
+def test_build_missing_source_errors(capsys):
+    rc = main(["build", "--source", "C:/definitely/not/here"])
+    assert rc == 1
+    err = capsys.readouterr().err
+    assert "not found" in err