aelvoxim 1.0.0__tar.gz

aelvoxim-1.0.0/LICENSE

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

aelvoxim-1.0.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: aelvoxim
+Version: 1.0.0
+Summary: Lightweight AI Cognitive Engine Framework — give your AI a memory
+Author-email: macor24 <macor@gealss.com>
+License: MIT
+Project-URL: Homepage, https://github.com/macor24/aelvoxim
+Project-URL: Repository, https://github.com/macor24/aelvoxim
+Project-URL: Documentation, https://github.com/macor24/aelvoxim/tree/master/docs
+Keywords: ai,agent,cognitive-engine,memory,self-learning,framework
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Application Frameworks
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bcrypt>=4.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn[standard]>=0.20.0
+Provides-Extra: pg
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "pg"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Provides-Extra: dev
+Requires-Dist: aelvoxim[pg,test]; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Provides-Extra: full
+Requires-Dist: aelvoxim[pg]; extra == "full"
+Dynamic: license-file
+
+# Aelvoxim
+
+<p align="center">
+  <img src="docs/Aelvoxim2.jpg" alt="Aelvoxim" width="600">
+</p>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/aelvoxim)](https://pypi.org/project/aelvoxim/)
+[![GitHub Repo](https://img.shields.io/badge/GitHub-macor24%2Faelvoxim-181717?logo=github)](https://github.com/macor24/aelvoxim)
+
+**Aelvoxim — Lightweight AI Cognitive Engine Framework.**
+
+Give your AI application a "memory" — it remembers, reasons, learns, and has meta-cognition.
+
+---
+
+## Quick Start
+
+```bash
+# Install
+pip install aelvoxim
+
+# Start the server
+aelvoxim server --port 9701
+
+# Open in browser
+open http://localhost:9701
+
+# Or use the ChatAEL frontend (dedicated chat UI)
+python serve_chatael.py
+# Open http://localhost:9702
+```
+
+### From source
+
+```bash
+git clone https://github.com/macor24/aelvoxim.git
+cd aelvoxim
+pip install -e .
+python src/run_server.py 9701
+```
+
+---
+
+## Use Cases
+
+Aelvoxim's layered memory, autonomous learning, and meta-cognition unlock scenarios that ordinary LLM wrappers and RAG pipelines cannot handle.
+
+### 🧑‍🤝‍🧑 Long-Living Virtual Character
+Most AI agents lose everything on restart — Aelvoxim doesn't.
+
+- Conversations are stored in **episodic memory** and **never reset**
+- User preferences and speaking style are extracted into **semantic memory** (persist across sessions)
+- The **forgetting curve** naturally prioritizes recent interactions while preserving core facts
+- After weeks of use, the character grows to genuinely know the user, instead of starting from scratch every session
+
+### 📚 Living Code Documentation
+Hook Aelvoxim into your Git workflow and let it maintain your project docs automatically.
+
+- Connect via **GitHub/GitLab webhook** — every PR merge triggers re-learning
+- Aelvoxim scans new code, extracts module APIs, and updates its knowledge base
+- **Conflict detection** flags when an interface changed but docs weren't updated
+- Team members ask "how does this function work?" and get answers grounded in actual code, not stale docs
+
+### 🔍 Continuous Compliance Monitoring (Medical / Legal)
+Meta-cognition + auto-validation as a regulatory watchdog.
+
+- Store regulations, guidelines, or protocols in the knowledge base
+- **Curiosity-driven discovery** periodically searches for new versions or updates
+- **Conflict detection** catches contradictions between new and old knowledge automatically
+- Output validation ensures every answer stays within compliance boundaries
+- No manual review cycles needed — the system watches itself
+
+### 🧠 Personal Learning Companion
+Unlike ChatGPT where every conversation is isolated, Aelvoxim builds a persistent model of what you know.
+
+- Tracks what you've learned and which concepts you find confusing
+- **Forgetting curve** schedules review reminders at optimal intervals
+- Extracts knowledge triples from your notes automatically (knowledge distillation)
+- **Gap analysis** identifies blind spots and suggests what to study next
+- Over time it becomes a second brain that knows your knowledge landscape
+
+### 📊 Automated Business Intelligence
+Turn curiosity-driven learning into a competitive radar.
+
+- Define interest directions (competitor moves, industry news, tech trends)
+- **Curiosity engine** autonomously discovers and fetches relevant content
+- Extracted insights are stored as structured knowledge
+- **Conflict alerts** fire when new information contradicts existing beliefs (e.g. a competitor changed pricing)
+- No manual keyword rules — the AI decides what's worth learning
+
+### ⚙️ Self-Tuning Service Bot
+Deploy a support bot that tunes itself — no DevOps babysitting required.
+
+- Out of the box it works with conservative defaults
+- **Auto calibration** monitors real response quality and adjusts parameters (temperature, expert weights, memory thresholds) based on what actually works
+- When traffic patterns shift (e.g. more technical questions at certain hours), the system adapts without a config push
+- **Knowledge gap analysis** spots missing answers and automatically initiates learning
+- Over weeks the bot silently improves — your only job is to keep it running
+
+---
+
+## Features
+
+### 🧠 Memory System
+Your AI remembers like a human — with layers, decay, and doubt.
+
+| Capability | Description |
+|------------|-------------|
+| **4-layer memory** | Working / Episodic / Semantic / Procedural |
+| **MemoryFusion** | Inverted index + multi-layer retrieval |
+| **Forgetting curve** | Knowledge decays naturally (Ebbinghaus) |
+| **Conflict detection** | Finds contradictions, alerts the user |
+| **Confidence Matrix** | 5-dimensional trust score on every response |
+
+### 🔧 Expert System
+A team of specialized AI experts working together.
+
+| Expert | Role | Community | Pro |
+|--------|------|-----------|-----|
+| LogicExpert | Rule reasoning, contradiction detection | ✅ | ✅ |
+| MemoryExpert | Memory retrieval, fusion search | ✅ | ✅ |
+| EthicsExpert | 15 ethical rules, transparent & auditable | ✅ | ✅ |
+| SafetyExpert | Local keyword + regex safety checks | ✅ | ✅ |
+| CodeReviewExpert | Code style, complexity, secret scanning | ✅ | ✅ |
+| EmotionExpert | Sentiment analysis, empathetic response | ❌ | ✅ |
+| CreativeExpert | Creative writing, content generation | ❌ | ✅ |
+| IntrospectionExpert | Self-reflection, quality audit | ❌ | ✅ |
+| HypothesisEngine | Root cause hypothesis & validation | ❌ | ✅ |
+
+### 📚 Learning System
+
+| Capability | Community | Pro |
+|------------|-----------|-----|
+| Manual learning (API trigger) | ✅ | ✅ |
+| 7×24 auto-learning loop | ❌ | ✅ |
+| Curiosity-driven discovery | ❌ | ✅ |
+| Auto parameter tuning | ❌ | ✅ |
+| Knowledge gap analysis | ❌ | ✅ |
+| Post-validation audit | ❌ | ✅ |
+
+### 🔌 API & Integration
+- **RESTful API** — FastAPI, Swagger docs at `/docs`
+- **SSE streaming** — Real-time token-by-token output
+- **Multi-user auth** — Email/password registration + API Keys
+- **Knowledge base CRUD** — Add, search, update, delete knowledge entries
+- **Session management** — Persistent conversations with history
+
+---
+
+## Architecture
+
+```
+aelvoxim/
+├── src/aelvoxim/
+│   ├── core/         Cognitive engine (belief, metacog, reasoner, judge, DGM-H)
+│   ├── learn/        Learning engine (learner, KB, validator, search, curiosity)
+│   ├── memory/       Memory system (4 layers, fusion, decay, conflict, scoring)
+│   ├── server/       API server (FastAPI, auth, chat pipeline, sessions)
+│   ├── cortex/       Brain cortex (intent routing, scheduler)
+│   ├── experts/      Expert system (orchestrator, 5+ experts, registry)
+│   ├── storage/      Dual storage (SQLite local, PostgreSQL production)
+│   ├── utils/        Helpers (i18n, paths, JSON)
+│   └── edition.py    Edition gating (community/pro config control)
+├── frontend/
+│   └── chatael-v2/   ChatAEL — React + Tailwind chat UI
+├── tests/            130+ test cases
+├── docs/
+├── CONTRIBUTING.md
+├── SECURITY.md
+└── LICENSE (MIT)
+```
+
+---
+
+## Community vs Pro
+
+| Dimension | Community (free, MIT) | Pro (license key) |
+|-----------|----------------------|-------------------|
+| Learning | Manual trigger | 7×24 auto loop |
+| Discovery | User-specified | Curiosity-driven |
+| Tuning | Static defaults | Dynamic auto-tune |
+| Experts | 5 core | 12 total (incl. advanced) |
+| Validation | None | Scheduled auto-scan |
+| Security | Local rules | SentriKit deep engine |
+| License | MIT | License key |
+
+---
+
+## External Dependencies
+
+Only **3 external packages** — everything else is Python standard library.
+
+| Package | Purpose |
+|---------|---------|
+| `bcrypt` | Password hashing |
+| `fastapi` | API framework |
+| `uvicorn` | ASGI server |
+
+---
+
+## Why Aelvoxim?
+
+- **Lightweight** — 3 deps, 34k lines of Python, no Docker required
+- **Self-contained** — SQLite for single-user, PostgreSQL for multi-user
+- **Private by design** — Your data stays on your machine, no telemetry
+- **Dual storage** — SQLite for dev, PostgreSQL for production, same code
+- **Built-in safety** — Ethics rules, safety checks, meta-cognition monitoring
+
+---
+
+## License
+
+MIT License — Copyright (c) 2026 macor24
+
+See [LICENSE](./LICENSE) for details.

aelvoxim-1.0.0/README.md

@@ -0,0 +1,217 @@
+# Aelvoxim
+
+<p align="center">
+  <img src="docs/Aelvoxim2.jpg" alt="Aelvoxim" width="600">
+</p>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/aelvoxim)](https://pypi.org/project/aelvoxim/)
+[![GitHub Repo](https://img.shields.io/badge/GitHub-macor24%2Faelvoxim-181717?logo=github)](https://github.com/macor24/aelvoxim)
+
+**Aelvoxim — Lightweight AI Cognitive Engine Framework.**
+
+Give your AI application a "memory" — it remembers, reasons, learns, and has meta-cognition.
+
+---
+
+## Quick Start
+
+```bash
+# Install
+pip install aelvoxim
+
+# Start the server
+aelvoxim server --port 9701
+
+# Open in browser
+open http://localhost:9701
+
+# Or use the ChatAEL frontend (dedicated chat UI)
+python serve_chatael.py
+# Open http://localhost:9702
+```
+
+### From source
+
+```bash
+git clone https://github.com/macor24/aelvoxim.git
+cd aelvoxim
+pip install -e .
+python src/run_server.py 9701
+```
+
+---
+
+## Use Cases
+
+Aelvoxim's layered memory, autonomous learning, and meta-cognition unlock scenarios that ordinary LLM wrappers and RAG pipelines cannot handle.
+
+### 🧑‍🤝‍🧑 Long-Living Virtual Character
+Most AI agents lose everything on restart — Aelvoxim doesn't.
+
+- Conversations are stored in **episodic memory** and **never reset**
+- User preferences and speaking style are extracted into **semantic memory** (persist across sessions)
+- The **forgetting curve** naturally prioritizes recent interactions while preserving core facts
+- After weeks of use, the character grows to genuinely know the user, instead of starting from scratch every session
+
+### 📚 Living Code Documentation
+Hook Aelvoxim into your Git workflow and let it maintain your project docs automatically.
+
+- Connect via **GitHub/GitLab webhook** — every PR merge triggers re-learning
+- Aelvoxim scans new code, extracts module APIs, and updates its knowledge base
+- **Conflict detection** flags when an interface changed but docs weren't updated
+- Team members ask "how does this function work?" and get answers grounded in actual code, not stale docs
+
+### 🔍 Continuous Compliance Monitoring (Medical / Legal)
+Meta-cognition + auto-validation as a regulatory watchdog.
+
+- Store regulations, guidelines, or protocols in the knowledge base
+- **Curiosity-driven discovery** periodically searches for new versions or updates
+- **Conflict detection** catches contradictions between new and old knowledge automatically
+- Output validation ensures every answer stays within compliance boundaries
+- No manual review cycles needed — the system watches itself
+
+### 🧠 Personal Learning Companion
+Unlike ChatGPT where every conversation is isolated, Aelvoxim builds a persistent model of what you know.
+
+- Tracks what you've learned and which concepts you find confusing
+- **Forgetting curve** schedules review reminders at optimal intervals
+- Extracts knowledge triples from your notes automatically (knowledge distillation)
+- **Gap analysis** identifies blind spots and suggests what to study next
+- Over time it becomes a second brain that knows your knowledge landscape
+
+### 📊 Automated Business Intelligence
+Turn curiosity-driven learning into a competitive radar.
+
+- Define interest directions (competitor moves, industry news, tech trends)
+- **Curiosity engine** autonomously discovers and fetches relevant content
+- Extracted insights are stored as structured knowledge
+- **Conflict alerts** fire when new information contradicts existing beliefs (e.g. a competitor changed pricing)
+- No manual keyword rules — the AI decides what's worth learning
+
+### ⚙️ Self-Tuning Service Bot
+Deploy a support bot that tunes itself — no DevOps babysitting required.
+
+- Out of the box it works with conservative defaults
+- **Auto calibration** monitors real response quality and adjusts parameters (temperature, expert weights, memory thresholds) based on what actually works
+- When traffic patterns shift (e.g. more technical questions at certain hours), the system adapts without a config push
+- **Knowledge gap analysis** spots missing answers and automatically initiates learning
+- Over weeks the bot silently improves — your only job is to keep it running
+
+---
+
+## Features
+
+### 🧠 Memory System
+Your AI remembers like a human — with layers, decay, and doubt.
+
+| Capability | Description |
+|------------|-------------|
+| **4-layer memory** | Working / Episodic / Semantic / Procedural |
+| **MemoryFusion** | Inverted index + multi-layer retrieval |
+| **Forgetting curve** | Knowledge decays naturally (Ebbinghaus) |
+| **Conflict detection** | Finds contradictions, alerts the user |
+| **Confidence Matrix** | 5-dimensional trust score on every response |
+
+### 🔧 Expert System
+A team of specialized AI experts working together.
+
+| Expert | Role | Community | Pro |
+|--------|------|-----------|-----|
+| LogicExpert | Rule reasoning, contradiction detection | ✅ | ✅ |
+| MemoryExpert | Memory retrieval, fusion search | ✅ | ✅ |
+| EthicsExpert | 15 ethical rules, transparent & auditable | ✅ | ✅ |
+| SafetyExpert | Local keyword + regex safety checks | ✅ | ✅ |
+| CodeReviewExpert | Code style, complexity, secret scanning | ✅ | ✅ |
+| EmotionExpert | Sentiment analysis, empathetic response | ❌ | ✅ |
+| CreativeExpert | Creative writing, content generation | ❌ | ✅ |
+| IntrospectionExpert | Self-reflection, quality audit | ❌ | ✅ |
+| HypothesisEngine | Root cause hypothesis & validation | ❌ | ✅ |
+
+### 📚 Learning System
+
+| Capability | Community | Pro |
+|------------|-----------|-----|
+| Manual learning (API trigger) | ✅ | ✅ |
+| 7×24 auto-learning loop | ❌ | ✅ |
+| Curiosity-driven discovery | ❌ | ✅ |
+| Auto parameter tuning | ❌ | ✅ |
+| Knowledge gap analysis | ❌ | ✅ |
+| Post-validation audit | ❌ | ✅ |
+
+### 🔌 API & Integration
+- **RESTful API** — FastAPI, Swagger docs at `/docs`
+- **SSE streaming** — Real-time token-by-token output
+- **Multi-user auth** — Email/password registration + API Keys
+- **Knowledge base CRUD** — Add, search, update, delete knowledge entries
+- **Session management** — Persistent conversations with history
+
+---
+
+## Architecture
+
+```
+aelvoxim/
+├── src/aelvoxim/
+│   ├── core/         Cognitive engine (belief, metacog, reasoner, judge, DGM-H)
+│   ├── learn/        Learning engine (learner, KB, validator, search, curiosity)
+│   ├── memory/       Memory system (4 layers, fusion, decay, conflict, scoring)
+│   ├── server/       API server (FastAPI, auth, chat pipeline, sessions)
+│   ├── cortex/       Brain cortex (intent routing, scheduler)
+│   ├── experts/      Expert system (orchestrator, 5+ experts, registry)
+│   ├── storage/      Dual storage (SQLite local, PostgreSQL production)
+│   ├── utils/        Helpers (i18n, paths, JSON)
+│   └── edition.py    Edition gating (community/pro config control)
+├── frontend/
+│   └── chatael-v2/   ChatAEL — React + Tailwind chat UI
+├── tests/            130+ test cases
+├── docs/
+├── CONTRIBUTING.md
+├── SECURITY.md
+└── LICENSE (MIT)
+```
+
+---
+
+## Community vs Pro
+
+| Dimension | Community (free, MIT) | Pro (license key) |
+|-----------|----------------------|-------------------|
+| Learning | Manual trigger | 7×24 auto loop |
+| Discovery | User-specified | Curiosity-driven |
+| Tuning | Static defaults | Dynamic auto-tune |
+| Experts | 5 core | 12 total (incl. advanced) |
+| Validation | None | Scheduled auto-scan |
+| Security | Local rules | SentriKit deep engine |
+| License | MIT | License key |
+
+---
+
+## External Dependencies
+
+Only **3 external packages** — everything else is Python standard library.
+
+| Package | Purpose |
+|---------|---------|
+| `bcrypt` | Password hashing |
+| `fastapi` | API framework |
+| `uvicorn` | ASGI server |
+
+---
+
+## Why Aelvoxim?
+
+- **Lightweight** — 3 deps, 34k lines of Python, no Docker required
+- **Self-contained** — SQLite for single-user, PostgreSQL for multi-user
+- **Private by design** — Your data stays on your machine, no telemetry
+- **Dual storage** — SQLite for dev, PostgreSQL for production, same code
+- **Built-in safety** — Ethics rules, safety checks, meta-cognition monitoring
+
+---
+
+## License
+
+MIT License — Copyright (c) 2026 macor24
+
+See [LICENSE](./LICENSE) for details.

aelvoxim-1.0.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=64.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aelvoxim"
+version = "1.0.0"
+description = "Lightweight AI Cognitive Engine Framework — give your AI a memory"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "macor24", email = "macor@gealss.com"},
+]
+keywords = ["ai", "agent", "cognitive-engine", "memory", "self-learning", "framework"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+dependencies = [
+    "bcrypt>=4.0.0",
+    "fastapi>=0.100.0",
+    "uvicorn[standard]>=0.20.0",
+]
+
+[project.optional-dependencies]
+pg = ["psycopg2-binary>=2.9.0"]
+test = ["pytest>=7.0", "httpx>=0.27"]
+dev = ["aelvoxim[pg,test]", "build>=1.0", "twine>=4.0"]
+full = ["aelvoxim[pg]"]
+
+[project.urls]
+Homepage = "https://github.com/macor24/aelvoxim"
+Repository = "https://github.com/macor24/aelvoxim"
+Documentation = "https://github.com/macor24/aelvoxim/tree/master/docs"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+aelvoxim = ["**/*.html"]
+
+[project.scripts]
+aelvoxim = "aelvoxim.__main__:main"
+aelvoxim-admin = "aelvoxim.admin:main"

aelvoxim-1.0.0/setup.cfg

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

aelvoxim-1.0.0/src/aelvoxim/__init__.py

@@ -0,0 +1,11 @@
+"""aelvoxim.init — Aelvoxim MetaCore
+
+A zero-dependency, pure-stdlib, self-evolving AI Agent framework.
+"""
+
+from __future__ import annotations
+
+import os
+
+_EDITION = os.environ.get("METACORE_EDITION", os.environ.get("AELVOXIM_EDITION", "enterprise"))
+__version__ = "1.0.0"

aelvoxim-1.0.0/src/aelvoxim/__main__.py

@@ -0,0 +1,84 @@
+"""aelvoxim.__main__ — CLI entry point
+
+Usage:
+    python -m metacore --lang en
+    python -m metacore learn add "Topic name"
+    python -m metacore status
+"""
+
+import sys
+import argparse
+
+from .utils.i18n import set_lang, _
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        description="MetaCore — Self-evolving AI Agent framework",
+    )
+    parser.add_argument("--lang", default="en", help="Interface language (en/zh)")
+    sub = parser.add_subparsers(dest="command")
+
+    # learn
+    learn_p = sub.add_parser("learn", help="Manage learning")
+    learn_sub = learn_p.add_subparsers(dest="learn_cmd")
+    add_p = learn_sub.add_parser("add", help="Add a learning direction")
+    add_p.add_argument("topic", help="Topic to learn")
+    learn_sub.add_parser("start", help="Start learning loop")
+    learn_sub.add_parser("stop", help="Stop learning loop")
+    learn_sub.add_parser("status", help="Show learning status")
+
+    # ui
+    ui_p = sub.add_parser("ui", help="Start read-only dashboard")
+    ui_p.add_argument("--port", type=int, default=9700, help="Dashboard port (default: 9700)")
+
+    # status
+    sub.add_parser("status", help="Show system status")
+
+    args = parser.parse_args(argv)
+    set_lang(args.lang)
+
+    if args.command == "ui":
+        print("Dashboard merged into 9701 at /v1/admin/panel")
+
+    if args.command == "learn":
+        cmd = getattr(args, "learn_cmd", None)
+        if cmd == "add":
+            from .learn.learner import get_learner
+            learner = get_learner()
+            added = learner.add_direction(args.topic)
+            print(f"Direction '{args.topic}' {'added' if added else 'already exists'}")
+        elif cmd == "start":
+            from .learn.learner import get_learner
+            get_learner().start()
+            print(_("started"))
+        elif cmd == "stop":
+            from .learn.learner import get_learner
+            get_learner().stop()
+            print(_("stopped"))
+        elif cmd == "status":
+            from .learn.learner import get_learner
+            st = get_learner().get_status()
+            print(json.dumps(st, indent=2, ensure_ascii=False))
+            # Cold-start suggestion
+            from .utils import LEARNER_CONFIG
+            try:
+                cfg = json.loads(LEARNER_CONFIG.read_text())
+            except Exception:
+                cfg = []
+            if not cfg:
+                print("---")
+                print("No learning directions yet. Try:")
+                print('  metacore learn add "FastAPI async optimization patterns"')
+                print('  metacore learn add "Python threading safety patterns"')
+                print('  metacore learn add "Database index optimization SQLite"')
+    elif args.command == "status":
+        from .learn.learner import get_learner
+        st = get_learner().get_status()
+        print(json.dumps(st, indent=2, ensure_ascii=False))
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()