vietnamese-writing-intelligence 0.2.1__tar.gz

vietnamese_writing_intelligence-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - 'feat/**'
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Test (${{ matrix.os }} - Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev,mcp]"
+
+      - name: Run Ruff linter
+        run: |
+          ruff check .
+
+      - name: Run Pytest test suite
+        run: |
+          pytest -v
+
+      - name: Build Wheel & Source Distribution
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Isolated Wheel Smoke Test
+        shell: bash
+        run: |
+          # Cài đặt file wheel vừa đóng gói vào môi trường
+          python -m pip install --force-reinstall dist/*.whl
+
+          # Chuyển ra thư mục tạm bên ngoài repo để đảm bảo kiểm tra độc lập
+          mkdir -p /tmp/smoke_test || mkdir -p ./smoke_test
+          cd /tmp/smoke_test 2>/dev/null || cd ./smoke_test
+
+          # Kiểm tra entrypoint CLI và tài nguyên schemas / benchmark nhúng trong wheel
+          vn-intel --help
+          vn-intel benchmark --json

vietnamese_writing_intelligence-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    name: Build & Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/vietnamese-writing-intelligence
+    permissions:
+      id-token: write # Bắt buộc cho Trusted Publishing (OIDC)
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tool
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build sdist and wheel
+        run: |
+          python -m build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true

vietnamese_writing_intelligence-0.2.1/.gitignore

@@ -0,0 +1,44 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE & Editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing & Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS specific
+.DS_Store
+Thumbs.db

vietnamese_writing_intelligence-0.2.1/LICENSE

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

vietnamese_writing_intelligence-0.2.1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: vietnamese-writing-intelligence
+Version: 0.2.1
+Summary: An agentic framework for native Vietnamese writing, voice profiling, and fact-preserving text refinement.
+Author-email: Van-Truong Dang <vantruong-dang@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-skills,humanizer,llm,mcp,nlp,vietnamese,writing
+Requires-Python: >=3.11
+Requires-Dist: jsonschema>=4.20.0
+Requires-Dist: vietnamese-writing-skills<0.6.0,>=0.4.6
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# 🇻🇳 Vietnamese Writing Intelligence — Orchestration Foundation (v0.1.0)
+
+> **An extensible framework for Vietnamese writing intelligence, currently providing orchestration, structured validation, and an evolving roadmap toward native language understanding and generation.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python Version](https://img.shields.io/badge/Python-3.11%20to%203.14%2B-green.svg)](pyproject.toml)
+[![Architecture](https://img.shields.io/badge/Architecture-LLM%20Brain%20%2B%20NLP%20Sensors-purple.svg)](#-triết-lý-kiến-trúc-llm-brain--deterministic-sensors)
+
+---
+
+## 📌 Triết lý Kiến trúc: "LLM Brain + Deterministic Sensors"
+
+Dự án không tìm cách biến mọi đặc trưng ngôn ngữ học thành các luật cứng (hard rules) cực đoan. Chúng tôi áp dụng mô hình lai (Neuro-symbolic approach):
+1. **LLM làm bộ não (Brain):** Xử lý ngữ cảnh, lập dàn ý, tư duy cấu trúc Đề – Thuyết và sinh bản thảo tự nhiên.
+2. **NLP truyền thống làm cảm biến (Sensors):** Đo lường bề mặt, phân tích ranh giới từ, phát hiện sáo ngữ và kiểm toán ngữ âm/nhịp điệu mà không can thiệp thô bạo.
+3. **JSON Schema & Anchor Guardrails:** Rào chắn dữ liệu (`immutable_anchors`) ngăn chặn việc làm biến dạng số liệu, tên riêng hoặc đảo ngược chuỗi nhân quả kỹ thuật khi biên tập.
+
+---
+
+## 🚀 Tính năng cốt lõi trong v0.1.0
+
+- **State Machine 4 trạng thái:** Phân định rõ ràng giữa `clean_rewrite`, `no_change`, `review_comment`, và `needs_author_decision`.
+- **Anti-Corruption Adapter (`upstream_adapter.py`):** Tách biệt và bảo vệ hệ thống khỏi sự thay đổi của upstream linter (`vietnamese-writing-skills`), tự động kích hoạt bộ quy tắc nội tại khi chạy độc lập, đồng thời che chắn code fences, URLs, emails để chống báo lỗi giả.
+- **Fail-Fast Schema Validation:** Kiểm định cấu trúc `VoiceProfile` và `DraftManifest` theo chuẩn JSON Schema Draft 2020-12 ngay tại thời điểm khởi tạo.
+- **Anchor-based Semantic Integrity Checks:** Đối soát các điểm neo dữ kiện bất biến (`immutable_anchors`) với cơ chế chuẩn hóa khoảng trắng, Unicode tổ hợp (NFC) và ranh giới từ, loại bỏ tình trạng báo lỗi giả và bảo toàn số liệu/thực thể.
+
+---
+
+## 🗺 Lộ trình Phát triển 2 Trục Song hành (Roadmap to v1.0)
+
+```
+        Trục A: Năng lực Ngôn ngữ                       Trục B: Năng lực Tạo sinh
+ (Deterministic NLP & Linguistic Sensors)           (Agentic Drafting & Voice Profiling)
+                   │                                                  │
+v0.1 (Current)     ├─ Schema Validation & Regex ACL Adapter           ├─ Basic Orchestrator & CLI
+                   │                                                  │
+v0.2               ├─ Segmentation, Normalization & Context Rules     ├─ Native Drafter (Workflow Planner)
+                   │                                                  │
+v0.3               ├─ Register & Dialect Modeling (Bắc/Trung/Nam)     ├─ Voice Profiler & Feature Extraction
+                   │                                                  │
+v0.4               ├─ Prosody Analyzer (Nhịp điệu & Bằng - Trắc)      ├─ Deep Semantic & Causal Audit
+                   │                                                  │
+                   └─────────────────────────┬────────────────────────┘
+                                             ▼
+v1.0                         Integrated Vietnamese Writing Agent
+```
+
+---
+
+## 💻 Cài đặt & Sử dụng
+
+### 1. Cài đặt môi trường phát triển (Python 3.11 – 3.14+)
+```bash
+git clone https://github.com/vantruong-dang/vietnamese-writing-intelligence.git
+cd vietnamese-writing-intelligence
+python -m pip install -e ".[dev]"
+```
+
+### 2. Chạy bộ kiểm thử (Unit Tests)
+```bash
+pytest -v
+```
+
+### 3. Sử dụng qua dòng lệnh (CLI)
+```bash
+vn-intel audit <file_van_ban.txt> --profile profiles/systems_architect.json --manifest <file_manifest.json>
+```
+
+---
+
+## 📚 Tham khảo, Nguồn cảm hứng & Ghi công (Acknowledgments)
+
+Dự án **Vietnamese Writing Intelligence** được xây dựng trên sự kế thừa, chắt lọc triết lý và kiến trúc từ các dự án nguồn mở tiên phong:
+
+### 1. Dự án Thượng nguồn Trực tiếp (Upstream & Linguistic Baseline)
+* **[longhang2004/vietnamese-humanizer](https://github.com/longhang2004/vietnamese-humanizer)** (Sản phẩm: *Vietnamese Writing Skills* / PyPI: `vietnamese-writing-skills`) của tác giả Hàng Nhựt Long (@longhang2004) và Lê Ngọc Phương Thư:
+  - *Kế thừa & tích hợp:* State Machine 4 chế độ đầu ra (`clean_rewrite`, `no_change`, `review_comment`, `needs_author_decision`), triết lý bảo toàn dữ kiện ngữ nghĩa (Semantic Preservation), và taxonomy phân loại lỗi bề mặt tiếng Việt.
+
+### 2. Chuẩn mực Agent Skills & Khử văn phong AI (Agentic & De-AI Paradigms)
+* **[anthropics/skills](https://github.com/anthropics/skills):** Cấu trúc đặc tả Agent Skill chuẩn hóa (`SKILL.md`) với Metadata YAML frontmatter và cơ chế phân tách Mode vận hành.
+* **[blader/humanizer](https://github.com/blader/humanizer):** Hệ thống 25+ negative patterns nhận diện dấu vân tay máy tính của RLHF và quy trình tự phê bình (Self-Critique Loop).
+* **[danielmiessler/fabric](https://github.com/danielmiessler/fabric):** Triết lý module hóa Unix cho prompt/pattern (`humanize`, `improve_writing`).
+* **[JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman):** Kỹ thuật nén mật độ thông tin cao, cắt bỏ từ đệm và triệt tiêu đại từ nhân xưng thừa thãi.
+* **[obra/superpowers](https://github.com/obra/superpowers):** Cơ chế kiểm định ngầm nội bộ (Internal Verification Gate) trước khi trả kết quả.
+* **[ComposioHQ/awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills):** Tuyển tập kiến trúc kỹ năng và phương pháp phân lập ngữ vực (Persona Engineering).
+
+### 3. Hệ sinh thái Xử lý Ngôn ngữ Tự nhiên Tiếng Việt (Vietnamese NLP Ecosystem)
+Dự án tham chiếu các nghiên cứu và công cụ nền tảng cho Roadmap từ v0.2:
+* **[Underthesea](https://github.com/undertheseanlp/underthesea):** Hệ thống NLP tiếng Việt phục vụ phân tích hình thái, tách từ (Word Segmentation) và gán nhãn từ loại (POS Tagging).
+* **[VnCoreNLP](https://github.com/vncorenlp/VnCoreNLP):** Bộ công cụ xử lý ngôn ngữ tự nhiên tiếng Việt chuẩn học thuật (tách từ, gán nhãn, phân tích cú pháp phụ thuộc).
+* **[PyVi](https://github.com/trungngv/pyvi):** Thư viện Python nhẹ cho tác vụ phân đoạn từ và nhận diện thực thể tiếng Việt.
+
+---
+
+## 📄 Bản quyền (License)
+
+Dự án được phân phối dưới giấy phép **[MIT License](LICENSE)**.

vietnamese_writing_intelligence-0.2.1/README.md

@@ -0,0 +1,97 @@
+# 🇻🇳 Vietnamese Writing Intelligence — Orchestration Foundation (v0.1.0)
+
+> **An extensible framework for Vietnamese writing intelligence, currently providing orchestration, structured validation, and an evolving roadmap toward native language understanding and generation.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python Version](https://img.shields.io/badge/Python-3.11%20to%203.14%2B-green.svg)](pyproject.toml)
+[![Architecture](https://img.shields.io/badge/Architecture-LLM%20Brain%20%2B%20NLP%20Sensors-purple.svg)](#-triết-lý-kiến-trúc-llm-brain--deterministic-sensors)
+
+---
+
+## 📌 Triết lý Kiến trúc: "LLM Brain + Deterministic Sensors"
+
+Dự án không tìm cách biến mọi đặc trưng ngôn ngữ học thành các luật cứng (hard rules) cực đoan. Chúng tôi áp dụng mô hình lai (Neuro-symbolic approach):
+1. **LLM làm bộ não (Brain):** Xử lý ngữ cảnh, lập dàn ý, tư duy cấu trúc Đề – Thuyết và sinh bản thảo tự nhiên.
+2. **NLP truyền thống làm cảm biến (Sensors):** Đo lường bề mặt, phân tích ranh giới từ, phát hiện sáo ngữ và kiểm toán ngữ âm/nhịp điệu mà không can thiệp thô bạo.
+3. **JSON Schema & Anchor Guardrails:** Rào chắn dữ liệu (`immutable_anchors`) ngăn chặn việc làm biến dạng số liệu, tên riêng hoặc đảo ngược chuỗi nhân quả kỹ thuật khi biên tập.
+
+---
+
+## 🚀 Tính năng cốt lõi trong v0.1.0
+
+- **State Machine 4 trạng thái:** Phân định rõ ràng giữa `clean_rewrite`, `no_change`, `review_comment`, và `needs_author_decision`.
+- **Anti-Corruption Adapter (`upstream_adapter.py`):** Tách biệt và bảo vệ hệ thống khỏi sự thay đổi của upstream linter (`vietnamese-writing-skills`), tự động kích hoạt bộ quy tắc nội tại khi chạy độc lập, đồng thời che chắn code fences, URLs, emails để chống báo lỗi giả.
+- **Fail-Fast Schema Validation:** Kiểm định cấu trúc `VoiceProfile` và `DraftManifest` theo chuẩn JSON Schema Draft 2020-12 ngay tại thời điểm khởi tạo.
+- **Anchor-based Semantic Integrity Checks:** Đối soát các điểm neo dữ kiện bất biến (`immutable_anchors`) với cơ chế chuẩn hóa khoảng trắng, Unicode tổ hợp (NFC) và ranh giới từ, loại bỏ tình trạng báo lỗi giả và bảo toàn số liệu/thực thể.
+
+---
+
+## 🗺 Lộ trình Phát triển 2 Trục Song hành (Roadmap to v1.0)
+
+```
+        Trục A: Năng lực Ngôn ngữ                       Trục B: Năng lực Tạo sinh
+ (Deterministic NLP & Linguistic Sensors)           (Agentic Drafting & Voice Profiling)
+                   │                                                  │
+v0.1 (Current)     ├─ Schema Validation & Regex ACL Adapter           ├─ Basic Orchestrator & CLI
+                   │                                                  │
+v0.2               ├─ Segmentation, Normalization & Context Rules     ├─ Native Drafter (Workflow Planner)
+                   │                                                  │
+v0.3               ├─ Register & Dialect Modeling (Bắc/Trung/Nam)     ├─ Voice Profiler & Feature Extraction
+                   │                                                  │
+v0.4               ├─ Prosody Analyzer (Nhịp điệu & Bằng - Trắc)      ├─ Deep Semantic & Causal Audit
+                   │                                                  │
+                   └─────────────────────────┬────────────────────────┘
+                                             ▼
+v1.0                         Integrated Vietnamese Writing Agent
+```
+
+---
+
+## 💻 Cài đặt & Sử dụng
+
+### 1. Cài đặt môi trường phát triển (Python 3.11 – 3.14+)
+```bash
+git clone https://github.com/vantruong-dang/vietnamese-writing-intelligence.git
+cd vietnamese-writing-intelligence
+python -m pip install -e ".[dev]"
+```
+
+### 2. Chạy bộ kiểm thử (Unit Tests)
+```bash
+pytest -v
+```
+
+### 3. Sử dụng qua dòng lệnh (CLI)
+```bash
+vn-intel audit <file_van_ban.txt> --profile profiles/systems_architect.json --manifest <file_manifest.json>
+```
+
+---
+
+## 📚 Tham khảo, Nguồn cảm hứng & Ghi công (Acknowledgments)
+
+Dự án **Vietnamese Writing Intelligence** được xây dựng trên sự kế thừa, chắt lọc triết lý và kiến trúc từ các dự án nguồn mở tiên phong:
+
+### 1. Dự án Thượng nguồn Trực tiếp (Upstream & Linguistic Baseline)
+* **[longhang2004/vietnamese-humanizer](https://github.com/longhang2004/vietnamese-humanizer)** (Sản phẩm: *Vietnamese Writing Skills* / PyPI: `vietnamese-writing-skills`) của tác giả Hàng Nhựt Long (@longhang2004) và Lê Ngọc Phương Thư:
+  - *Kế thừa & tích hợp:* State Machine 4 chế độ đầu ra (`clean_rewrite`, `no_change`, `review_comment`, `needs_author_decision`), triết lý bảo toàn dữ kiện ngữ nghĩa (Semantic Preservation), và taxonomy phân loại lỗi bề mặt tiếng Việt.
+
+### 2. Chuẩn mực Agent Skills & Khử văn phong AI (Agentic & De-AI Paradigms)
+* **[anthropics/skills](https://github.com/anthropics/skills):** Cấu trúc đặc tả Agent Skill chuẩn hóa (`SKILL.md`) với Metadata YAML frontmatter và cơ chế phân tách Mode vận hành.
+* **[blader/humanizer](https://github.com/blader/humanizer):** Hệ thống 25+ negative patterns nhận diện dấu vân tay máy tính của RLHF và quy trình tự phê bình (Self-Critique Loop).
+* **[danielmiessler/fabric](https://github.com/danielmiessler/fabric):** Triết lý module hóa Unix cho prompt/pattern (`humanize`, `improve_writing`).
+* **[JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman):** Kỹ thuật nén mật độ thông tin cao, cắt bỏ từ đệm và triệt tiêu đại từ nhân xưng thừa thãi.
+* **[obra/superpowers](https://github.com/obra/superpowers):** Cơ chế kiểm định ngầm nội bộ (Internal Verification Gate) trước khi trả kết quả.
+* **[ComposioHQ/awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills):** Tuyển tập kiến trúc kỹ năng và phương pháp phân lập ngữ vực (Persona Engineering).
+
+### 3. Hệ sinh thái Xử lý Ngôn ngữ Tự nhiên Tiếng Việt (Vietnamese NLP Ecosystem)
+Dự án tham chiếu các nghiên cứu và công cụ nền tảng cho Roadmap từ v0.2:
+* **[Underthesea](https://github.com/undertheseanlp/underthesea):** Hệ thống NLP tiếng Việt phục vụ phân tích hình thái, tách từ (Word Segmentation) và gán nhãn từ loại (POS Tagging).
+* **[VnCoreNLP](https://github.com/vncorenlp/VnCoreNLP):** Bộ công cụ xử lý ngôn ngữ tự nhiên tiếng Việt chuẩn học thuật (tách từ, gán nhãn, phân tích cú pháp phụ thuộc).
+* **[PyVi](https://github.com/trungngv/pyvi):** Thư viện Python nhẹ cho tác vụ phân đoạn từ và nhận diện thực thể tiếng Việt.
+
+---
+
+## 📄 Bản quyền (License)
+
+Dự án được phân phối dưới giấy phép **[MIT License](LICENSE)**.

vietnamese_writing_intelligence-0.2.1/docs/KNOWLEDGE_ARCHITECTURE_MAP.md

@@ -0,0 +1,80 @@
+# Knowledge-to-Architecture Map (v0.2.0)
+*Cơ chế chuyển hóa tri thức từ 7 Repository nguồn mở và 11 Tiên đề Ngôn ngữ học tiếng Việt thành các thành phần kiến trúc có thể đo lường.*
+
+---
+
+## 📌 Tổng quan Chiến lược
+
+Dự án **Vietnamese Writing Intelligence** không được định vị như một bản nâng cấp linter hay một lớp wrapper đơn giản quanh LLM. Mục tiêu của dự án là xây dựng một **nền tảng hiểu, tạo sinh, phân tích và biên tập tiếng Việt có nhận thức sâu sắc về ngôn ngữ, ngữ cảnh, thể loại và giọng văn**.
+
+Mọi thiết kế kỹ thuật đều tuân thủ nguyên tắc phân định 3 cấp độ:
+1. **Đã tham khảo (Referenced):** Tiếp thu ý tưởng, triết lý thiết kế.
+2. **Đã chuyển hóa thành thiết kế (Architected):** Cụ thể hóa thành Data Contracts, Schema, Interfaces và State Machine.
+3. **Đã triển khai & kiểm chứng (Implemented & Validated):** Có mã nguồn thực thi, có unit tests và benchmark định lượng độc lập.
+
+---
+
+## 🗺 Phần I: Ma trận Chuyển hóa từ 7 Repository Mã nguồn Mở
+
+| Repository Nguồn | Nguyên lý / Tri thức cốt lõi | Module tiếp nhận trong V3 | Cơ chế Kỹ thuật (Technical Mechanism) | Chỉ số Kiểm chứng (Evaluation Metric) |
+| :--- | :--- | :--- | :--- | :--- |
+| **[longhang2004/vietnamese-humanizer](https://github.com/longhang2004/vietnamese-humanizer)** | **State Machine & Preservation Sheet** | `orchestrator.py` & `validators.py` | 4 trạng thái quyết định (`clean_rewrite`, `no_change`, `review_comment`, `needs_author_decision`); cơ chế che chắn code block/URL/email (`mask_protected`). | Tỷ lệ can thiệp không cần thiết (Unnecessary Rewrite Rate $\le 5\%$). |
+| **[anthropics/skills](https://github.com/anthropics/skills)** | **Declarative Agent Specification** | `skills/*/SKILL.md` | Định dạng chuẩn YAML Frontmatter, phân lập ranh giới `Trigger When` vs `Do Not Use When`, chuẩn hóa Input/Output context. | Khả năng tương thích parser với Claude Code CLI / Cursor rules (100% Valid YAML & Specs). |
+| **[blader/humanizer](https://github.com/blader/humanizer)** | **Negative Patterns & Critique Loop** | `linguistics/context_rules.py` & `drafting/` | Quét dấu vân tay AI (Perplexity thấp, triadic balance) + quy trình 2-Pass: Sinh bản thảo tự do $\rightarrow$ Tự phản biện độc lập. | Giảm tỷ lệ sáo ngữ AI (AI Cliche Reduction Rate $\ge 90\%$). |
+| **[danielmiessler/fabric](https://github.com/danielmiessler/fabric)** | **Unix Philosophy for AI Patterns** | `drafting/planner.py` | Chia nhỏ tác vụ viết thành các pattern đơn nhiệm (Single-purpose patterns): trích xuất luận điểm, dàn ý Đề-Thuyết, biên tập vi mô. | Tỷ lệ hoàn thành tác vụ chuyên biệt (Task Precision) không bị trôi ngữ cảnh. |
+| **[JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman)** | **Information Density & Pruning** | `linguistics/phrase_analysis.py` | Cắt tỉa hư từ rỗng, triệt tiêu đại từ thừa (*nó, điều này*), tối đa hóa tỷ lệ Động từ/Danh từ thực (Verb-to-Noun signal). | Mật độ thông tin (Token-to-Fact Ratio: giảm số từ thừa mà giữ nguyên số dữ kiện). |
+| **[obra/superpowers](https://github.com/obra/superpowers)** | **Test-First & Verification Gates** | `tests/` & `validation/semantic_audit.py` | Kiểm toán độc lập trước khi trả về kết quả; không tin tưởng đầu ra LLM nếu chưa vượt qua bài test dữ kiện bất biến. | Tỷ lệ rò rỉ dữ kiện sai (Hallucination Escape Rate $= 0\%$). |
+| **[ComposioHQ/awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills)** | **Persona & Register Engineering** | `schemas/voice-profile.schema.json` | Phân lập rõ ràng giữa Ngữ vực (Register), Ngữ điệu (Tone) và Vai vế giao tiếp (Relationship) thay vì gộp chung vào một prompt mơ hồ. | Độ nhất quán văn phong giữa các phân đoạn (Cross-paragraph Tone Consistency $\ge 95\%$). |
+
+---
+
+## 🇻🇳 Phần II: Ma trận Chuyển hóa từ 11 Tiên đề Ngôn ngữ học Tiếng Việt
+
+*Nguồn cảm hứng học thuật trực tiếp từ khảo cứu của cố GS. **Cao Xuân Hạo** (*Tiếng Việt Văn Việt Người Việt*) và học giả **Nguyễn Hiến Lê** (*Cổ văn Trung Quốc*).*
+
+```
+                                 HỆ THỐNG NGÔN NGỮ HỌC TIẾNG VIỆT
+                                                │
+         ┌────────────────────────┬─────────────┴────────────┬────────────────────────┐
+         ▼                        ▼                          ▼                        ▼
+[1. Ngữ dụng & Cấu trúc]   [2. Cú pháp & Từ loại]     [3. Ngữ âm & Nhịp điệu]   [4. Ngữ vực & Xã hội]
+ - Cấu trúc Đề – Thuyết     - Danh hóa có điều kiện    - Phối thanh Bằng - Trắc  - Ma trận Xưng hô Thân tộc
+ - Khung đề vs Chủ đề       - Động từ hóa hành động    - Nhịp ngắt Tiểu đối      - Phân lập Ngữ vực & Phương ngữ
+ - Tỉnh lược Chủ ngữ        - Hiện thực vs Giả định    - Tiếng & Danh từ đơn vị  - Bẫy Trùng ngữ vs Ngoại lệ
+```
+
+| Tiên đề Ngôn ngữ học | Bản chất Ngôn ngữ bản địa | Sai lầm của AI/Linter thông thường | Chuyển hóa Kỹ thuật vào Kiến trúc V3 | Phương pháp Kiểm chứng (Validation) |
+| :--- | :--- | :--- | :--- | :--- |
+| **1. Cấu trúc Đề – Thuyết (Topic – Comment)** | Tiếng Việt là ngôn ngữ thiên về Chủ đề (Topic-prominent). Đưa khung cảnh/đối tượng làm tiền đề (Đề), phán đoán theo sau (Thuyết). | Ép câu văn vào cấu trúc Chủ ngữ – Động từ (SVO) ngô nghê dịch từ tiếng Anh. | `drafting/planner.py` tạo `TopicCommentPlan`: bắt buộc xác định rõ "Khung cảnh/Chủ đề" trước khi gán "Vị ngữ/Hành động". | Cặp đối chứng: Câu SVO gượng ép vs Câu Đề-Thuyết tự nhiên (Human Rating). |
+| **2. Tỉnh lược Chủ ngữ (Zero Anaphora)** | Tiếng Việt định vị chủ thể qua ngữ cảnh diễn ngôn. Khi chủ đề đã rõ, câu hoàn toàn không cần đại từ nhân xưng. | Liên tục chèn *"nó", "chúng ta", "họ", "điều này"* vào đầu mỗi câu văn. | `linguistics/phrase_analysis.py` phát hiện đại từ thừa sau dấu chấm nếu ngữ cảnh không đổi chủ thể; tự động gợi ý lược bỏ. | Tỷ lệ loại bỏ đại từ rác mà không gây mơ hồ ngữ nghĩa (Ambiguity Check). |
+| **3. Cơ chế Danh hóa có điều kiện (Nominalization)** | Hư từ *sự/việc* đứng trước Động từ chỉ là một dạng danh hóa; nhiều trường hợp là danh từ thực (*việc này*) hoặc thành ngữ cố định (*sự tích*). | Phạt mù quáng mọi sự xuất hiện của `việc/sự + V`. | `linguistics/context_rules.py` phân tích 3 tầng: (1) Cụm cố định $\rightarrow$ Bỏ qua; (2) Chủ ngữ mệnh đề $\rightarrow$ Chấp nhận; (3) Đi sau động từ hành động $\rightarrow$ Cảnh báo. | Precision / Recall trên tập dữ liệu benchmark danh từ hóa. |
+| **4. Hư từ & Tình thái từ (Discourse Particles)** | Hệ thống tình thái từ cuối câu (*nhỉ, cơ, chứ, đa, nghen*) và liên từ khẩu ngữ (*khổ nỗi, hóa ra*) định hình quan hệ và cảm xúc. | Nhồi nhét bừa bãi để giả làm "văn người" (gây cảm giác blogger gồng), hoặc cấm sạch khiến câu văn chết cứng. | `voice-profile.schema.json` quản lý cờ `colloquial_particles_allowed` gắn chặt với `register`. Phân định rõ văn bản học thuật (cấm) vs đàm thoại (cho phép). | Kiểm tra tính phù hợp ngữ vực (Register Compliance Rate). |
+| **5. Cân bằng Bằng – Trắc & Nhịp điệu (Prosody)** | Văn xuôi tự nhiên của người Việt có tính nhạc ngầm: nhịp chẵn (2/2, 4/4) và phân bổ thanh điệu (Bằng: ngang/huyền; Trắc: sắc/hỏi/ngã/nặng). | Đánh giá văn phong chỉ qua số đếm từ (Word count) hoặc ép câu ngắn cụt lủn. | `linguistics/prosody.py` (chỉ đóng vai trò Sensor phân tích, không phạt cứng): cảnh báo chuỗi âm trắc gắt gỏng hoặc nhịp câu mất cân đối ở đuôi đoạn. | So sánh phân phối thanh điệu với Pre-LLM Gold Corpus (Distribution Drift). |
+| **6. Cấu trúc Hán-Việt vs Thuần Việt** | Từ Hán-Việt mang tính trừu tượng, trang trọng, cô đọng; từ thuần Việt mang tính gợi hình, đời thường, cụ thể. | Trộn lẫn từ Hán-Việt cổ với khẩu ngữ hiện đại trong cùng một đoạn văn. | `linguistics/pos.py` & `lexical_audit.py` đo mật độ Hán-Việt (`sino_vietnamese_density`) theo 3 mức: *bình dân, cân bằng, học thuật cao*. | Tỷ lệ lệch tông từ vựng (Lexical Tone Drift $\le 2\%$). |
+| **7. Phân tầng Ngữ vực (Registers) độc lập với Phương ngữ** | Một nhà khoa học miền Nam viết báo cáo khoa học vẫn dùng từ toàn dân trang trọng; người miền Bắc viết kịch vẫn dùng phương ngữ Nam Bộ. | Đồng nhất "phương ngữ" với "từ sai chuẩn" hoặc đánh đồng ngữ vực thân mật với phương ngữ. | Tách rời 2 trục trong schema: `register` (học thuật, hành chính, thân mật...) và `dialect_bias` (Bắc, Trung, Nam, Toàn dân). | Ma trận kiểm thử chéo 4 Ngữ vực $\times$ 3 Vùng miền. |
+| **8. Quan hệ Xưng hô Thân tộc hóa (Kinship Honorifics)** | Tiếng Việt không có đại từ trung tính tuyệt đối như *You/I*; đại từ phản ánh vị thế xã hội, tuổi tác, sự tôn trọng và khoảng cách quyền lực. | AI dùng lộn xộn *"bạn - tôi"*, *"chúng tôi - chúng ta"* (bao gồm hay loại trừ người nghe). | `validation/register_audit.py` kiểm tra tính nhất quán của ngôi xưng: cấm lẫn lộn giữa *chúng tôi* (exclusive) và *chúng ta* (inclusive). | Consistency Check trên toàn văn bản (Pronoun Drift $= 0$). |
+| **9. Phân định Khung đề (Range Topic) vs. Chủ đề (Instance Topic) & Triệt tiêu Câu khuyết tật** | Khung đề giới hạn phạm vi không gian/thời gian (*Trong tình hình này*), Chủ đề là thực thể trung tâm. Không được biến Khung đề thành chủ ngữ cho vị từ hành động. | AI và báo chí tạo câu khuyết tật: `*Trong tình hình này đòi hỏi...`, `*Bằng những hình tượng sắc nét đã cho thấy...`. | `linguistics/phrase_analysis.py` phát hiện Giới ngữ mở đầu đi kèm vị từ ngoại động thiếu Chủ đề thực sự; tự động cảnh báo hoặc tái cấu trúc chuẩn bản địa. | Tỷ lệ phát hiện câu khuyết tật không vị ngữ (Crippled Sentence Detection $\ge 90\%$). |
+| **10. Phạm trù Hiện thực vs. Giả định (`Tuy` vs. `Dù`) & Khoảng cách Thời gian** | `Tuy / Mặc dầu` chỉ dùng cho sự việc đã/đang có thật. `Dù / Cho dù` chỉ dùng cho sự thể giả định, chưa xảy ra. Khoảng cách thời gian ưu tiên Khung đề (*Ba ngày nữa John về*). | AI lẫn lộn: `*Ngày mai tuy mưa to tôi vẫn đến` (sai logic); dịch thô: `*John sẽ về trong ba ngày`. | `linguistics/context_rules.py` phân tích tính giả định qua trạng ngữ thời gian để phát hiện dùng sai `dù` vs `tuy`; chuyển đổi cấu trúc thời gian thô sang Khung đề. | Test cases phân biệt `Dù` vs `Tuy` đạt độ chính xác 100%. |
+| **11. Thực thể tính của Danh từ đơn vị (Unitizers) & Kiểm soát Trùng ngữ (Pleonasm)** | *Cái, con, bức, tấm* là Danh từ đơn vị mang đầy đủ vật tính (reity). Trùng ngữ logic cần loại bỏ, nhưng phải miễn trừ cho ngữ nghĩa thân tộc bản địa (*anh trai, chị gái* = ruột thịt). | Phạt nhầm danh từ đơn vị độc lập (*Tôi ăn hai cái*); hoặc phạt nhầm danh từ thân tộc ruột thịt (*anh trai, chị gái*). | `validation/lexical_audit.py` tích hợp từ điển trùng ngữ logic (`tối ưu nhất`, `nguyên nhân là vì`) đồng thời cấu hình danh sách miễn trừ thân tộc. | False Positive trên danh từ đơn vị và từ thân tộc $= 0\%$. |
+
+---
+
+## 🎯 Phần III: Tiêu chuẩn Nghiệm thu Định lượng cho Sprint v0.2.0
+
+### 1. Cổng Kiểm định Ngôn ngữ (Linguistic Quality Gate - Trục A)
+* **Tập dữ liệu kiểm chuẩn (Benchmark Corpus):** Tạo `tests/data/linguistic_gold_standard.jsonl` gồm **200 câu tiếng Việt** có gán nhãn thủ công (Ground Truth) chia đều cho 4 nhóm:
+  - **Nhóm 1 (50 câu):** Danh từ hóa 3 tầng (*danh từ gốc, chủ ngữ trừu tượng hợp lệ, danh từ hóa sáo rỗng `sự/việc`*).
+  - **Nhóm 2 (50 câu):** Cấu trúc Đề – Thuyết và phát hiện câu khuyết tật Khung đề vs Chủ đề (*"Trong tình hình này đòi hỏi..."*), tác tử phân giới `thì`.
+  - **Nhóm 3 (50 câu):** Hiện thực vs. Giả định (`Tuy` vs `Dù`), khoảng cách thời gian (*"ba ngày nữa"*), bẫy trùng ngữ (`tối ưu nhất` vs miễn trừ `anh trai/chị gái`).
+  - **Nhóm 4 (50 câu):** Bảo vệ thuật ngữ, code block, công thức số liệu và văn biền ngẫu đối xứng tầng bậc (ngữ liệu từ Nguyễn Hiến Lê).
+* **Chỉ số đo lường (Metrics):**
+  - **Context-Rule Precision:** $\ge 85\%$ (không được báo lỗi oan cho câu danh hóa hợp lệ).
+  - **Context-Rule Recall:** $\ge 80\%$ (bắt được các cấu trúc dịch thô sáo rỗng thực sự).
+  - **False Positive trên Code/Thuật ngữ/Danh từ đơn vị:** $0\%$ (nhờ tầng che chắn và từ điển miễn trừ).
+
+### 2. Cổng Kiểm định Tạo sinh (Generative Quality Gate - Trục B)
+* **Bảo toàn dữ kiện (Anchor Preservation):**
+  - Mọi bản nháp sinh ra từ `DraftPlanner` + `BaseLLMProvider` khi chạy qua `SemanticAuditor` phải đạt:
+    $$\text{Metrics Retention} = 100\% \quad \text{và} \quad \text{Domain Terms Retention} = 100\%$$
+* **Không phụ thuộc Vendor (Vendor Agnostic):**
+  - Có thể thay thế liền mạch giữa `MockLLMProvider` (dùng cho CI/CD), `OllamaProvider` (chạy local offline) và `Anthropic/OpenAIProvider` mà không phải sửa code trong `DraftPlanner`.

vietnamese_writing_intelligence-0.2.1/profiles/systems_architect.json

@@ -0,0 +1,19 @@
+{
+  "profile_id": "systems_architect",
+  "version": "1.0.0",
+  "syntactic_signature": {
+    "clause_chaining_style": "hypotactic_causal",
+    "allow_long_sentences": true,
+    "max_sentence_word_budget": 70
+  },
+  "lexical_preferences": {
+    "sino_vietnamese_density": "high_academic_precision",
+    "colloquial_particles_allowed": false,
+    "english_term_retention": "strict_preserve_technical"
+  },
+  "pattern_overrides": {
+    "NOMINALIZATION_HEAVY": {
+      "enforcement": "disabled"
+    }
+  }
+}

vietnamese_writing_intelligence-0.2.1/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vietnamese-writing-intelligence"
+version = "0.2.1"
+description = "An agentic framework for native Vietnamese writing, voice profiling, and fact-preserving text refinement."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Van-Truong Dang", email = "vantruong-dang@users.noreply.github.com" }
+]
+keywords = ["vietnamese", "nlp", "llm", "agent-skills", "writing", "humanizer", "mcp"]
+dependencies = [
+    "jsonschema>=4.20.0",
+    "vietnamese-writing-skills>=0.4.6,<0.6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.4.0",
+    "build>=1.0.0",
+]
+mcp = [
+    "mcp>=1.1.0",
+]
+
+[project.scripts]
+vn-intel = "vn_writing_intel.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vn_writing_intel"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"schemas" = "vn_writing_intel/schemas"
+"tests/data/linguistic_gold_standard.jsonl" = "vn_writing_intel/data/linguistic_gold_standard.jsonl"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4", "RUF"]
+ignore = [
+    "BLE001",  # Cho phép CLI bắt Exception cấp cao để in thông báo thân thiện
+    "E501",    # Cho phép chuỗi văn bản tiếng Việt / regex dài trong dữ liệu và luật
+    "RUF001",  # Cho phép dấu nháy đơn cong (‘ ’) trong module chuẩn hóa dấu câu tiếng Việt
+]
+
+[tool.ruff.lint.isort]
+combine-as-imports = true