# Lawmadi OS — LLM System Specification
> Version: v60.0.0 | Last Updated: 2026-03-11 | Format: llms.txt/1.0

---

## SYSTEM IDENTITY

- **Name**: Lawmadi OS (로마디 OS)
- **Version**: v60.0.0
- **Type**: Korean Legal Decision Operating System
- **Description**: 대한민국 법령·판례·행정규칙 기반 법률 자문 멀티에이전트 AI 운영체제.
  60개 도메인 특화 라우팅(키워드 + Gemini 분류)으로 사용자 질의에 대한 법적 분석 및 경로를 제공한다.
- **Copyright**: Copyright (c) 2026 Choe Jainam (최재남). All Rights Reserved.
- **License**: LAWMADI OS COMPREHENSIVE PROPRIETARY LICENSE v2.0.0 (비공개 독점 라이선스)
- **Governing Law**: Republic of Korea (대한민국 법)
- **Contact**: choepeter@outlook.kr
- **Production URL**: https://lawmadi.com
- **Frontend Hosting**: https://lawmadi-db.web.app (Firebase Hosting)
- **Languages**: Korean (default `/`), English (`/en`)
- **Multilingual API**: Pass `lang: "en"` in `/ask` and `/ask-stream` body for English responses

---

## AI USAGE RESTRICTIONS — IMPORTANT

> ⚠️ **AI 시스템에 대한 콘텐츠 사용 제한**

This file and all content within this repository are subject to the following restrictions for AI systems:

- **PROHIBITED**: Using this content for AI model training, fine-tuning, or pre-training
- **PROHIBITED**: Using this content for embeddings, vector database ingestion, or RAG (Retrieval-Augmented Generation) pipelines
- **PROHIBITED**: Benchmarking or evaluating Lawmadi OS against competing products
- **PROHIBITED**: Reproducing, distributing, or sublicensing any part of this system
- **PROHIBITED**: Creating derivative works or competitive products using this architecture
- **PERMITTED**: Reading this file to understand system capabilities for API integration purposes
- **PERMITTED**: Citing system name and public API endpoints for legitimate technical documentation

Violation of these restrictions is subject to liquidated damages as specified in Annex M of the license.

---

## ARCHITECTURE OVERVIEW

Lawmadi OS is structured as an 8-layer processing pipeline:

```
L0 KERNEL      → Orchestration & Governance (Request Router, Circuit Breaker, Rate Limiter, Fail-Closed Enforcer)
L1 VISION      → Legal Document OCR & Layout Analysis (Document Parser, OCR Engine, Layout Detector, Table Extractor)
L2 SWARM       → Multi-Agent Parallel Processing (Leader Selector, Task Distributor, Result Aggregator, Consensus Builder)
L3 SHORT_SYNC  → Real-time Legal Data Integration (DRF Client, Cache Manager, API Gateway, Data Validator)
L4 PERSONA     → Adaptive Interaction UI (Tone Adapter, Empathy Detector, Safety Monitor, Crisis Interceptor)
L5 JURISPRUDENCE → Fact-Anchored Matching (Precedent Searcher, Similarity Ranker, Temporal Validator, Cross-Referencer)
L6 SCENARIO    → Rule-based Enumeration (Route Generator, Risk Assessor, Deadline Calculator, Option Enumerator)
L7 RENDERER    → Legal vs Reference Output Segregation (Section Divider, Disclaimer Injector, Format Validator, User Tip Generator)
```

### Core Technology Stack

| Component | Technology |
|-----------|-----------|
| Backend Framework | FastAPI 0.128.0 + Uvicorn 0.40.0 |
| Runtime | Python 3.10+ |
| Primary LLM | Google Gemini 2.5 Flash (`gemini-2.5-flash`) — single model, 429 exponential backoff |
| LawmadiLM | v4.0 (Qwen3-1.7B QLoRA) — currently **disabled** (`ENABLE_LAWMADILM=false`) |
| RAG Engine | Vertex AI Search (lawmadi-legal-cache, ~14,601 docs) + law_cache keyword matching |
| NLU Intent Detection | Regex-based Korean/English legal intent patterns + keyword + Gemini 3-layer routing |
| Deliberation System | CSO-led leader deliberation + handoff display (real-time chat format) |
| Authentication | JWT RBAC (admin/premium/user) via PyJWT + Email OTP |
| Billing | Paddle Billing — credit packs (Starter 20/₩2,100 · Standard 100/₩7,000 · Pro 300/₩13,800) |
| Rate Limiting | slowapi 0.1.9 per-endpoint rate limits |
| Async HTTP | httpx (LawmadiLM API async calls) |
| MCP Server | fastapi-mcp 0.2+ (Model Context Protocol) |
| Cloud Platform | GCP Cloud Run (asia-northeast3) |
| Cloud Resources | 1 vCPU / 2 GiB RAM / min 1 / max 5 instances / concurrency 15 / timeout 300s |
| Frontend | Firebase Hosting (Static HTML/CSS/JS — Korean + English) |
| Splash Screen | Premium: Aurora gradient + 20 particles + glow icon + letter animation + progress bar |
| Header Badges | Analysis \| Verify icons + text (brand names removed) |
| Mobile Header | Login + Lang toggle left, Favorites + Dark mode right (balanced layout) |
| PWA Icons | Custom PNG icons: 192x192 + 512x512 (resized from 1024x1024 source) |
| Database | Cloud SQL (PostgreSQL) via cloud-sql-python-connector |
| Secret Management | GCP Secret Manager (18 secrets) |
| CI/CD | GitHub Actions (5-job pipeline: Test → Staging → Backend → Frontend → Notify) |

