@ninebix/nmt-system 1.0.0 → 1.0.2

package/README.md

@@ -1,281 +1,149 @@
 <!--
 ================================================================================
-NINEBIX inc. (주식회사 나인빅스)
+NINEBIX inc.
 Email   : sobdi90@9bix.com
 Website : https://9bix.com
-Corp ID : 476-86-03488
 ================================================================================
 -->
 
 # NMT System (Neuron Merkle Tree)
 
-**확률적 존재론 기반 검증 가능한 의미적 지식 그래프 시스템**
-
-A Probabilistic Ontology-based Verifiable Semantic Knowledge Graph System
+**A Probabilistic Ontology-based Verifiable Semantic Knowledge Graph System**
 
+[![npm version](https://img.shields.io/npm/v/@ninebix/nmt-system.svg)](https://www.npmjs.com/package/@ninebix/nmt-system)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org)
 [![License](https://img.shields.io/badge/License-NSAL%20v1.0-orange)](LICENSE)
 
----
-
-## Target Audience
-
-| 대상 | 활용 방식 |
-|------|----------|
-| **AI/ML 연구자** | 확률적 추론, 확률 분포 기반 지식 표현 연구 |
-| **지식 그래프 개발자** | 검증 가능한 분산 지식 베이스 구축 |
-| **LLM 애플리케이션 개발자** | RAG 시스템 백엔드, 맥락 기반 검색 |
-| **블록체인/DeFi 개발자** | Merkle 증명 기반 데이터 무결성 검증 |
-| **기업 R&D 팀** | 사내 지식 관리, AI 학습 데이터 파이프라인 |
+NMT is a knowledge graph system where **all knowledge exists as probability distributions** rather than deterministic facts. It combines Merkle tree verification, HNSW vector search, and bidirectional inference for building verifiable, distributed knowledge bases.
 
 ---
 
-## Core Features
-
-### 1. Probabilistic Ontology (확률적 존재론)
-
-기존 결정론적 지식 그래프와 달리, **모든 지식이 확률 분포로 존재**합니다.
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│              Probabilistic Ontology Framework                        │
-│                                                                      │
-│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐          │
-│  │  Probabilistic│    │   Attractor  │    │ Bidirectional│          │
-│  │    States     │───▶│    Model     │───▶│  Inference   │          │
-│  │  (확률분포)   │    │  (목표 끌개) │    │ (양방향추론) │          │
-│  └──────────────┘    └──────────────┘    └──────────────┘          │
-│         │                   │                   │                   │
-│         └───────────────────┴───────────────────┘                   │
-│                             │                                       │
-│                    ┌────────┴────────┐                             │
-│                    │  Four-Stage     │                             │
-│                    │  Learning       │                             │
-│                    │ (4단계 학습)    │                             │
-│                    └─────────────────┘                             │
-└─────────────────────────────────────────────────────────────────────┘
-```
+## Features
 
-#### 왜 확률적 존재론인가?
-
-| 기존 방식 | NMT 확률적 방식 | 이점 |
-|----------|----------------|------|
-| "A는 B이다" (결정론) | "A가 B일 확률 0.85" | 불확실성 표현 가능 |
-| 단일 정답 | 다중 가능성 분포 | 복잡한 현실 반영 |
-| 정적 지식 | 관측/맥락에 따른 변화 | 동적 추론 가능 |
-| 원인→결과 단방향 | 원인↔결과 양방향 | 역추론/귀납 가능 |
+- **Probabilistic Ontology** - Knowledge as probability distributions, not fixed facts
+- **Bidirectional Inference** - Forward (cause→effect) and backward (effect→cause) reasoning
+- **Attractor Model** - Goal-oriented decision making with future state influence
+- **Four-Stage Learning** - Extract → Pattern → Process → Outcome learning pipeline
+- **Merkle Verification** - Cryptographic integrity proofs for all data
+- **State Synchronization** - Vector clocks and change journals for distributed systems
+- **Dynamic Embeddings** - Runtime-expandable semantic dimensions
+- **Local Embeddings** - Powered by Xenova/transformers (no external API required)
 
 ---
 
-### 2. Attractor Model (목표 끌개 모델)
-
-**미래 목표가 현재 결정에 영향**을 미치는 목적론적 추론 시스템.
-
-```typescript
-// 목표 끌개 생성
-nmt attractor create "프로젝트 완료" --priority 9 --deadline 2025-03-31
+## Installation
 
-// 현재 상태에서 목표까지의 경로 계산
-nmt attractor path neuron-current attractor-goal
+### From npm
 
-// 목표 확률장의 영향력 계산
-nmt attractor influence neuron-xyz
+```bash
+npm install -g @ninebix/nmt-system
 ```
 
-**활용 사례:**
-- 목표 기반 의사결정 지원
-- 프로젝트 계획 최적화
-- 학습 경로 추천
-
----
-
-### 3. Four-Stage Learning (4단계 학습 시스템)
-
-AI 학습을 **인간의 학습 과정과 유사하게** 구조화:
-
-```
-Stage 1: Extract (추출)
-   ↓
-   유의미한 정보 추출 및 키워드 식별
-   ↓
-Stage 2: Pattern (패턴)
-   ↓
-   반복 패턴 인식 및 분류
-   ↓
-Stage 3: Process (과정)
-   ↓
-   AI 추론 과정 자체를 학습
-   ↓
-Stage 4: Outcome (결과)
-   ↓
-   결과 피드백으로 전체 시스템 개선
-```
+### From Source
 
 ```bash
-# 학습 세션 시작
-nmt learn session start
-
-# 내용 추출
-nmt learn extract neuron-abc --limit 20
-
-# 4단계 전체 실행
-nmt orchestrate learn --input "질문" --output "답변" --success --feedback 0.9
+git clone https://github.com/CopikProjeckId/nmt-system.git
+cd nmt-system
+npm install
+npm run build
+npm link
 ```
 
 ---
 
-### 4. Bidirectional Inference (양방향 추론)
+## Quick Start
 
-원인→결과 (연역)와 결과→원인 (귀납)을 **동시에 수행**:
+### Initialize
 
 ```bash
-# 순방향 추론 (원인 → 결과)
-nmt infer forward neuron-cause --depth 5
-
-# 역방향 추론 (결과 → 원인)
-nmt infer backward neuron-effect --depth 5
+# Initialize data directory
+nmt init
 
-# 인과 관계 탐색
-nmt infer causal neuron-a neuron-b
-
-# 양방향 통합 추론
-nmt infer bidirectional neuron-xyz --depth 3
+# Check system health
+nmt prob health
 ```
 
----
-
-### 5. Merkle Tree Verification (머클 트리 검증)
-
-모든 데이터의 **암호학적 무결성 검증** 지원:
+### Ingest Data
 
 ```bash
-# 뉴런 무결성 검증
-nmt verify neuron neuron-abc
-
-# 증명 생성
-nmt verify proof neuron-abc --index 2
+# Ingest text file
+nmt ingest ./documents/article.txt --tags "ml,tutorial"
 
-# 두 뉴런 간 차이 비교
-nmt verify diff neuron-abc neuron-xyz
-
-# 배치 증명
-nmt verify batch neuron-abc --indices 0,2,5
+# Ingest text directly
+nmt ingest-text "Machine learning is a subset of AI" --tags "ml,ai"
 ```
 
-**Merkle 기능:**
-- Tree Diff: 두 트리 간 변경 사항 추적
-- Batch Proof: 다중 리프 동시 증명
-- Range Proof: 범위 기반 부분 검증
-- Versioned Tree: 버전 관리 및 롤백
-
----
-
-### 6. State Synchronization (상태 동기화)
-
-**분산 환경**을 위한 동기화 인프라:
+### Search
 
 ```bash
-# 동기화 상태 확인
-nmt sync status
-
-# 변경 로그 조회
-nmt sync changes --from 0
+# Semantic search
+nmt search "neural networks" --k 10
 
-# 상태 내보내기
-nmt sync export --output backup.json
-
-# 상태 가져오기
-nmt sync import backup.json
-
-# 연결된 피어 목록
-nmt sync peers
-
-# 저널 통계
-nmt sync journal
+# Get neuron details
+nmt get <neuron-id>
 ```
 
-**동기화 기능:**
-- Vector Clock: 분산 환경 인과 관계 추적
-- Change Journal: 변경 이력 저널링
-- Conflict Resolution: Last-Write-Wins, Vector Clock, Custom Merge 전략
-- Merkle-based Diff: 효율적인 상태 비교
-
----
-
-### 7. Dynamic Embedding (동적 임베딩)
-
-**차원을 동적으로 추가/수정** 가능한 유연한 임베딩:
+### Inference
 
 ```bash
-# 새 차원 등록
-nmt dimension register "감정" --category "sentiment"
+# Forward inference (cause → effect)
+nmt infer forward <neuron-id> --depth 5
 
-# 카테고리별 차원 조회
-nmt dimension category "sentiment"
+# Backward inference (effect → cause)
+nmt infer backward <neuron-id> --depth 5
 
-# 뉴런에 차원 값 설정
-nmt dimension set neuron-abc "감정" 0.8
-```
-
----
+# Find causal chain between neurons
+nmt infer causal <from-id> <to-id>
 
-## Quick Start
-
-### Prerequisites
-
-- Node.js 18+
-- npm or yarn
+# Bidirectional inference
+nmt infer bidirectional <neuron-id> --depth 3
+```
 
-### Installation
+### Attractors (Goal-Oriented Reasoning)
 
 ```bash
-# Clone
-git clone https://github.com/CopikProjeckId/nmt-system.git
-cd nmt-system
+# Create goal attractor
+nmt attractor create "Project Completion" --strength 0.8
 
-# Install
-npm install
+# Find path to goal
+nmt attractor path <neuron-id> <attractor-id>
 
-# Build
-npm run build
+# Calculate goal influence on neuron
+nmt attractor influence <neuron-id>
 ```
 
-### CLI Usage
+### Verification
 
 ```bash
-# 전역 설치 (선택)
-npm link
+# Verify neuron integrity
+nmt verify neuron <neuron-id>
 
-# 도움말
-nmt --help
-
-# 시스템 상태 확인
-nmt prob health
+# Generate Merkle proof
+nmt verify proof <neuron-id> --index 2
 
-# 텍스트 학습
-nmt ingest --text "학습할 내용" --tags "태그1,태그2"
+# Compare two neurons
+nmt verify diff <neuron-a> <neuron-b>
 
-# 검색
-nmt query "검색어" --k 10
-
-# 통합 추론
-nmt orchestrate infer neuron-abc --depth 3
+# Batch verification
+nmt verify batch <neuron-id> --indices 0,2,5
 ```
 
-### API Server
+### State Synchronization
 
 ```bash
-# 개발 서버 시작
-npm run dev
+# Check sync status
+nmt sync status
 
-# 프로덕션 빌드 후 실행
-npm run build
-npm start
-```
+# View change log
+nmt sync changes --from 0
 
-- Backend API: http://localhost:3000
-- Dashboard: http://localhost:5173
+# Export state
+nmt sync export --output backup.json
+
+# Import state
+nmt sync import backup.json
+```
 
 ---
 
@@ -308,7 +176,7 @@ npm start
 │  │                      Core Engines                             │  │
 │  │  ┌────────────┐  ┌────────────┐  ┌────────────┐              │  │
 │  │  │MerkleEngine│  │ HNSWIndex  │  │NeuronGraph │              │  │
-│  │  │(검증/증명) │  │(벡터검색)  │  │(그래프탐색)│              │  │
+│  │  │ (Proofs)   │  │ (Search)   │  │ (Graph)    │              │  │
 │  │  └────────────┘  └────────────┘  └────────────┘              │  │
 │  └───────────────────────────┬──────────────────────────────────┘  │
 │                              │                                      │
@@ -328,50 +196,14 @@ npm start
 
 ---
 
-## Project Structure
+## Why Probabilistic Ontology?
 
-```
-nmt-system/
-├── bin/
-│   └── nmt.ts              # CLI entry point
-├── src/
-│   ├── api/                # REST API (Express)
-│   ├── cli/                # CLI commands
-│   │   ├── commands/       # Command implementations
-│   │   └── utils/          # Validators, formatters
-│   ├── core/               # Core engines
-│   │   ├── merkle-engine.ts
-│   │   ├── hnsw-index.ts
-│   │   ├── neuron-graph.ts
-│   │   ├── probabilistic-orchestrator.ts
-│   │   ├── probabilistic-neuron.ts
-│   │   ├── bidirectional-inference.ts
-│   │   ├── attractor-model.ts
-│   │   ├── dynamic-embedding.ts
-│   │   └── evolution-scheduler.ts
-│   ├── events/             # Event system
-│   │   ├── event-bus.ts
-│   │   └── progress-tracker.ts
-│   ├── services/           # Business logic
-│   │   ├── four-stage-learning.ts
-│   │   ├── ingestion.ts
-│   │   ├── query.ts
-│   │   └── embedding-provider.ts
-│   ├── storage/            # Persistence (LevelDB)
-│   │   ├── probabilistic-store.ts
-│   │   ├── neuron-store.ts
-│   │   └── chunk-store.ts
-│   ├── sync/               # State synchronization
-│   │   ├── state-sync.ts
-│   │   ├── change-journal.ts
-│   │   └── vector-clock.ts
-│   ├── types/              # TypeScript definitions
-│   └── utils/              # Utilities
-├── tests/                  # Test suites
-├── dashboard/              # React dashboard (optional)
-├── docs/                   # Documentation
-└── data/                   # Runtime data
-```
+| Traditional Approach | NMT Probabilistic Approach | Benefit |
+|---------------------|---------------------------|---------|
+| "A is B" (deterministic) | "A is B with probability 0.85" | Express uncertainty |
+| Single answer | Multiple possibility distribution | Reflect complex reality |
+| Static knowledge | Context-dependent changes | Dynamic reasoning |
+| Cause → Effect only | Cause ↔ Effect bidirectional | Abductive reasoning |
 
 ---
 
@@ -381,26 +213,27 @@ nmt-system/
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
-| `/api/v1/ingest` | POST | 텍스트 학습 |
-| `/api/v1/ingest/url` | POST | URL 학습 |
-| `/api/v1/query/search` | POST | 의미적 검색 |
-| `/api/v1/rag/query` | POST | RAG 질의 |
-| `/api/v1/graph/neuron/:id` | GET | 뉴런 상세 |
-| `/api/v1/graph/full` | GET | 전체 그래프 |
-| `/api/v1/health` | GET | 헬스 체크 |
-| `/api/v1/metrics` | GET | 시스템 메트릭 |
+| `/api/v1/ingest` | POST | Ingest text content |
+| `/api/v1/ingest/url` | POST | Ingest from URL |
+| `/api/v1/query/search` | POST | Semantic search |
+| `/api/v1/rag/query` | POST | RAG query |
+| `/api/v1/graph/neuron/:id` | GET | Get neuron details |
+| `/api/v1/graph/full` | GET | Get full graph |
+| `/api/v1/health` | GET | Health check |
+| `/api/v1/metrics` | GET | System metrics |
 
 ### CLI Commands
 
 | Category | Commands |
 |----------|----------|
+| **Core** | `init`, `ingest`, `search`, `get`, `list`, `stats` |
 | **Inference** | `infer forward`, `backward`, `causal`, `bidirectional` |
 | **Learning** | `learn extract`, `session` |
 | **Attractor** | `attractor create`, `path`, `influence` |
 | **Dimension** | `dimension register`, `category`, `set` |
-| **Orchestrate** | `orchestrate infer`, `learn`, `feedback`, `reinforce` |
-| **Sync** | `sync status`, `changes`, `export`, `import`, `peers` |
-| **System** | `prob metrics`, `health`, `prometheus` |
+| **Sync** | `sync status`, `changes`, `export`, `import` |
+| **Verify** | `verify neuron`, `proof`, `diff`, `batch` |
+| **System** | `prob metrics`, `health`, `dashboard` |
 
 ---
 
@@ -416,18 +249,38 @@ nmt-system/
 
 ---
 
+## Configuration
+
+Create `.env` file in your project root:
+
+```env
+# Data directory for LevelDB storage
+DATA_DIR=./data
+
+# Dashboard server port
+PORT=3000
+
+# HNSW Index Parameters
+HNSW_M=16
+HNSW_EF_CONSTRUCTION=200
+HNSW_EF_SEARCH=50
+
+# Text Chunking
+CHUNK_SIZE=512
+CHUNK_OVERLAP=50
+
+# Logging
+LOG_LEVEL=info
+```
+
+---
+
 ## Documentation
 
-### English
-- [User Guide](docs/USER_GUIDE_EN.md)
-- [CLI API Reference](docs/CLI_API_EN.md)
+- [User Guide (EN)](docs/USER_GUIDE_EN.md)
+- [CLI API Reference (EN)](docs/CLI_API_EN.md)
 - [Architecture](docs/ARCHITECTURE.md)
-- [Quick Reference](docs/QUICK_REFERENCE.md)
-
-### 한국어 (Korean)
-- [한글 문서](docs/README_KO.md)
-- [사용자 가이드](docs/USER_GUIDE.md)
-- [CLI API 레퍼런스](docs/CLI_API.md)
+- [한국어 문서](docs/README_KO.md)
 
 ---
 
@@ -456,8 +309,9 @@ This project is licensed under the [NINEBIX Source Available License (NSAL) v1.0
 
 ## Acknowledgments
 
-- Built with TypeScript, React, Express, LevelDB
+- Built with TypeScript, Express, LevelDB
 - Vector search powered by HNSW algorithm
+- Embeddings by Xenova/transformers
 - Cryptographic hashing via SHA3-256
 
 ---