derekinside 0.7.0__tar.gz

derekinside-0.7.0/LICENSE

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

derekinside-0.7.0/PKG-INFO

@@ -0,0 +1,406 @@
+Metadata-Version: 2.4
+Name: derekinside
+Version: 0.7.0
+Summary: Local-first AI knowledge system — multi-model entity extraction, knowledge graph, self-learning consensus, constraint-solving pipeline
+Author-email: aITMS01 <aitms01@derekinside.dev>, Derek Wang <derek@derekinside.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/derekwang85/derekinside
+Project-URL: Repository, https://github.com/derekwang85/derekinside
+Project-URL: Documentation, https://github.com/derekwang85/derekinside#readme
+Project-URL: Bug Tracker, https://github.com/derekwang85/derekinside/issues
+Keywords: knowledge-graph,rag,entity-extraction,ai-memory,local-ai,agent-memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: click>=8.0
+Requires-Dist: psycopg[binary]>=3.1
+Provides-Extra: pgvector
+Requires-Dist: psycopg-pool>=3.1; extra == "pgvector"
+Provides-Extra: ollama
+Requires-Dist: httpx>=0.27; extra == "ollama"
+Provides-Extra: http
+Requires-Dist: fastapi>=0.100; extra == "http"
+Requires-Dist: uvicorn>=0.24; extra == "http"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.15; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT">
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+">
+  <img src="https://img.shields.io/badge/version-0.7.0-blue" alt="Version">
+  <img src="https://img.shields.io/github/actions/workflow/status/derekwang85/derekinside/ci.yml?label=CI" alt="CI">
+  <img src="https://img.shields.io/badge/coverage-65%25-green" alt="Coverage">
+  <img src="https://img.shields.io/github/stars/derekwang85/derekinside" alt="Stars">
+  <img src="https://img.shields.io/github/last-commit/derekwang85/derekinside" alt="Last Commit">
+</p>
+
+<h1 align="center">🧠 DereInside</h1>
+<p align="center"><em>Know your project from the inside out. / 由内而外地了解你的项目。</em></p>
+
+<p align="center">
+  <strong>Local-first · Multi-model · Self-learning · Agent-native</strong>
+  <br>
+  The AI knowledge system that <strong>understands your code</strong> — not just retrieves it.
+  <br>
+  理解你的代码的 AI 知识系统 —— 而不只是检索它。
+</p>
+
+---
+
+## 🆕 Latest Updates
+
+> **v0.7.0** — 正式发布到 PyPI + ghcr.io：50K star 路线图阶段 0 全部技术准备就绪
+
+- **🚀 正式发布** — 首个可安装发布：`pip install derekinside`，多架构 Docker 镜像（ghcr.io），GitHub Release 自动草拟。
+- **📦 发布流水线 (c7/c8)** — `release.yml`：tag 触发 → verify → build → PyPI（Trusted Publishing/OIDC）→ Docker（buildx 多架构）→ 草拟 Release。
+- **🏛️ 规约体系文档完整性补全 (d1-d3)** — ADR-002 / everos-analysis.md / user_profile.md 补齐，全项目引用零断链；新增阶段 0 发布检查清单。
+- **🗺️ 50K star 执行进度同步 (d4-d5)** — 路线图报告新增「执行进度总览」，完成状态统一标注。
+
+> **v0.6.0** — 规约体系 + sync/fact 图谱 + ContextGate 上下文门禁 + EverOS 裁决
+
+- **🏗️ Model Registry (Track A)** — 6+ 可插拔模型端点（Ollama / vLLM / OpenAI / FreeCode / MiniMax），四维画像自动探测（capabilities × intelligence × cost × speed × quality）。
+- **🧩 Constraint-Solving Pipeline** — 不是线性 fallback，而是多维约束求解器：按智能/成本/延迟过滤、按目标排序、优雅降级。
+- **🔄 Self-Learning Consensus** — 多模型交叉验证，自动拒绝噪音实体。
+- **🧬 Knowledge Graph 爆炸增长** — 生产知识图谱实体 5,485 个（7.9x），链接 10,817 个（7.6x）。
+- **📊 评测可复现 (c5)** — 新增 `long_mem_eval.py --offline` 确定性离线基线（7 样本 / 48 实体，P 92.9% · R 27.7% · F1 0.426），无 DB/LLM 即可复现。
+- **🧪 CI 强化 (c2/c3)** — ruff 全量+格式门禁、离线套件 coverage 门禁（63%）、真实 PostgreSQL service job（pgvector 集成测试 8/8），离线单测 363 项全绿。
+
+---
+
+## 🏆 Why DereInside?
+
+Most "AI knowledge" tools are black boxes. One embedding model. One pipeline. One size fits nobody.
+
+**DereInside is different.** It's a **multi-model cognitive engine** — not a vector database with a chat wrapper.
+
+| What others do | What DereInside does |
+|:--------------|:--------------------|
+| One embedding model for everything | **6 interchangeable models**, auto-switched by content type |
+| Fixed pipeline, no tuning | **Constraint-solving pipeline** — define what you need (intelligence × cost × speed), the system selects the best model |
+| Black-box evaluation | **Quantified public benchmarks** (LongMemEval) — every mode has measurable precision/recall/F1 |
+| Manual prompt engineering | **Self-learning consensus** — multiple models cross-validate each other, automatically rejecting noise |
+| Tool-specific lock-in (Ollama only) | **Open provider architecture** — Ollama / vLLM / OpenAI / FreeCode / MiniMax / any OpenAI-compatible endpoint |
+| Static knowledge | **Living knowledge graph** — entities, relations, cross-Wing fusion, temporal decay |
+| Cloud-dependent | **Zero-cloud optional** — runs on a Raspberry Pi 4; GPU optional, not required |
+
+---
+
+## 🧬 Architecture — Designed, Not Patched
+
+DereInside's architecture is the result of **deliberate engineering**, not organic growth. Every layer was designed to solve a real constraint:
+
+```
+                     ┌─────────────────────┐
+                     │     Model Registry   │
+                     │  6+ model endpoints  │
+                     │ (Ollama/vLLM/OpenAI) │
+                     └──────┬──────────────┘
+                            │
+              ┌─────────────┼─────────────┐
+              ▼             ▼             ▼
+      ┌────────────┐ ┌──────────┐ ┌──────────┐
+      │ Embedding  │ │Extraction│ │ Rerank   │
+      │ Pipeline   │ │Pipeline  │ │ Pipeline │
+      └──────┬─────┘ └────┬─────┘ └────┬─────┘
+             │            │            │
+             ▼            ▼            ▼
+      ┌──────────────────────────────────────┐
+      │        Constraint Solver             │
+      │  Filter: intel × cost × latency      │
+      │  Rank:   quality / speed / cost      │
+      │  Relax:  graceful degradation        │
+      └──────────────────────────────────────┘
+```
+
+### 🎯 Model Registry — First-Class Models, Not Plumbing
+
+Every AI endpoint is a **first-class citizen** with a **four-dimensional profile**:
+
+```yaml
+models:
+  qwen-7b:
+    driver: ollama        # Transport: Ollama
+    capabilities: [extract, rerank]  # What it can do
+    intelligence: high     # How smart it is
+    cost_tier: free        # What it costs
+    speed_tier: slow       # How fast it runs
+    quality: high          # Output quality
+```
+
+This means you can **swap providers without changing code**. In production? Switch from Ollama to vLLM for GPU acceleration. API budget available? Add OpenAI as a fallback. Using FreeCode's free tier? Add it in one line — the system auto-profles its capabilities.
+
+### 🔄 Pipeline Resolver — Constraint Solving, Not Fallback Chains
+
+```yaml
+pipeline:
+  extract:
+    requires:
+      min_intelligence: low    # Only smart enough models
+      max_cost: free           # Only free models
+      max_latency_ms: 10000    # Under 10 seconds
+    objective: optimize_quality
+    candidates:
+      - qwen-7b                # High quality, free
+      - qwen-1.5b              # Faster fallback
+      - gpt-4o-mini            # ❌ Excluded: paid
+```
+
+Not a linear "try A then B then C" — a **multi-dimensional constraint solver**:
+- Filters by intelligence requirement
+- Filters by cost budget
+- Filters by latency ceiling
+- Checks model health
+- Ranks by objective (quality / speed / cost)
+- **Relaxes constraints gracefully** when no model matches, with clear logging
+
+### 🧪 Model Profiler — Zero-Conf Auto-Detection
+
+Users shouldn't need to know their model's specs. DereInside **probes models automatically**:
+
+```python
+class ModelProfiler:
+    # Golden data from LongMemEval — zero external API cost
+    SMOKE_SET = [3 samples, ~2s]     # Boot positioning
+    FULL_SET  = [15 samples, ~10s]   # Deep benchmark
+
+    def profile(self, model) -> ModelProfile:
+        return ModelProfile(
+            capabilities=self._detect_capabilities(model),  # What can it do?
+            intelligence=self._measure_intelligence(model), # How smart?
+            speed=self._measure_speed(model),               # How fast?
+            quality=self._measure_quality(model),           # How accurate?
+            cost_tier=self._guess_cost(model),              # How expensive?
+        )
+```
+
+**Passive observer**: runtime metrics (latency, entity count, error rate) collected as zero-cost side effects. When it detects anomalies — latency doubling, entity count dropping — it triggers a re-profle automatically.
+
+**Oscillation detection**: if a FreeCode model keeps changing, profle freezes after 3 probes and alerts instead of chasing instability.
+
+---
+
+## 🧠 Self-Learning Consensus
+
+DereInside doesn't trust a single model. It **cross-validates across multiple extraction modes**:
+
+```
+Chunk: "class OrderService extends BaseService { @Autowired ... }"
+
+  regex      → {OrderService, BaseService}          (精95.6%)
+  hybrid-7b  → {OrderService, BaseService, ...}     (精77.4%)
+  1.5b       → {OrderService, BaseService, Autowired} (高召回, 有噪音)
+
+  ConsensusEngine:
+    OrderService  3/3  → confirmed  (weight=1.0) ✓
+    BaseService   3/3  → confirmed  (weight=1.0) ✓
+    Autowired     1/3  → rejected   (weight=0.0) ✗  (噪音: 非实体)
+```
+
+**Result**: noise rejection improves with each extraction run. After 3 full cycles on a 2,467-chunk codebase, estimated noise drops from ~28% to ~10%.
+
+---
+
+## 🏗️ Knowledge Graph — Rich, Clean, Connected
+
+DereInside builds a knowledge graph that understands **relationships**, not just keywords:
+
+| Relation | Source | Semantics |
+|:---------|:-------|:----------|
+| `OrderService` → `BaseService` | `class OrderService extends BaseService` | **extends** |
+| `KYCController` → `/api/kyc/submit` | `@PostMapping("/api/kyc/submit")` | **serves_path** |
+| `AuditService` → `AuditLogRepository` | `@Autowired` | **depends_on** |
+| `TradeEntity` ↔ `PositionService` | Field declaration | **has_field** |
+| `KYCApplication` → (merged) `KYC申请` | Entity resolution | **alias** |
+
+**Entity resolution** automatically merges:
+- `KYCApplication` = `kycapplication` = `KYC 申请` (alias dict)
+- `AuditServiceImpl` → `AuditService` (suffix stripping)
+- Cross-wing duplicates → automatic fusion
+
+**Subgraph queries** traverse the graph:
+```bash
+derekinside graph subgraph "KYC" --depth 2 --ascii
+# → 🔍 KYC (concept)
+#     ├─ KYCApplication (class) ← depends_on
+#     ├─ KYCController (class) ← serves_path: /api/kyc/submit
+#     ├─ 合同审批流程 (concept) ← related
+```
+
+---
+
+## 📊 Quantified — Not Hype
+
+Every extraction mode is benchmarked on **LongMemEval** with human-annotated ground truth. The **offline fixed-corpus baseline** is fully deterministic and reproducible on any machine (no DB or LLM required), so you always get the same numbers:
+
+```bash
+python3 scripts/long_mem_eval.py --offline
+```
+
+| Mode | Corpus | Precision | Recall | F1 | Uses |
+|:-----|:------:|:--------:|:------:|:--:|:-----|
+| **regex (offline)** | 7 samples / 48 entities | **92.9%** | 27.7% | **0.426** | Code entities |
+| **hybrid-1.5b / 7B** | requires local ollama | — | — | — | General purpose |
+
+> LLM/hybrid comparison (1.5B / 7B) runs in the `qwen2.5-coder` mode against your local ollama endpoint. Run the same script **without** `--offline` against a populated database to reproduce the full 100-chunk comparison on your own data.
+
+**Smart Dispatch** automatically selects the right mode per chunk:
+```
+.cjava/.py → regex        (精92.9%)
+.md/.txt   → hybrid-1.5b  (needs local ollama)
+.xml/.sql  → 1.5b          (needs local ollama)
+.log       → skip           (0s)
+```
+
+Result: **2,467 chunks reduced from 5h26m to ~1.5h** with weighted F1 improvement of ~15%.
+
+---
+
+## 🏭 Production Profile (as of June 2026)
+
+DereInside is running in production powering the aITMS01 engineering workflow:
+
+| Metric | Value | Growth |
+|:-------|:-----:|:------:|
+| **Wings** (knowledge domains) | **21** | +50% from launch |
+| **Rooms** (sub-domains) | **54** | +20% |
+| **Pages** (ingested) | **599** | +8% |
+| **Chunks** (indexed) | **2,931** | +11%, 100% embedded |
+| **Knowledge Graph Entities** | **5,485** | **7.9x** |
+| **Knowledge Graph Links** | **10,817** | **7.6x** |
+
+The knowledge graph explosion (7.9x entities, 7.6x links) is the direct result of the Model Registry + constraint-solving pipeline — the system now discovers relationships across code, documents, and conversations that were invisible under the old single-model architecture.
+
+**What this means in practice:**
+- Zero cloud dependency — runs on a single VM with PostgreSQL
+- All embeddings, extractions, and graph operations local
+- API response < 200ms for search queries
+- Full re-index of 2,931 chunks completes in ~1.5h (was 5h26m before smart dispatch)
+- Agent-native: MCP server provides structured context to sub-agents at spawn time
+
+---
+
+## ⚡ Quick Start
+
+```bash
+# Install
+pip install derekinside
+
+# Ingest your project
+derekinside mine ~/TradeOMS --wing=tradeoms
+
+# Build the knowledge graph
+derekinside graph build
+
+# Search
+derekinside search "KYC approval flow"
+
+# Serve as API for AI agents
+derekinside serve --mode http --port 18890
+
+# Explore the graph
+derekinside graph subgraph "OrderService" --depth 2 --ascii
+```
+
+### MCP Integration (AI Agent ready)
+
+```python
+# Your AI agent gets persistent memory via MCP
+from mcp import ClientSession
+
+session = ClientSession("http://localhost:18890")
+context = session.query("What is the KYC process?")
+# → Returns entities, relations, and ranked chunks
+```
+
+---
+
+## 🛣️ Roadmap
+
+| Phase | Status | What |
+|:------|:------:|:-----|
+| **Phase 0** | ✅ | gbrain → DereInside migration |
+| **Phase 1-2** | ✅ | Hierarchical indexes + knowledge graph |
+| **Phase 2.5** | ✅ | 5-mode extraction + LongMemEval benchmarks |
+| **Phase 3** | ✅ | MCP server + HTTP bridge + per-agent isolation |
+| **Track A** | ✅ | **Model Registry + Pipeline + Profiler** — architectural overhaul |
+| **Track B** | ✅ | Smart dispatch, Consensus self-learning, Cross-wing fusion, Temporal decay |
+| **Track C** | ✅ | Relation inferrer, Entity resolution, Graph pruning, Enrichment, Subgraph |
+| **Phase 4** | 🚧 | Multi-model ensemble + Agent-native context gate |
+| **Phase 5** | 📋 | Web UI dashboard + collaborative annotations |
+| **Phase 6** | 📋 | Fleet learning — share profles across instances |
+| **EverOS Merger** | 📋 | Evaluate EverOS integration (see [RFC-0002](docs/rfcs/0002-everos-merge.md)) |
+| **Fact Logging** | 📋 | Cross-Agent shared memory (see [RFC-0001](docs/rfcs/0001-fact-logging.md)) |
+
+---
+
+## 🤝 Contributing
+
+We're building something that matters. If you share the vision:
+
+- **Code contributors**: See [CONTRIBUTING.md](CONTRIBUTING.md) — we welcome PRs
+- **Testers**: Run LongMemEval on your own data and share results
+- **Feedback**: Open an issue or start a discussion
+- **Sponsors**: Reach out if DereInside saves your team time
+
+---
+
+## 📜 License
+
+MIT — free for any use, commercial or otherwise.
+
+---
+
+<details>
+<summary>🌏 中文简介 / Chinese Overview</summary>
+
+### DereInside 是什么？
+
+一个 **本地优先 · 多模型 · 自学习 · 面向智能体（Agent）** 的 AI 代码知识系统。区别于"向量数据库 + 聊天外壳"，DereInside 是一台**多模型认知引擎**：
+
+- **多模型注册表**：6+ 可插拔模型端点（Ollama / vLLM / OpenAI / FreeCode / MiniMax 等），按内容类型自动切换。
+- **约束求解流水线**：代码里声明需要的智能度 × 成本 × 速度，系统自动挑选最优模型，而非"先试 A 再试 B"的线性回退。
+- **自学习共识**：多个模型互相校验，自动剔除噪音实体，错误率随运行次数下降。
+- **活的知识图谱**：实体、关系、跨 Wing 融合、时间衰减——不只存关键词，还理解"谁依赖谁、谁提供什么接口"。
+- **零云端可选**：在树莓派 4 上也能跑，GPU 可选、非必需。
+- **评测可复现**：离线确定性基线让你在任何机器上得到完全相同的精确率/召回率/F1 数值。
+
+### 快速上手
+
+```bash
+pip install derekinside
+derekinside mine ~/TradeOMS --wing=tradeoms   # 摄取项目
+derekinside graph build                        # 构建知识图谱
+derekinside search "KYC approval flow"         # 语义搜索
+derekinside serve --mode http --port 18890     # 起 API（供 AI 智能体调用）
+```
+
+支持 MCP 协议，接入后你的 AI 智能体在生成时即可获得结构化上下文。
+
+</details>
+
+---
+
+<p align="center">
+  <strong>🧠 DereInside: Know your project from the inside out.</strong>
+  <br>
+  <em>From one engineer who refused to build another black box.</em>
+  <br>
+  🌏 中英双语维护中 · 欢迎参与贡献
+</p>