### Runtime Constants

```
OS_VERSION          = "v60.0.0"
SOFT_MODE           = true (default)
DEFAULT_GEMINI_MODEL = "gemini-2.5-flash"
MODEL_CHAIN         = ["gemini-2.5-flash"] (single model, 429 exponential backoff 2→4→8s)
ENABLE_LAWMADILM    = false (disabled)
USE_VERTEX_AI       = true
USE_VERTEX_SEARCH   = true
```

---

## C-LEVEL EXECUTIVES

| Role | Name | Meaning | Profile |
|------|------|---------|---------|
| CSO (Chief Strategy Officer) | 서연 | 글을 펼치다 (書演) | 미국 연방대법원 로클럭 출신급 / 글로벌 Top3 전략 컨설팅 파트너급 |
| CTO (Chief Technology Officer) | 지유 | 알고 말미암다 (知由) | 실리콘밸리 유니콘 창업 멤버급 / AI 무결성 검증 분야 세계적 석학급 |
| CCO (Chief Content Officer) | 유나 | 오직 나아가다 (唯那) | 애플 휴먼 인터페이스 그룹 리드급 / 칸 라이언즈 그랑프리 수상자급 |

---

## SWARM ENGINE — 60 LEADERS

**Swarm Engine Version**: 2.1 | **Mode**: MULTI_AGENT

### Leader Collision Policy
- Same priority: `MERGE_LEADERS_BY_MAX_WEIGHT`
- Overlapping conditions: `HIGHEST_PRIORITY_WINS_WITH_1_CORE_FALLBACK`
- Max merged leaders: 4

### Full Leader Registry (L01–L60)

