# Hugging Face へのアップロードガイド
**refactorium-dual-deepseek-r1-7b v1.0.0**

---

## 📋 前提条件

```bash
# Git LFS をインストール
brew install git-lfs  # macOS
# または
apt-get install git-lfs  # Linux

# Hugging Face CLI をインストール
pip install huggingface-hub

# Hugging Face にログイン
huggingface-cli login
```

---

## 🚀 ステップバイステップ

### ステップ1: Hugging Face リポジトリを作成

1. https://huggingface.co/new にアクセス
2. リポジトリ名: `refactorium-dual-deepseek-r1-7b`
3. タイプ: `Model`
4. ライセンス: `mit`
5. 作成

### ステップ2: ローカルリポジトリを初期化

```bash
cd /Users/motonishikoudai/project_refactorium

# Git LFS を初期化
git lfs install

# Hugging Face リポジトリをクローン
git clone https://huggingface.co/kofdai/refactorium-dual-deepseek-r1-7b hf_repo

cd hf_repo
```

### ステップ3: ファイルをコピー

```bash
# プロジェクトルートからコピー
cp -r ../phase1_skeleton .
cp -r ../tests .
cp ../requirements.txt .
cp ../USER_GUIDE.md .
cp ../API_REFERENCE.md .
cp ../ARCHITECTURE.md .
cp ../DEPLOYMENT_GUIDE.md .
cp ../RELEASE_NOTES_v1.0.0.md .
cp ../MODEL_CARD.md .
cp ../huggingface_setup.py .
cp ../install.sh .
cp ../.gitattributes .
cp ../README.md .

# モデル重みをコピー（存在する場合）
mkdir -p models
cp /path/to/model/weights/*.safetensors models/
```

### ステップ4: Git LFS で大きいファイルを管理

```bash
# Git LFS トラックを設定
git lfs track "*.safetensors"
git lfs track "*.bin"
git lfs track "*.pt"
git lfs track "*.pth"

git add .gitattributes
```

### ステップ5: ファイルをステージ

```bash
# 優先度順にステージ
echo "# Staging in priority order..."

# 1. コアシステム（最優先）
git add phase1_skeleton/*.py
git add phase1_skeleton/limbic/*.py
git add phase1_skeleton/safety/*.py
git add phase1_skeleton/config/

# 2. ドキュメント
git add *.md

# 3. 設定・スクリプト
git add requirements.txt
git add huggingface_setup.py
git add install.sh

# 4. テスト
git add tests/

# 5. モデル重み（最後）
git add models/
```

### ステップ6: コミット

```bash
git commit -m "refactorium-dual-deepseek-r1-7b v1.0.0

Features:
- Constraint-driven consciousness engine
- 3-layer safety architecture
- Zero-downtime model/database switching
- Zero-downtime performance: P50=1.15ms, Throughput=7,439 req/s
- Comprehensive documentation
- 55/55 tests passing

This is a complete AI system, not just model weights.
Model weights alone will NOT work - use install.sh or huggingface_setup.py

For more information, see:
- USER_GUIDE.md - Installation and usage
- MODEL_CARD.md - System overview
- ARCHITECTURE.md - Technical details

Installation:
  bash install.sh
  or
  python huggingface_setup.py

License: MIT
"
```

### ステップ7: プッシュ

```bash
git push
```

Git LFS が大きいファイルをアップロードします。完了まで時間がかかる場合があります。

---

## 🔒 重要: ファイル構造

```
refactorium/
├── 🔴 必須 (これらなしで動作しません)
│   ├── phase1_skeleton/
│   │   ├── orchestrator.py
│   │   ├── api_server.py
│   │   ├── model_manager.py
│   │   ├── db_manager.py
│   │   ├── runtime_coordinator.py
│   │   ├── limbic/physiology.py
│   │   ├── safety/brain_constraints.py
│   │   └── config/system.yaml
│   ├── requirements.txt
│   └── install.sh
│
├── 🟡 推奨 (セットアップを大幅に簡易化)
│   ├── USER_GUIDE.md
│   ├── API_REFERENCE.md
│   ├── ARCHITECTURE.md
│   ├── DEPLOYMENT_GUIDE.md
│   ├── MODEL_CARD.md
│   ├── huggingface_setup.py
│   └── README.md
│
└── 🟢 オプション (モデル重みなど)
    └── models/
        ├── main_model.safetensors
        └── shadow_model.safetensors
```

