source-kb 0.2.12

Auto-generate structured knowledge base documents from source code. Supports AI agent mode (skill-based) and standalone CLI.

source-kb

English | 中文

Auto-generate structured knowledge base documents from source code, build vector indexes, and support RAG retrieval.

Features

• CLI toolchain: skeleton extraction, prompt rendering, intelligent splitting, quality validation, vector indexing — all standalone Python scripts
• Platform-agnostic: works in Kiro / Cursor / Claude Code / Windsurf / any AI Agent
• LLM-agnostic: without an Agent, use engine with any OpenAI-compatible API (Anthropic / OpenAI / DeepSeek / Ollama / vLLM, etc.)
• Intelligent subagent splitting: semantic grouping by business domain (LLM-based) or package-aware greedy algorithm (code-based)
• Two-phase generation: outline first, then expand — eliminates information isolation between shards
• Method-level source injection: prioritized by complexity (high=full body / medium=first 20 lines / low=signature only)
• Real-time quality validation: each subagent output is verified immediately, with automatic retry on failure
• Document deduplication: LLM-powered post-merge dedup (internal redundancy + cross-doc ownership)
• Module doc distillation: summarize multiple microservice docs into domain-level documentation
• Any language support via preset system (java-spring built-in)
• Source code access through git remote (multi-repo & monorepo)
• Lightweight self-built RAG engine (ChromaDB + pluggable embedding)
• Auto-publish docs to source repo knowledge branch

Quick Start

Option 1: Skill Mode (recommended)

Install the CLI toolchain:

pip install source-kb[full]

# If you have multiple Python versions, specify the target version:
python -3.12 -m pip install source-kb[full]

Install skills to your Agent's directory:

# Run from your project root (presets/ and examples/ are copied to current directory)
cd my-project/
source-kb install-skills --agent kiro     # Kiro
source-kb install-skills --agent cursor   # Cursor
source-kb install-skills --agent claude   # Claude Code

Note: install-skills copies presets/ and examples/ to the current working directory. Make sure to run it from your project root. To copy assets to a different project later:

source-kb install-skills --assets-only   # Copy presets/ + examples/ to current directory

Then talk to your AI Agent (Kiro / Claude Code / Cursor / Windsurf):

Please read skills/kb-init/SKILL.md and follow the steps to initialize the knowledge base.

Or add the guide to your project rules file (.kiro/steering/, .cursorrules, .claude/CLAUDE.md, etc.). See Getting Started.

Non-Java project? Works the same way. Configure kb-project.yaml with the generic preset:

# Use generic preset (works for any language)
source-kb extract --repo .source-cache/my-app --preset generic --output knowledge/my-app

The generic preset uses path-based rules + regex parser for file classification — no tree-sitter required. For higher accuracy, create a custom preset following presets/java-spring/ as reference.

Option 2: CLI Mode (no Agent, requires LLM API config)

pip install source-kb[full]

export LLM_BASE_URL="https://api.anthropic.com"
export LLM_MODEL="claude-sonnet-4-6"
export LLM_API_KEY="sk-xxx"
source-kb extract --repo .source-cache/my-app --preset java-spring --summary --output knowledge/my-app
source-kb index --kb my-app

Full guide: Getting Started.

CLI Quick Reference

# Skeleton extraction
source-kb extract --repo .source-cache/xxx --preset java-spring --summary --output knowledge/xxx

# Prompt rendering
source-kb render --template presets/java-spring/templates/subagent-business.md --module xxx --kb yyy --doc-type business-logic --mode readwrite

# File list extraction
source-kb file-list --skeleton knowledge/xxx/.meta/skeleton/skeleton.json --preset java-spring --doc-type business-logic --output knowledge/xxx/.meta/file-lists/business-logic.txt

# Coverage validation
source-kb validate coverage check --skeleton knowledge/xxx/.meta/skeleton/skeleton.json --docs-dir knowledge/xxx --type service

# Index & search
source-kb index --kb my-project
source-kb search --kb my-project "query"

Skills

Skill	Purpose
kb-init	Generate all docs from source + build index
kb-audit	Compare docs vs source, fix inconsistencies
kb-sync	Detect git changes, incrementally update docs and index
kb-search	Vector retrieval + contextual answers

Skill files are Agent operation guides — no platform-specific instructions.

Requirements

• Python 3.10~3.12 (⚠️ 3.13 not supported — tree-sitter-languages has no prebuilt wheel)
• Git
• Embedding backend (Ollama / OpenAI-compatible / DashScope / ChromaDB built-in)

Installation

# Basic install (CLI toolchain)
pip install source-kb

# Full install (skeleton parsing + vector index)
pip install source-kb[full]

# Skeleton parsing only (tree-sitter)
pip install source-kb[skeleton]

# Vector index only (ChromaDB)
pip install source-kb[rag]

Verify installation:

source-kb --version
source-kb --help

Documentation

• Getting Started — Installation, configuration, first run
• Configuration Reference — Full kb-project.yaml field reference
• Custom Presets — Create and customize language presets
• Design Document — Architecture design and technical decisions
• CLI vs Agent Mode — Two modes compared