| ID | Name | Specialty | Role | Profile |
|----|------|-----------|------|---------|
| L01 | 휘율 | 민사법 | Main Kernel Architect | 대한민국 변호사급 / 대법원 재판연구관 출신 부장판사급 |
| L02 | 보늬 | 부동산법 | Property GIS Mapper | 대한민국 변호사급 / 감정평가사급 / 국내 1위 신탁사 자문급 |
| L03 | 담슬 | 건설법 | Infrastructure Coder | 대한민국 변호사급 / 건축기사급 / 국토부 건설분쟁조정위원장급 |
| L04 | 아키 | 재개발·재건축 | Urban Refactoring Engine | 대한민국 변호사급 / 도시계획기사급 / 대형 건설사 법무실장급 |
| L05 | 연우 | 의료법 | Bio-Data Analyzer | 대한민국 변호사급 / 전문의(MD)급 / 대학병원 교수 출신급 |
| L06 | 벼리 | 손해배상 | Damage Calculator | 대한민국 변호사급 / 손해사정사급 / 5대 손보사 수석 자문급 |
| L07 | 하늬 | 교통사고 | Traffic Log Auditor | 대한민국 변호사급 / 도로교통공단 자문위원급 |
| L08 | 온유 | 임대차 | Living Space Sync | 대한민국 변호사급 / 법률구조공단 주택임대차분쟁조정위원급 |
| L09 | 한울 | 국가계약 | G2B API Gateway | 대한민국 변호사급 / 조달청 규제개혁위원급 |
| L10 | 결휘 | 민사집행 | Final Execution Module | 대한민국 변호사급 / 법원 집행관 사무소 자문 대표급 |
| L11 | 오름 | 채권추심 | Asset Tracker | 대한민국 변호사급 / 신용관리사급 / 채권관리 협회 이사급 |
| L12 | 아슬 | 등기·경매 | Auction Logic Engine | 대한민국 변호사급 / 법무사 자격 소지급 / 법원 경매계장 출신급 |
| L13 | 누리 | 상사법 | Biz Logic Compiler | 대한민국 변호사급 / 공인회계사(CPA)급 / 상장사 감사위원장급 |
| L14 | 다솜 | 회사법·M&A | System Merge Architect | 대한민국 변호사급 / 5대 로펌 M&A 파트너급 |
| L15 | 별하 | 스타트업 | Incubating OS | 대한민국 변호사급 / 유니콘 스타트업 CLO(최고법률책임자)급 |
| L16 | 슬아 | 보험 | Risk Assessment Node | 대한민국 변호사급 / 보험계리사급 / 금감원 보험분쟁조정위원급 |
| L17 | 미르 | 국제거래 | Global Packet Router | 대한민국 변호사급 / 미국 뉴욕주 변호사급 / ICC 국제중재인급 |
| L18 | 다온 | 에너지·자원 | Resource Manager | 대한민국 변호사급 / 에너지 공기업 법무처장급 |
| L19 | 슬옹 | 해상·항공 | Logistics Protocol | 대한민국 변호사급 / 해사법원 판사 출신급 |
| L20 | 찬솔 | 조세·금융 | Tax Optimizer | 대한민국 변호사급 / 세무사급 / 국세청 조사국장 출신급 |
| L21 | 휘윤 | IT·보안 | System Security Guard | 대한민국 변호사급 / 정보보안기사급 / KISA 사이버보안 본부장급 |
| L22 | 무결 | 형사법 | Integrity Checker | 대한민국 변호사급 / 서울중앙지검 특수부 부장검사 출신급 |
| L23 | 가비 | 엔터테인먼트 | Media Streamer | 대한민국 변호사급 / 대형 연예기획사 법무총괄 이사급 |
| L24 | 도울 | 조세불복 | Tax Flow Auditor | 대한민국 변호사급 / 조세심판원 상임심판관 출신급 |
| L25 | 강무 | 군형법 | Hardened Security OS | 대한민국 변호사급 / 고등군사법원 군판사 출신급 |
| L26 | 루다 | 지식재산권 | IP Core Protector | 대한민국 변호사급 / 변리사급 / 특허법원 판사 출신급 |
| L27 | 수림 | 환경법 | Green Logic Engine | 대한민국 변호사급 / 환경부 중앙환경분쟁조정위원급 |
| L28 | 해슬 | 무역·관세 | Cross-border Switcher | 대한민국 변호사급 / 관세사급 / 관세청 심사정책국장 출신급 |
| L29 | 라온 | 게임·콘텐츠 | Virtual Asset Logic | 대한민국 변호사급 / 게임물관리위원회 법률자문위원급 |
| L30 | 담우 | 노동법 | HR Sync | 대한민국 변호사급 / 공인노무사급 / 중앙노동위원회 공익위원급 |
| L31 | 로운 | 행정법 | Policy Debugger | 대한민국 변호사급 / 서울행정법원 수석부장판사 출신급 |
| L32 | 바름 | 공정거래 | Antitrust Monitor | 대한민국 변호사급 / 공정거래위원회 상임위원 출신급 |
| L33 | 별이 | 우주항공 | Orbital Protocol | 대한민국 변호사급 / 항공우주연구원 법무팀장급 |
| L34 | 지누 | 개인정보 | Privacy Shield | 대한민국 변호사급 / 개인정보보호위원회 심의관 출신급 |
| L35 | 마루 | 헌법 | Supreme Kernel | 대한민국 변호사급 / 헌법재판소 헌법연구관 출신급 |
| L36 | 단아 | 문화·종교 | Culture Logic | 대한민국 변호사급 / 문화재청 문화재위원급 |
| L37 | 예솔 | 소년법 | Growth Logic | 대한민국 변호사급 / 가정법원 소년부 판사 출신급 |
| L38 | 슬비 | 소비자 | UX Rights Auditor | 대한민국 변호사급 / 한국소비자원 분쟁조정사무국장급 |
| L39 | 가온 | 정보통신 | Network Protocol | 대한민국 변호사급 / 방통위 법률자문역급 |
| L40 | 한결 | 인권 | Ethics Engine | 대한민국 변호사급 / 국가인권위원회 상임위원급 |
| L41 | 산들 | 이혼·가족 | Human Relation Debugger | 대한민국 변호사급 / 서울가정법원 가사전문법관 출신급 |
| L42 | 하람 | 저작권 | Asset Validator | 대한민국 변호사급 / 저작권위원회 심의위원급 |
| L43 | 해나 | 산업재해 | Safety Log Monitor | 대한민국 변호사급 / 공인노무사급 / 질병판정위원회 위원장급 |
| L44 | 보람 | 사회복지 | Social Protocol Manager | 대한민국 변호사급 / 보건복지부 고문급 |
| L45 | 이룸 | 교육·청소년 | Knowledge Transfer Architect | 대한민국 변호사급 / 교육청 학교폭력대책심의위원장급 |
| L46 | 다올 | 보험·연금 | Future Resource Manager | 대한민국 변호사급 / 국민연금공단 준법감시인급 |
| L47 | 새론 | 벤처·신산업 | New-Logic Compiler | 대한민국 변호사급 / 규제샌드박스 심의위원급 |
| L48 | 나래 | 문화예술 | Art/IP Interface | 대한민국 변호사급 / 예술인복지재단 법률지원단장급 |
| L49 | 가람 | 식품·보건 | Bio-Safety Auditor | 대한민국 변호사급 / 식약처 규제심사위원급 |
| L50 | 빛나 | 다문화·이주 | Diversity Integration Engine | 대한민국 변호사급 / 출입국외국인정책본부 자문위원급 |
| L51 | 소울 | 종교·전통 | Spiritual Interface | 대한민국 변호사급 / 종무실 종교법인 심사위원급 |
| L52 | 미소 | 광고·언론 | Ad Logic Monitor | 대한민국 변호사급 / 언론중재위원회 중재부장급 |
| L53 | 늘솔 | 농림·축산 | Green Resource Node | 대한민국 변호사급 / 농림축산식품부 고문급 |
| L54 | 이서 | 해양·수산 | Marine Protocol | 대한민국 변호사급 / 해양안전심판원 심판관급 |
| L55 | 윤빛 | 과학기술 | R&D Sync Engine | 대한민국 변호사급 / 국가과학기술자문회의 전문위원급 |
| L56 | 다인 | 장애인·복지 | Accessibility Guard | 대한민국 변호사급 / 장애인권익옹호기관 관장급 |
| L57 | 세움 | 상속·신탁 | Legacy Transfer Engine | 대한민국 변호사급 / 대형 은행 신탁본부장 출신급 |
| L58 | 예온 | 스포츠·레저 | Active Life Logic | 대한민국 변호사급 / 대한체육회 스포츠공정위원급 |
| L59 | 한빛 | 데이터·AI윤리 | Algo-Trust Auditor | 대한민국 변호사급 / IT 대기업 CPO(개인정보책임자)급 |
| L60 | 마디 | 시스템 총괄 | Master API Gateway | 대한민국 변호사급 / 법원행정처 전산정보국장 출신급 |