---

## ✅ アップロード後の確認

### 1. Hugging Face ページで確認

https://huggingface.co/kofdai/refactorium-dual-deepseek-r1-7b

以下が表示されるか確認：

- ✅ コードファイル
- ✅ ドキュメント
- ✅ モデル重み
- ✅ Model Card

### 2. ダウンロード テスト

```bash
# 新しいディレクトリでテスト
mkdir refactorium_test
cd refactorium_test

# ワンコマンドセットアップ
python huggingface_setup.py --repo kofdai/refactorium-dual-deepseek-r1-7b
```

期待される結果：

```
✅ すべての必須コンポーネントが正常にダウンロード
✅ セットアップ検証に合格
✅ システムはすぐに実行可能
```

---

## 🔐 セキュリティ チェックリスト

アップロード前に確認：

- [ ] `.gitattributes` が Git LFS を正しく設定している
- [ ] `huggingface_setup.py` が検証機能を持っている
- [ ] `MODEL_CARD.md` に明確な警告がある
- [ ] ドキュメントに「モデル重みだけでは動作しない」と記載
- [ ] `requirements.txt` が完全である

---

## 📝 Hugging Face メタデータ

リポジトリページで設定：

### モデルカード

```
# Model Card: Refactorium v1.0.0

This is **NOT** just model weights.

This is a complete constraint-driven consciousness AI system
that includes:

- Constraint-driven consciousness engine
- 3-layer safety architecture
- Core system (18,000+ lines of code)
- Tests (55/55 passing)
- Documentation (13,000+ lines)

Model weights ALONE will NOT work.

Install with: python huggingface_setup.py

For details, see MODEL_CARD.md
```

### タグ

```
Tags: refactorium, constraint-driven-consciousness,
      safety-ai, deep-seek, dual-model, zero-downtime,
      constraint-engine, ethical-ai, cpython3-11,
      production-ready, v1.0.0
```

### データセット

```
Datasets:
- refactorium-memories (ChromaDB format)
- constraint-mappings (YAML)
```

---

## 🚨 アップロード後の監視

### ダウンロード数の追跡

Hugging Face は自動的に以下を追跡します：

- 📊 ダウンロード数（日次）
- 👥 ユニークユーザー
- ⭐ スター数
- 💬 コメント
- 🔗 リンク参照

### ダッシュボード

https://huggingface.co/kofdai/refactorium-dual-deepseek-r1-7b/discussions

で以下を監視：

- コミュニティからの質問
- 使用例
- 問題レポート

---

## 🐛 問題が生じた場合

### モデル重みだけがダウンロードされた

```bash
# Hugging Face リポジトリから完全版をダウンロード
git clone https://huggingface.co/kofdai/refactorium-dual-deepseek-r1-7b

cd refactorium-dual-deepseek-r1-7b

# これで完全なシステムが揃います
```

### Git LFS ファイルが見つからない

```bash
# Git LFS ファイルをプル
git lfs pull

# または完全にダウンロード
git clone --single-branch https://huggingface.co/kofdai/refactorium-dual-deepseek-r1-7b
cd refactorium-dual-deepseek-r1-7b
git lfs pull
```

---

## 📚 参考リンク

- [Hugging Face Models Documentation](https://huggingface.co/docs/hub/models)
- [Git LFS Documentation](https://git-lfs.github.com/)
- [Model Card Guidelines](https://github.com/huggingface/model_cards)

---

**Version**: 1.0.0
**Last Updated**: 2025-12-14
**Status**: Ready for Upload