ai-wiki 0.1.0__tar.gz

ai_wiki-0.1.0/LICENSE

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

ai_wiki-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: ai-wiki
+Version: 0.1.0
+Summary: Structured knowledge wiki CLI for AI agents
+Project-URL: Homepage, https://github.com/j-dev-team/ai-wiki
+Project-URL: Repository, https://github.com/j-dev-team/ai-wiki
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: flask>=3.0
+Requires-Dist: sqlite-vec>=0.1.6
+Requires-Dist: sentence-transformers>=3.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file

ai_wiki-0.1.0/README.md

@@ -0,0 +1,494 @@
+# AI Wiki — Structured Knowledge Encyclopedia
+
+A CLI-based knowledge wiki system that stores, searches, and manages knowledge learned by AI assistants as **structured YAML** data.
+
+[한국어 README](README.ko.md)
+
+---
+
+## Features
+
+- **Structured YAML Storage** — Accumulate knowledge as key-value structured data, not markdown prose
+- **FTS5 Full-Text Search** — SQLite FTS5-based keyword search for Korean and English
+- **Vector Semantic Search** — `sentence-transformers` + `sqlite-vec` embedding search
+- **Hybrid Search (RRF Fusion)** — Combines FTS5 + vector search via RRF (Reciprocal Rank Fusion): `score = Σ 1/(k+rank_i)`
+- **Quality Gates** — 5-level automatic evaluation of confidence, sources, and verification
+- **Auto Cross-Reference** — Automatic detection and bidirectional linking of related documents
+- **Git Auto-Commit** — Automatic Git history recording on every document change
+- **AI Agent Skill Integration** — Auto-generates skill files for Claude Code (`~/.claude/skills/`), Gemini CLI (`~/.gemini/skills/`), and GPT Codex (`~/.codex/skills/`)
+- **Wiki Name Customization** — Name entered during init is displayed in the web UI header
+- **Token Optimization** — Efficient operation with large document sets via DB metadata queries
+
+---
+
+## Installation
+
+### User Installation (pip)
+
+```bash
+pip install ai-wiki
+ai-wiki init ~/my-wiki
+```
+
+### Developer Installation (source)
+
+```bash
+git clone https://github.com/j-dev-team/ai-wiki.git
+cd ai-wiki
+python -m venv .venv
+source .venv/bin/activate   # Linux/macOS
+# .venv\Scripts\activate    # Windows
+pip install -e ".[test]"
+```
+
+> **Windows Note**: Use `python` instead of `python3`.
+
+### Interactive Init Flow
+
+`ai-wiki init` runs interactively:
+
+1. **Language Selection** — `English` / `한국어`
+2. **Wiki Name** — Displayed in the web UI header (saved in `.ai-wiki.yaml`)
+3. **Agent Selection** — Choose which AI agents you use (default: Claude Code)
+4. **Preset Selection** — Category structure matching your wiki's purpose
+
+**Agent Selection UI:**
+
+```
+Which AI agents do you use? (comma-separated numbers)
+  1. Claude Code
+  2. Gemini CLI
+  3. GPT Codex
+Select [1,2,3] (default: 1):
+```
+
+- Default: `1` (Claude Code only)
+- Multiple: `1,2` → Claude Code + Gemini CLI
+- All: `1,2,3`
+- Skills are installed only to the selected agent paths (saved in `.ai-wiki.yaml`)
+
+| Preset | Description |
+|--------|-------------|
+| `general` | General knowledge (default) |
+| `tech` | Technology & development focused |
+| `business` | Business & management focused |
+| `research` | Research & academic focused |
+
+---
+
+## Quick Start
+
+```bash
+# Search documents (hybrid: FTS5 + vector auto-combined)
+ai-wiki search "python"
+
+# List documents (recent first, default 50)
+ai-wiki list
+
+# Filter by category + sort by title
+ai-wiki list --category technology/python --sort title
+
+# Pagination
+ai-wiki list --limit 20 --offset 40
+
+# Get a document
+ai-wiki get <document-id>
+
+# Create a document
+ai-wiki create \
+  --title "Python Basics" \
+  --category "technology/programming" \
+  --tags "python,programming" \
+  --confidence 0.9 \
+  --source "https://docs.python.org" \
+  --content-stdin << EOF
+type: knowledge
+what: Python is a general-purpose interpreted programming language
+creator: Guido van Rossum
+release_year: 1991
+paradigm:
+  - object-oriented
+  - functional
+  - procedural
+use_cases:
+  - web development
+  - data science
+  - automation
+  - AI/ML
+EOF
+```
+
+---
+
+## Web UI
+
+```bash
+# Start web UI
+ai-wiki-web
+
+# Default port: 5000 → http://localhost:5000
+# Wiki name is read from the `name` field in .ai-wiki.yaml
+```
+
+> **Warning**: The web UI has no authentication or authorization. Use it only on localhost and do not expose it to external networks.
+
+---
+
+## CLI Command Reference
+
+### Basic CRUD
+
+| Command | Description |
+|---------|-------------|
+| `ai-wiki init [path]` | Initialize a new wiki (directory structure + config) |
+| `ai-wiki create` | Create a new document |
+| `ai-wiki get <ID>` | Get a document by ID |
+| `ai-wiki update <ID>` | Update an existing document |
+| `ai-wiki delete <ID> --confirm` | Delete a document |
+| `ai-wiki list` | List all documents (`--sort`, `--category`, `--limit`, `--offset`) |
+| `ai-wiki destroy [path]` | Destroy a wiki (remove skill files, env vars, directory) |
+| `ai-wiki upgrade-skill` | Upgrade skill files to the latest version |
+
+### Search
+
+| Command | Description |
+|---------|-------------|
+| `ai-wiki search "query"` | Hybrid search (FTS5 + vector, auto-combined via RRF) |
+| `ai-wiki vsearch "query"` | Semantic vector search |
+| `ai-wiki similar <ID>` | Find documents similar to a given document |
+| `ai-wiki tag <tag>` | List documents with a specific tag |
+| `ai-wiki tags` | List all tags and document counts |
+
+### Quality Management
+
+| Command | Description |
+|---------|-------------|
+| `ai-wiki quality <ID>` | Single document quality report |
+| `ai-wiki quality-all` | Batch quality check for all documents |
+| `ai-wiki verify <ID>` | Update document verification date |
+| `ai-wiki verify <ID> --human` | Mark as human-verified |
+| `ai-wiki verify-queue` | List documents needing verification |
+| `ai-wiki review <ID>` | Generate verification checklist |
+
+### Wiki Maintenance
+
+| Command | Description |
+|---------|-------------|
+| `ai-wiki reindex` | Rebuild search index |
+| `ai-wiki vindex` | Rebuild vector index |
+| `ai-wiki lint` | Wiki health check |
+| `ai-wiki lint --fix` | Health check + auto-fix |
+| `ai-wiki maintain` | Run lint + quality + todo together |
+| `ai-wiki backlinks <ID>` | List documents referencing this document |
+| `ai-wiki sync-backlinks` | Bulk sync all bidirectional backlinks |
+
+### Analysis & Exploration
+
+| Command | Description |
+|---------|-------------|
+| `ai-wiki stats` | Access statistics (Top N views/searches) |
+| `ai-wiki gaps` | Gap analysis by category |
+| `ai-wiki todo` | Auto-collected task list for the wiki |
+| `ai-wiki stale` | List outdated documents (default: 90 days) |
+| `ai-wiki discover` | Find isolated, low-quality, or stale documents |
+| `ai-wiki path <ID1> <ID2>` | Shortest path between two documents (BFS) |
+| `ai-wiki cluster` | Document topic clustering |
+| `ai-wiki history <ID>` | Git change history for a document |
+
+### Export / Import
+
+| Command | Description |
+|---------|-------------|
+| `ai-wiki export <ID>` | Export as Markdown or YAML |
+| `ai-wiki export-all` | Batch export all documents |
+| `ai-wiki ingest <file>` | Ingest a source file (auto-creates stub document) |
+
+---
+
+## Hybrid Search
+
+`ai-wiki search` **automatically combines** FTS5 keyword search and vector semantic search.
+
+- **RRF (Reciprocal Rank Fusion)** algorithm merges both result sets
+- Returns a unified `hybrid_score` field
+- Falls back to FTS5-only mode if vector search is not installed
+
+```bash
+# Hybrid search (default)
+ai-wiki search "machine learning python"
+
+# Pure vector search only
+ai-wiki vsearch "machine learning python"
+```
+
+---
+
+## Document Structure (YAML Schema)
+
+```yaml
+id: tech-python-abc123
+title: Python Basics
+category: technology/programming
+tags:
+  - python
+  - programming
+confidence: 0.9
+version: 1
+created_at: 2026-01-01T00:00:00Z
+last_modified: 2026-01-01T00:00:00Z
+last_verified: 2026-01-01T00:00:00Z
+sources:
+  - https://docs.python.org
+related:
+  - tech-django-xyz789
+author: claude
+content:
+  type: knowledge
+  what: Python is a general-purpose interpreted programming language
+  creator: Guido van Rossum
+  release_year:
+    value: 1991
+    _v:
+      level: verified       # unverified | sourced | verified | corroborated | human_verified | disputed
+      source: https://docs.python.org
+  use_cases:
+    - web development
+    - data science
+  _meta:
+    maturity: mature        # stub | draft | review | mature
+    completeness: 0.85
+  _changelog:
+    - date: 2026-01-01T00:00:00Z
+      action: created
+      fields: [what, creator]
+      note: Document created
+```
+
+### File Storage Path
+
+```
+articles/<category>/<subcategory>/<slug>.yaml
+```
+
+Example: `articles/technology/programming/python-abc123.yaml`
+
+---
+
+## Quality System
+
+### Verification Levels (`_v`)
+
+Track reliability by attaching `_v` metadata to factual data such as numbers, dates, and quotes.
+
+| Level | Weight | Description |
+|-------|--------|-------------|
+| `unverified` | 0.0 | Not verified |
+| `sourced` | 0.3 | Has a source |
+| `verified` | 0.8 | Verified |
+| `corroborated` | 0.8 | Cross-verified |
+| `disputed` | 0.2 | Disputed |
+| `human_verified` | 1.0 | Verified by a human |
+
+### Maturity Stages
+
+| Stage | Description |
+|-------|-------------|
+| `stub` | Minimal info, needs enrichment |
+| `draft` | Basic info present |
+| `review` | Under review |
+| `mature` | Complete document |
+
+### Quality Score Calculation
+
+```
+score = structure keys (15%) + word count (20%) + sources (10%) +
+        tags (5%) + related docs (10%) + confidence (10%) + verification rate (30%)
+```
+
+---
+
+## Directory Structure
+
+```
+ai_wiki/
++-- articles/           # Document YAML files (subdirectories by category)
++-- data/
+|   +-- wiki.db         # SQLite main index (FTS5)
+|   +-- vectors.db      # Vector embedding index
++-- sources/            # Ingested source files
++-- logs/               # Operation logs
++-- tmp/                # Temporary files
++-- src/ai_wiki/        # Package source
+|   +-- cli.py          # CLI entry point
+|   +-- models.py       # Article data model
+|   +-- storage.py      # File/DB storage layer
+|   +-- index.py        # SQLite search index
+|   +-- vector.py       # Vector search engine
+|   +-- quality.py      # Quality validation engine
+|   +-- schemas.py      # Type-specific schemas
+|   +-- catalog.py      # Catalog builder
+|   +-- wikilog.py      # Operation logger
+|   +-- web.py          # Web UI (Flask)
++-- tests/              # Tests
++-- .ai-wiki.yaml       # Wiki configuration
++-- pyproject.toml
+```
+
+---
+
+## Wiki Operations
+
+### Single Wiki (Default)
+
+Install one wiki and all AI agent projects on the system can automatically access it.
+
+```bash
+ai-wiki init ~/my-wiki
+```
+
+Skill files are auto-generated on init. Any agent in any project will automatically search, query, and create documents in the wiki when it receives knowledge-related questions.
+
+```
+~/.claude/skills/my-wiki/   <- Claude Code
+~/.gemini/skills/my-wiki/   <- Gemini CLI
+~/.codex/skills/my-wiki/    <- GPT Codex
+
+Project A --+
+Project B --+-- Share a single wiki
+Project C --+
+```
+
+### Multi Wiki
+
+Run multiple independent wikis on a single system.
+
+#### Creating Wiki Instances
+
+```bash
+# Work wiki
+ai-wiki init ~/work-wiki
+# -> Wiki name: "Work Wiki"
+# -> Preset: business
+
+# Personal knowledge wiki
+ai-wiki init ~/knowledge-wiki
+# -> Wiki name: "My Knowledge"
+# -> Preset: general
+```
+
+#### Switching Wikis
+
+Switch the target wiki using the `AI_WIKI_ROOT` environment variable.
+
+```bash
+# Search work wiki
+AI_WIKI_ROOT=~/work-wiki ai-wiki search "client"
+
+# Search personal wiki
+AI_WIKI_ROOT=~/knowledge-wiki ai-wiki search "python"
+```
+
+#### Agent Skill Integration
+
+`ai-wiki init` auto-generates skill files for each selected agent. All agent projects can access all wiki skills, enabling multiple projects to share multiple wikis.
+
+```
+~/.claude/skills/
+  +-- work-wiki/SKILL.md        (AI_WIKI_ROOT=~/work-wiki)
+  +-- knowledge-wiki/SKILL.md   (AI_WIKI_ROOT=~/knowledge-wiki)
+
+~/.gemini/skills/
+  +-- work-wiki/SKILL.md        (AI_WIKI_ROOT=~/work-wiki)
+  +-- knowledge-wiki/SKILL.md   (AI_WIKI_ROOT=~/knowledge-wiki)
+
+~/.codex/skills/
+  +-- work-wiki/SKILL.md        (AI_WIKI_ROOT=~/work-wiki)
+  +-- knowledge-wiki/SKILL.md   (AI_WIKI_ROOT=~/knowledge-wiki)
+
+Project A --+
+Project B --+-- Access both wiki skills
+Project C --+
+```
+
+- **Data**: Fully isolated per wiki (separate articles/, data/)
+- **Program**: Single shared ai-wiki CLI
+- **Skills**: Independent skill files per wiki, accessible from all projects
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AI_WIKI_ROOT` | Wiki root directory path (required) |
+
+Automatically registered during `ai-wiki init`.
+
+```bash
+# Manual setup (Windows)
+setx AI_WIKI_ROOT "D:/dev/ai_wiki"
+
+# Manual setup (Linux/macOS)
+export AI_WIKI_ROOT="/home/user/ai_wiki"
+```
+
+---
+
+## Development / Testing
+
+```bash
+# Activate virtual environment
+source .venv/bin/activate   # Linux/macOS
+.venv\Scripts\activate      # Windows
+
+# Run tests
+pytest
+
+# Reinstall package (after source changes)
+pip install -e .
+```
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `click` | CLI framework |
+| `pyyaml` | YAML parsing/serialization |
+| `flask` | Web UI server |
+| `sqlite-vec` | Vector embedding search |
+| `sentence-transformers` | Multilingual embedding model |
+| `pecab` *(optional)* | Korean morphological analysis |
+
+Vector search (`vsearch`, `similar`, `vindex`) is only available when `sqlite-vec` and `sentence-transformers` are installed. FTS5 search works without them.
+
+---
+
+## AI Agent Skill Integration
+
+Skill files are **auto-generated** during `ai-wiki init`. When an agent receives a knowledge-related question, the skill auto-triggers and uses the `ai-wiki` CLI to search, query, and create documents.
+
+| Agent | Skill Path |
+|-------|------------|
+| Claude Code | `~/.claude/skills/<wiki-name>/` |
+| Gemini CLI | `~/.gemini/skills/<wiki-name>/` |
+| GPT Codex | `~/.codex/skills/<wiki-name>/` |
+
+**Skills are installed only to the agents you select during init.**
+
+- **`ai-wiki init`** — Creates skill files in the selected agent paths
+- **`ai-wiki upgrade-skill`** — Updates skill files to the latest version (reads `agents` from `.ai-wiki.yaml`)
+- **`ai-wiki destroy`** — Removes skill files from selected agent paths
+- If `agents` field is missing, defaults to `["claude"]` (backward compatible)
+
+```bash
+# Upgrade skill files to latest version
+ai-wiki upgrade-skill
+```
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

ai_wiki-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ai-wiki"
+version = "0.1.0"
+description = "Structured knowledge wiki CLI for AI agents"
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.0",
+    "pyyaml>=6.0",
+    "flask>=3.0",
+    "sqlite-vec>=0.1.6",
+    "sentence-transformers>=3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/j-dev-team/ai-wiki"
+Repository = "https://github.com/j-dev-team/ai-wiki"
+
+[project.scripts]
+ai-wiki = "ai_wiki.cli:cli"
+ai-wiki-web = "ai_wiki.web:main"
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ai_wiki = ["skill_templates/*.md"]

ai_wiki-0.1.0/setup.cfg

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

ai_wiki-0.1.0/src/ai_wiki/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ai_wiki-0.1.0/src/ai_wiki/catalog.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+
+import yaml
+
+from ai_wiki.storage import get_wiki_root, get_data_dir
+
+
+def get_catalog_path() -> Path:
+    return get_wiki_root() / "index.yaml"
+
+
+def _extract_summary(content: dict) -> str:
+    """content에서 한 줄 요약 추출. #20: what > definition > error_message > purpose 순."""
+    if not isinstance(content, dict):
+        return ""
+    for key in ("what", "definition", "error_message", "purpose"):
+        val = content.get(key)
+        if val and isinstance(val, str):
+            return val[:120]
+    return ""
+
+
+def rebuild_catalog() -> int:
+    """#5: SQLite 기반 카탈로그 생성 (전체 파일 스캔 대신 DB 쿼리)."""
+    db_path = get_data_dir() / "wiki.db"
+
+    if not db_path.exists():
+        # DB 없으면 폴백
+        from ai_wiki.storage import list_all_articles
+        return _rebuild_from_articles(list_all_articles())
+
+    try:
+        conn = sqlite3.connect(str(db_path))
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+        cur.execute("""
+            SELECT id, title, category, tags, confidence, last_modified, content_type,
+                   maturity, quality_score
+            FROM articles_meta
+            ORDER BY category, lower(title)
+        """)
+
+        by_category: dict[str, list] = {}
+        total = 0
+        for row in cur.fetchall():
+            r = dict(row)
+            top_cat = r["category"].split("/")[0]
+            if top_cat not in by_category:
+                by_category[top_cat] = []
+
+            # summary: content에서 추출 필요 → 파일 읽기 (캐시된 경로로 O(1))
+            summary = ""
+            from ai_wiki.storage import load_article
+            article = load_article(r["id"])
+            if article:
+                summary = _extract_summary(article.content)
+
+            by_category[top_cat].append({
+                "id": r["id"],
+                "title": r["title"],
+                "category": r["category"],
+                "type": r["content_type"] or "",
+                "summary": summary,
+                "maturity": r.get("maturity", "unknown"),
+                "quality_score": r.get("quality_score", 0.0),
+                "confidence": r["confidence"],
+                "tags": json.loads(r["tags"] or "[]"),
+                "last_modified": r["last_modified"],
+            })
+            total += 1
+
+        conn.close()
+    except sqlite3.Error:
+        from ai_wiki.storage import list_all_articles
+        return _rebuild_from_articles(list_all_articles())
+
+    _write_catalog(total, by_category)
+    return total
+
+
+def _rebuild_from_articles(articles) -> int:
+    """폴백: Article 리스트에서 카탈로그 생성."""
+    articles.sort(key=lambda a: a.category + "/" + a.title.lower())
+    by_category: dict[str, list] = {}
+    for a in articles:
+        top_cat = a.category.split("/")[0]
+        if top_cat not in by_category:
+            by_category[top_cat] = []
+        by_category[top_cat].append({
+            "id": a.id,
+            "title": a.title,
+            "category": a.category,
+            "type": a.content.get("type", "") if isinstance(a.content, dict) else "",
+            "summary": _extract_summary(a.content),
+            "confidence": a.confidence,
+            "tags": a.tags,
+            "last_modified": a._fmt(a.last_modified),
+        })
+    _write_catalog(len(articles), by_category)
+    return len(articles)
+
+
+def _write_catalog(total: int, by_category: dict) -> None:
+    catalog = {"total": total, "categories": by_category}
+    with open(get_catalog_path(), "w", encoding="utf-8") as f:
+        yaml.dump(catalog, f, allow_unicode=True, default_flow_style=False, sort_keys=False)