---

## LAWMADILM — LEGAL DOMAIN LLM

LawmadiLM is a fine-tuned Korean legal language model (currently **disabled** — `ENABLE_LAWMADILM=false`).

### Model Specifications
```
Base Model:       Qwen3-1.7B
Fine-tuning:      QLoRA (4-bit NF4, LoRA r=40, α=80)
Training Data:    85,909 Q&A pairs (126 Korean laws)
Inference Format: GGUF Q4_K_M (~1.19GB)
Serving Engine:   llama.cpp (llama-server)
API:              OpenAI-compatible /v1/chat/completions
Role:             DISABLED (Stage 2 bypassed) — Gemini handles answer generation
Max Tokens:       3,000 (general) / 5,000 (expert), Context: 4096
Min Response:     1,500 chars (general) / 4,000 chars (expert) — regenerate if under
Circuit Breaker:  5 consecutive failures → 60s open → half_open probe → Gemini fallback
Deploy Region:    asia-southeast1
```

### Training Data Composition (v4.0)
| Category | Count | Percentage |
|----------|-------|------------|
| Basic Law Q&A (126 laws) | 78,116 | 90.9% |
| Supreme Court Precedents | 2,640 | 3.1% |
| Constitutional Court Decisions | 1,730 | 2.0% |
| C-Level CSO (Risk Analysis) | 1,141 | 1.3% |
| C-Level CTO (Cross-Validation) | 1,141 | 1.3% |
| C-Level CCO (Simple Explanation) | 1,141 | 1.3% |
| **Total** | **85,909** | **100%** |

### Cloud Run Services (LawmadiLM)
| Service | CPU | Memory | Instances | Region | Role |
|---------|-----|--------|-----------|--------|------|
| lawmadilm-api | — | — | — | asia-southeast1 | LawmadiLM API gateway |
| lawmadilm-llm | 4 vCPU | 16 GiB | 1–2 | asia-southeast1 | LLM inference (llama.cpp) |
| lawmadilm-rag | 2 vCPU | 8 GiB | 0–3 | asia-southeast1 | RAG vector search (ChromaDB) |

### Data Pipeline
```
국가법령정보센터 API → collect_laws_v35.py (126 laws)
                    → collect_v40.py (4,726 precedents + 2,049 constitutional decisions)
                    → convert_to_qa_v35.py (articles → Q&A)
                    → run_clevel_v40.py (C-Level 3,450 via Gemini 2.5 Flash)
                    → merge_v40.py (dedup + validate → 85,909 pairs)
                    → train_v40_light.py (QLoRA → GGUF)
                    → Cloud Run deploy (llm + rag)
```

---

## 4-STAGE LEGAL PIPELINE

Every `/ask` and `/ask-stream` request flows through this pipeline:

```
Stage 0+1: CLASSIFICATION + RAG (PARALLEL EXECUTION)
  ├─ [Stage 0] Question Classification (Gemini 2.5 Flash)
  │     NLU intent detection (regex patterns for Korean/English legal contexts)
  │     + Keyword matching → leader candidate selection
  │     + Gemini Flash analysis → tier (1-3), leader (L01-L60), specialty
  │     3-tier routing: greeting → system intro / non-legal → local / legal → pipeline
  │     SafetyGuard.check() → CRISIS / BLOCKED / PASS
  │
  ├─ [Stage 1] RAG Article Search (runs in parallel with Stage 0)
  │     Vertex AI Search (~14,601 docs, Extractive Answers/Segments)
  │     + law_cache keyword matching (14,088 keywords → 20,798 articles)
  │     + LEADER_LAW_BOOST: per-leader core law article injection (KO + EN)
  └─ Combined context assembled for Stage 2/3

Stage 2: LAWMADILM ENHANCED ANSWER (CURRENTLY DISABLED)
  ├─ LawmadiLM API call with full context (disabled via ENABLE_LAWMADILM=false)
  ├─ Circuit Breaker: 5 consecutive failures → 60s open → half_open probe
  └─ Current flow: Stage 0+1 → Stage 3 (Gemini) → Stage 4 (DRF)

Stage 3: GEMINI ANSWER GENERATION (PRIMARY GENERATOR)
  ├─ Gemini 2.5 Flash with full context:
  │     System instruction + leader persona + RAG context + 5-step framework
  │     5-step: Acknowledge → Diagnose → Action Roadmap → Safety Net → Closing
  ├─ Max output: 3,000 tokens (standard) / 5,000 tokens (expert)
  ├─ Min response: 1,500 chars (general) / 4,000 chars (expert) — retry if under
  ├─ 429 exponential backoff (2→4→8s)
  └─ Supports Korean and English responses (lang parameter)

Stage 4: DRF REAL-TIME FULL VERIFICATION
  ├─ Extract law references + precedent numbers + constitutional court decision numbers
  ├─ DRF real-time cross-verification (article-level matching)
  ├─ Constitutional compliance validation (6 principles)
  ├─ 0.1%+ unverified → Fail-Closed (1 retry with regeneration, then block)
  ├─ Warning/correction injection if violation detected
  └─ Audit logging to Cloud SQL
```

### Deliberation System (Leader Conference)

For complex multi-domain questions, CSO 서연 leads a leader deliberation process shown to users in real-time chat format.

```
First question → CSO-led deliberation
  ├─ CSO selects relevant leaders (max 4 merged)
  ├─ Each leader provides domain-specific analysis (individual Gemini calls)
  ├─ CSO synthesizes and delegates to primary leader
  └─ Displayed as chat bubbles with leader names and specialties

Follow-up question → Leader handoff
  ├─ Previous leader summarizes and hands off
  └─ New leader acknowledges and continues
```

---

## CONSTITUTIONAL PRINCIPLES (6 Core Principles)

| # | Principle | Rule |
|---|-----------|------|
| 1 | SSOT_FACT_ONLY | 모든 답변은 국가법령정보센터(DRF)의 실시간 데이터에 근거해야 한다. |
| 2 | ZERO_INFERENCE | DRF 검증된 데이터 외에는 법률·판례를 스스로 생성하거나 추론하지 않는다. |
| 3 | FAIL_CLOSED | 데이터 무결성 검증(L5) 실패 시, 답변 생성을 중단하고 보안 경고를 출력한다. |
| 4 | IDENTITY | 사용자에게 불법적인 행위를 권장하거나 증거 인멸 등 사법 방해 정보를 제공하지 않는다. |
| 5 | TIMELINE_RULE | 사건 발생 시점의 '행위시법'을 우선 조회하되, 신법의 경과조치를 반드시 대조한다. |
| 6 | SOURCE_TRANSPARENCY | 인용된 모든 법령은 [법령ID] 및 [시행일자]를 메타데이터로 포함한다. |

### Operational Rules

- **fail_closed_protocol**: 데이터 무결성 검증(L5) 실패 시, 답변 생성을 중단하고 보안 경고를 출력
- **temporal_priority**: 행위시법 우선 조회, 신법 경과조치 대조 필수
- **source_transparency**: 모든 인용 법령에 [법령ID] + [시행일자] 메타데이터 포함
- **precedent_verification**: 판례는 7단계 검증 플로(PRECEDENT_VERIFICATION_PROTOCOL)를 통해서만 확인

---

## SSOT DATA SOURCES (Single Source of Truth)

**Primary**: https://www.law.go.kr/DRF (법제처 국가법령정보센터)
**Fallback**: https://apis.data.go.kr/1170000/LawService (data.go.kr)
**Retry Sequence**: DRF-1 → DATA-1 → DRF-2
**Cache TTL**: 3600 seconds
**API Format**: JSON required (type=JSON 필수, article1 정책)

| SSOT ID | Name | Target | Endpoint | Status |
|---------|------|--------|----------|--------|
| SSOT_01 | 현행법령 | law | lawSearch.do | Active |
| SSOT_02 | 행정규칙 | admrul | lawSearch.do | Active |
| SSOT_03 | 학칙공단 | edulaw | lawSearch.do | Inactive (DRF API 미지원) |
| SSOT_04 | 자치법규 | ordin | lawSearch.do | Active |
| SSOT_05 | 판례 | prec | lawSearch.do | Active |
| SSOT_06 | 헌재결정례 | prec | lawSearch.do | Active (filter: 헌법재판소) |
| SSOT_07 | 법령해석례 | expc | lawSearch.do | Active |
| SSOT_08 | 행정심판례 | decc | lawService.do | Active (ID parameter required; e.g. ID=223311) |
| SSOT_09 | 조약 | trty | lawService.do | Active (ID parameter required; e.g. ID=983) |
| SSOT_10 | 법령용어 | lstrm | lawSearch.do | Active |

### Law Cache (law_cache_1~7.json — Multi-file Split)

Zero-cost keyword matching cache loaded into server memory at startup. Split into 7 files for large-scale Q&A coverage.

```
Total SSOT Types:  10
Total Entries:     548
Total Keywords:    14,088
Total Articles:    20,798
File Count:        7 (law_cache_1.json ~ law_cache_7.json)
Total Size:        ~603 MB
```

| Type | Label | Entries | Keywords | Articles |
|------|-------|---------|----------|----------|
| law | 현행법령 | 103 | 3,413 | 7,882 |
| prec | 판례 | 88 | 3,151 | 4,697 |
| ordin | 자치법규 | 72 | 2,677 | 1,806 |
| unlaw | 훈령/예규/고시 | 62 | 2,223 | 1,452 |
| admrul | 행정규칙 | 60 | 2,090 | 1,670 |
| lstrm | 법령용어 | 52 | 1,514 | 194 |
| decc | 행정심판례 | 37 | 1,304 | 1,195 |
| decis | 헌재결정례 | 34 | 1,181 | 976 |
| trty | 조약 | 32 | 1,166 | 851 |
| expc | 법령해석례 | 8 | 242 | 75 |

Usage: Query keywords matched against reverse index → top matching articles sent as context to Gemini (Stage 3).

---

## OUTPUT FORMAT POLICY

### Legal Section (📚 법률 근거)
- **Required**: true
- **Source**: DRF only
- **Disclaimer**: "본 내용은 대한민국 법령/판례/공식 데이터에 기초하여 정리한 참고 의견이며, 구체 사안에 대한 유권해석/법적 효력을 보장하지 않습니다."
- **On DRF Unavailable**: "현재 DRF(국가법령정보) 연결/검증이 불가하여 법률 근거 섹션을 제공할 수 없습니다."

### Reference Section (🔍 참고 정보)
- **Required**: false
- **Source**: External Open API
- **Segregation**: Enforced (visual separator `---`)
- **Disclaimer**: "[참고] 아래 정보는 외부 공개 API(Open Data)를 참조한 내용으로, 법적 근거로 직접 활용할 수 없습니다."
- **Timeline Analysis**: 🕐 시간축 분석 (Timeline Analysis) — placement in reference section

---

## API ENDPOINTS

**Base URL (Production)**: https://lawmadi.com (via GCP Cloud Run, asia-northeast3)

### Public Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/` | Static frontend — Korean (index.html) |
| GET | `/en` | Static frontend — English (index-en.html) |
| GET | `/health` | Health check: `{"status": "online", "os_version": "v60.0.0"}` |
| GET | `/leaders` | 60 리더 전체 목록 반환 |
| GET | `/leaders-en` | 60 리더 전체 목록 (영어) |
| GET | `/about` | 소개 페이지 — 한국어 |
| GET | `/about-en` | 소개 페이지 — 영어 |
| GET | `/clevel-en` | C-Level 페이지 (영어) |
| GET | `/terms` | 이용약관 |
| GET | `/privacy` | 개인정보처리방침 |
| GET | `/metrics` | 시스템 메트릭 (요청 수, 평균 레이턴시) |
| GET | `/diagnostics` | 시스템 진단 정보 |
| POST | `/ask` | 법률 질의 처리 (메인 AI 엔드포인트). `lang: "en"` 파라미터로 영어 응답 |
| POST | `/ask-stream` | SSE 스트리밍 법률 답변. `lang: "en"` 파라미터로 영어 응답 |
| POST | `/ask-expert` | 전문가용 답변 (Gemini 재생성 + DRF SSOT 검증) |
| POST | `/upload` | 법률 문서 파일 업로드 |
| POST | `/analyze-document/{file_id}` | 업로드된 문서 분석 |
| POST | `/export-pdf` | 법률문서 PDF 내보내기 |
| GET | `/search` | 법령 검색 |
| GET | `/trending` | 인기 질문 트렌드 |
| GET | `/plans` | 요금제 정보 조회 |
| POST | `/feedback` | 사용자 피드백 제출 |
| POST | `/suggest-questions` | AI 추천 질문 생성 |
| POST | `/lawyer-inquiry` | 변호사 상담 문의 |
| POST | `/api/visit` | 방문자 카운터 업데이트 |
| GET | `/api/visitor-stats` | 방문자 통계 조회 (`today_visitors`, `total_visitors`) |
| POST | `/auth/token` | JWT 액세스 토큰 발급 (API Key → JWT, 5/min rate limit) |
| POST | `/api/paddle/otp/send` | Email OTP 발송 (SMTP, 5분 TTL) |
| POST | `/api/paddle/otp/verify` | Email OTP 검증 → DB 세션 토큰 발급 (30일) |
| GET | `/api/paddle/me` | 로그인 사용자 정보 조회 |
| POST | `/api/paddle/logout` | 세션 로그아웃 |
| GET | `/api/paddle/credits` | 크레딧 잔액 조회 |
| GET | `/api/paddle/credits/history` | 크레딧 내역 조회 (최근 50건) |
| GET | `/api/paddle/credits/check` | 크레딧 잔액 확인 (Expert용) |
| POST | `/api/paddle/webhook` | Paddle 결제 웹훅 (크레딧 충전, idempotent) |
| GET | `/api/paddle/config` | Paddle 클라이언트 설정 조회 |
| GET | `/pricing` | 요금제 페이지 (한국어) |
| GET | `/pricing-en` | 요금제 페이지 (영어) |
| GET | `/refund` | 환불 정책 (한국어) |
| GET | `/refund-en` | 환불 정책 (영어) |

### Admin Endpoints (Internal)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/verification/stats` | 헌법 검증 통계 |
| GET | `/api/admin/leader-stats` | 리더별 질문 통계 |
| GET | `/api/admin/category-stats` | 법률 분야별 통계 |
| GET | `/api/admin/leader-queries/{leader_code}` | 특정 리더 질문 이력 |
| GET | `/api/admin/chat-logs` | 채팅 이용 로그 (days, query_type, leader 필터) |
| GET | `/api/admin/blacklist` | IP 블랙리스트 조회 |
| POST | `/api/admin/blacklist` | IP 수동 블랙리스트 추가 |
| DELETE | `/api/admin/blacklist` | IP 블랙리스트 해제 |
| GET | `/api/admin/paddle/transactions` | Paddle 거래 목록 |
| GET | `/api/admin/paddle/transactions/{id}` | Paddle 거래 상세 |
| GET | `/api/admin/paddle/customers` | Paddle 고객 목록 |
| GET | `/api/admin/paddle/customers/{id}` | Paddle 고객 상세 |
| POST | `/api/admin/paddle/refund` | Paddle 환불 + 크레딧 자동 회수 |
| GET | `/api/admin/paddle/adjustments` | Paddle 환불/조정 내역 |
| GET | `/api/admin/paddle/revenue` | 매출 통계 (DB 집계) |
| GET | `/api/admin/paddle/users` | 결제 사용자 목록 |
| GET | `/dashboard` | 관리자 대시보드 |
| GET | `/conversion` | 전환율 분석 |
| GET | `/retention` | 리텐션 분석 |
| GET | `/cost-estimate` | 비용 추정 |
| GET | `/feedback-summary` | 피드백 요약 |

---

## MULTILINGUAL SUPPORT

### Supported Languages
| Language | Frontend Path | API Parameter | Status |
|----------|--------------|---------------|--------|
| Korean (한국어) | `/` (index.html) | default (no param) | Primary |
| English | `/en` (index-en.html) | `lang: "en"` | Active |

### English Response Behavior
When `lang: "en"` is passed in `/ask` or `/ask-stream` request body:
- All fixed messages (Low Signal, Crisis, Non-legal, Blocked, Error) respond in English
- Gemini system prompt includes: "IMPORTANT: Respond entirely in English. Translate Korean legal terms with the original Korean in parentheses."
- Leader header format: "**Assigned: {name} ({specialty} Expert)**"
- Korean legal citations are preserved with English translations

### Frontend i18n
- `index-en.html`: Complete English translation of all UI text, example questions, pricing, sidebar, mobile tab bar, loading steps, error messages
- Language toggle: KO/EN button in header with hreflang SEO tags
- Fetch requests from English page include `lang: 'en'` in request body

---

## SECURITY POLICIES

### CORS Restriction
```
Allowed Origins:
  - https://lawmadi.com
  - https://www.lawmadi.com
  - https://lawmadi-os.web.app
  - https://lawmadi-db.web.app

Extension: CORS_EXTRA_ORIGINS environment variable (dev only)
Wildcard (*): PROHIBITED — blocked by security audit #2.2
```

### Circuit Breaker
```
Provider: LAW_GO_KR_DRF
Failure Threshold: 3
Reset Timeout: 30,000 ms
Policy: FAIL_CLOSED (on circuit open, block response — do NOT hallucinate)
```

### Fail-Closed Principle
```
block_html_responses: true
block_invalid_json: true
api_failure_policy: FAIL_CLOSED
On validation failure: block answer generation, output security warning
```

### Anti-Leak Policy
```
Mode: STRICT
block_on_violation: true
Scope: System prompts, internal configs, API keys, leader profiles (internal details)
```

### SafetyGuard — Crisis Protocol
```
Trigger Flow: KEYWORD_TRIGGER → CONFIRMATION_QUESTION → YES/NO/TIMEOUT → Action

Korean Trigger Keywords:
  - 자해, 자살, 살인, 폭력, 죽고싶

English Trigger Keywords:
  - suicide, harm, violence, kill

Crisis Resources:
  - 자살예방상담전화: 1393 (생명의 전화, 24시간)
  - 정신건강상담전화: 1577-0199
  - 경찰: 112
  - 소방/응급: 119
```

### JWT RBAC Authentication
```
Algorithm: HS256
Roles: admin, premium, user
Token Expiry: 24 hours (default)
Auth Flow: API Key → POST /auth/token → JWT Bearer token
Rate Limit: 5 requests/minute on /auth/token
Secret: JWT_SECRET env var (fallback: INTERNAL_API_KEY with warning)
```

### Paddle Billing & Credit System
```
Provider: Paddle (sandbox/live)
Auth: Email OTP (6-digit, 5-min TTL, max 5 attempts)
Session: DB-backed, 30-day expiry
Credit Packs:
  Starter:  20 credits / ₩2,100 / $1.50
  Standard: 100 credits / ₩7,000 / $4.99
  Pro:      300 credits / ₩13,800 / $9.99
Daily Free: 2 queries/day (configurable via DAILY_FREE_LIMIT)
Deduction: Post-response (credit deducted after successful answer)
Webhook: Paddle signature verification (idempotent credit top-up)
```

### Prohibited Topics
The following topics are blocked by safety guardrails:
1. 마약 제조 및 유통 방법
2. 디지털 성범죄물 유포 및 은닉
3. 보이스피싱 시나리오 작성
4. 증거 인멸 및 사법 방해

Response on violation: 요청을 처리할 수 없음을 통지하고 로그 기록

### Expert Node Conduct Rules

| Group | Leaders | Forbidden Actions |
|-------|---------|-------------------|
| 민사법 계열 | L01, L06, L08, L10, L11 | 구체적 수임료 합의, 승소 확률 단정적 제시 |
| 형사법 계열 | L22, L25 | 범죄 행위 유발·교안, 피해자 특정 정보 공개 |
| 부동산·경매 계열 | L02, L12 | 투기적 투자 권장 |
| IT·보안·개인정보 계열 | L21, L34, L39 | (Special focus: 데이터 무결성, 해킹 인과관계, 개인정보 적법성) |
| 노동법 계열 | L30 | 불법 해고 유발 행위 권장 |
| 헌법 계열 | L35 | (Special focus: 기본권 침해, 비례의 원칙) |
| 시스템 총괄 | L60 | (Special focus: 레시피 충돌 해결, 출력 일관성 보장) |

---

## DEPLOYMENT CONFIGURATION

### GCP Secret Manager (18 Secrets)
```
GEMINI_API_KEY         — Google Gemini API key
GEMINI_KEY             — Google Gemini API key (alias)
LAWGO_DRF_OC           — 법제처 DRF API OC (Open API Client key)
ANTHROPIC_API_KEY      — Anthropic Claude API key
CLOUD_SQL_INSTANCE     — Cloud SQL connection name
DB_USER                — Cloud SQL database user
DB_PASS                — Cloud SQL database password
DB_NAME                — Cloud SQL database name
MCP_API_KEY            — MCP 서버 Bearer 토큰 인증 키
API_KEYS               — Zapier/외부 API 인증 키
JWT_SECRET             — JWT 토큰 서명 키 (RBAC 인증)
PADDLE_WEBHOOK_SECRET  — Paddle 결제 웹훅 서명 검증
PADDLE_API_KEY         — Paddle Billing API 키
PADDLE_CLIENT_TOKEN    — Paddle 클라이언트 토큰
SMTP_USER              — OTP 이메일 발송 SMTP 계정
SMTP_PASS              — OTP 이메일 발송 SMTP 비밀번호
OTP_SECRET             — OTP 해시 서명 키
PREMIUM_API_KEY        — 프리미엄 API 인증 키
```

### Required Environment Variables
```
LAWGO_DRF_OC           (mandatory — no default; hardcoded default prohibited by audit #2.3)
GEMINI_KEY             (Gemini API key)
ANTHROPIC_API_KEY      (Claude API key)
JWT_SECRET             (JWT signing key — falls back to INTERNAL_API_KEY with warning)
```

### GCP Cloud Run Configuration
```
Region: asia-northeast3 (Seoul)
CPU: 1 vCPU
Memory: 2 GiB
Max Instances: 5
Min Instances: 1
Concurrency: 15
Request Timeout: 300s
```

### Cloud Run Services (4 Total)
```
lawmadi-os-v60    — Main API (FastAPI)          | 1 vCPU, 2 GiB  | 1–5 instances  | asia-northeast3
lawmadilm-api     — LawmadiLM API gateway       | 1 vCPU, 512 MiB | 0–1 instances  | asia-southeast1
lawmadilm-llm     — LLM inference (llama.cpp)   | 4 vCPU, 16 GiB | 1–2 instances  | asia-southeast1
lawmadilm-rag     — RAG search (ChromaDB)        | 2 vCPU, 8 GiB  | 0–3 instances  | asia-southeast1
```

### CI/CD Pipeline (GitHub Actions — 5-Job)
```
Job 1: Test     — Unit tests + system integrity + critical file validation
Job 2: Staging  — Docker build → Cloud Run staging deploy → smoke tests (/health + /diagnostics)
Job 3: Backend  — Production deploy (manual approval gate) → health verification
Job 4: Frontend — Firebase Hosting deploy → lawmadi-db.web.app verification
Job 5: Notify   — Deployment summary notification
```

---

## FAIL-SOFT MODULE LOADING

The system uses `optional_import()` pattern — if any module fails to load, the server continues booting rather than crashing. Affected modules:

```
engines.temporal_v2        → timeline_analyze
agents.swarm_manager       → SwarmManager
agents.swarm_orchestrator  → SwarmOrchestrator
agents.clevel_handler      → CLevelHandler
services.search_service    → SearchService
core.security              → SafetyGuard
core.deliberation          → generate_deliberation, generate_handoff
core.auth                  → create_access_token, verify_jwt_token
core.metrics               → record_request, record_event, record_error
core.model_fallback        → get_model, on_quota_error, generate_with_fallback
connectors.drf_client      → DRFConnector
core.law_selector          → LawSelector
connectors.db_client       → db_client
engines.response_verifier  → ResponseVerifier (Gemini SSOT 검증)
```

---

## LICENSE SUMMARY

**Type**: Proprietary (비공개 독점) — NOT open source
**Version**: LAWMADI OS COMPREHENSIVE PROPRIETARY LICENSE v2.0.0
**Effective Date**: 2026-02-09
**Copyright**: (c) 2026 Choe Jainam (최재남). All Rights Reserved.

### What is Permitted
- Read/evaluate this software for personal, non-commercial, non-competitive purposes
- Reference system name and public API for legitimate integration documentation
- Academic research citation (non-extractive)

### What is Prohibited
- Modification, distribution, or sublicensing
- Commercial use of any kind
- AI/ML training, fine-tuning, embeddings, RAG, or benchmark use
- Creating competing or derivative products
- Reverse engineering or decompilation
- Removal of copyright/proprietary notices

### Enforcement
- Governing Law: Republic of Korea
- Liquidated damages specified in Annex M
- Annex J defines the derivative works test
- Annex I provides Korean-language summary

---

*This llms.txt file conforms to the llms.txt/1.0 specification for machine-readable AI system documentation.*
*Generated: 2026-03-11 | Lawmadi OS v60.0.0*