Kuroko（黒衣）

Kuroko は、アイデアメモや実験記録などのローカル資料を読み込み、公開検索に出してよい情報だけを抽象化して外部調査を行い、その結果を使って新規性評価と明細書ドラフト生成までを一気通貫で実行します。

想定用途:

発明候補の整理
先行技術の公開調査
新規性の一次評価
明細書ドラフトのたたき台作成

弁理士に依頼すると費用と時間がかかり、汎用 AI に相談すると発明が公知化・漏洩するリスクがある。Kuroko はこの2つの課題を、機密情報を処理するローカルエージェントと、論文や先攻特許の情報収集と分析を行うフロントエージェントを組み合わせることで解決した、個人発明家・スタートアップなどの中小規模の企業向けのシステムです。

---

特徴
アーキテクチャ概要（back / gate / front）
セキュリティ方針
エージェント構成
パイプライン（処理フロー）
動作環境
インストール
起動方法（クイックスタート）
デモの実行
ダッシュボード
入力データ・フォルダ
成果物データ
設定ファイル
各種コマンド
ディレクトリ構成
テスト
既知の制約
今後の改良候補
関連ドキュメント

---

特徴

ローカル資料を起点に、調査からドラフトまでを 1 本のパイプラインで実行

機密処理と公開調査を back / gate / front に分離

機密に触れる工程はすべて back ゾーンのローカル LLM で実行。

外部に出るのは抽象化された公開クエリのみ

ゲートを越境するトラフィックは固有数値・社内コード等を正規表現で検出して遮断

越境した全クエリ・全取得物を監査ログに記録

Semantic Scholar による論文系の先行技術レビュー

取得した先行技術との類似度から新規性を評価し、マッピング

Ollama の OpenAI 互換 API を前提に、モデル差し替えがしやすい構成

ダッシュボードでエージェントの稼働状況を可視化

---

アーキテクチャ概要（back / gate / front）

Kuroko は単一の巨大エージェントではなく、back（機密ゾーン）／ gate（漏洩ゲート）／ front（公開ゾーン） の3層に役割を分けた構成です。

┌──────────── BACK（機密ゾーン：ローカル LLM）────────────┐
│  ・機密入力の読解と抽象化／分解（最重要）                  │
│  ・内部表現（機密）の保持 ─── back 内に留置、gate を越えない │
│  ・新規性評価                                            │
│  ・明細書ドラフト生成 ＋ Reviewer Loop                    │
└──────────────────────┬──────────────────────────────┘
                       │  抽象化された公開クエリだけが越える
              ┌────────▼────────┐
              │  GATE 漏洩ゲート  │  検査 ＋ 監査ログ（logs/gate_audit.log）
              └────────┬────────┘
                       │  公開文献だけが back へ戻る
┌──────────────────────▼──────────────────────────────┐
│  FRONT（公開ゾーン：クラウド／大型 LLM 可）               │
│  ・特許 DB／論文（Semantic Scholar）／Web を検索し、       │
│    公開文献だけを gate 経由で back に返す実行係            │
└──────────────────────────────────────────────────────┘

越えるのは2方向だけ：(1) back → front は「抽象化された公開クエリ」のみ。(2) front → back は「公開文献そのもの」。
監査ログ：ゲートを通過した全クエリ・全取得文献を記録し、「何を外に出したか」を100%再構成できることを KPI としています。

⚠ 重要：リポジトリのコードは稼働PCへの負担軽減のため、機密ゾーンに外部クラウドモデルが設定されています。本番環境では、 back（機密）側は必ずローカルモデル（例 gpt-oss:20b）へ差し替えてください。

---

セキュリティ方針

Kuroko の差別化＝「構造的な機密保証」を、運用とコードの両面で担保しています。

機密処理は back zone に閉じる — 機密情報を扱う工程は back zone から外に出しません。

越境は必ずゲート経由 — back -> front の通信はすべて core/gate.py を通します。

ダッシュボードは既定でローカル専用 — 既定で 127.0.0.1 のみに bind

ダウンロード経路は成果物の最小限ファイルに限定し、状態ディレクトリやログ全体は配信しません。

抽象化の徹底 — 固有の数値・材料名・社内コード・製品名・組成比を公開クエリに含めません。抽象化の確信度が低い語は back に留め、人間レビューに回します。

---

エージェント構成

エージェント	ゾーン	責務	実装
DocumentIngestor	back	ローカル資料の読み込み	`core/ingest.py`
Abstractor	back	発明の内部表現（機密）と公開検索向けクエリ（抽象化）の生成。Kuroko の心臓部	`core/abstractor.py`
Gate（漏洩ゲート）	gate	外向きクエリの検査・遮断と監査ログ記録	`core/gate.py`
PublicResearcher	front	公開ソース／ローカル索引／合成データから prior art を収集	`core/public_research.py`
NoveltyEvaluator	back	内部表現と先行技術を突合し、要素別に新規性を評価	`core/novelty.py`
DraftPlanner	back	明細書の章立て（アウトライン）を作成	`core/drafting.py`
PatentDraftWriter	back	各節のドラフト本文を生成し結合	`core/drafting.py`
DraftExaminer	back	出力レビュー（整合性・非限定表現・請求項対応など）	`core/review.py`

各エージェントの契約（役割／入力／出力スキーマ／禁止事項など）は agents/*.md にプロンプトとして定義されています。

---

パイプライン（処理フロー）

core/pipeline.py が S0 → S6 を逐次実行する状態機械です。

段階	内容	ゾーン
S0	入力資料の読み込み	back
S1	機密読解・抽象化／分解（内部表現＋公開クエリの生成）	back
S2	漏洩ゲートでクエリを検査 → 公開調査で prior art を取得	gate → front
S3	新規性評価	back
S4	アウトライン作成 → 明細書ドラフト生成	back
S5	Reviewer Loop（審査と再生成）	back
S6	出力完了（以降の出願検討は人間レビュー必須）	back

---

動作環境

OS：Windows（PowerShell 前提。本書のコマンド例は PowerShell 用）
Python：3.11 以上
LLM 実行基盤：Ollama for Windows
外部 API（任意）：Semantic Scholar API、PatentsView API
ブラウザ：ダッシュボード表示用（任意）

最小構成では Python 標準ライブラリ中心で動作します。ライブ LLM 実行・YAML 設定・BM25 検索などを使う場合は後述の optional dependency を追加してください。

PowerShell の文字コード設定によっては、コンソール上だけ日本語が文字化けすることがあります。出力ファイル自体は UTF-8 で保存されます。

---

インストール

・リポジトリのルートへ移動します。

・依存をインストールします。

pip install -e ".[llm,yaml,retrieval,dev]"

用途別の optional dependency は以下のとおりです（pyproject.toml）。

extras	内容	主なパッケージ
`llm`	ライブ LLM 実行（Ollama OpenAI 互換クライアント）	`openai`
`yaml`	YAML 設定ファイルの読み込み	`PyYAML`
`retrieval`	BM25 字句検索	`rank-bm25`
`dev`	テスト	`pytest`

・Ollama を起動し、使用するモデルを準備します。

　既定の接続先は http://localhost:11434/v1 です。

・公開調査 API を使う場合だけ、必要に応じて環境変数を設定します。

$env:SEMANTIC_SCHOLAR_API_KEY = "your_api_key_here"
$env:PATENTSVIEW_API_KEY = "your_api_key_here"

---

基本の使い方

パイプライン実行

python main.py run <入力ファイルまたはディレクトリ> --objective "目的文" --config config.yaml

例:

python main.py run data/synthetic/example_idea.md --objective "ローカル資料から特許ドラフトを作成する" --config config.yaml

run は省略可能です（最初の引数がコマンド名でなければ自動的に run 扱いになります）。
--objective：パイプラインの目的文（省略時は既定値を使用）。
--config：使用する設定ファイル（省略時は config.yaml）。

実行が終わると結果サマリが JSON で標準出力され、成果物は設定ファイルの state_dir / artifacts_dir に書き出されます。

ダッシュボード起動

python main.py dashboard --open-browser

ダッシュボードは 1 つ目のターミナルで起動し、パイプラインは 2 つ目のターミナルで実行する使い方を想定しています。詳細は docs/dashboard.md を参照してください。

・ホストやポートを指定する場合：

python main.py dashboard --host 127.0.0.1 --port 8765

・ライブ実行がなくてもアニメーションするデモシーンをループ表示：

python main.py dashboard --demo --open-browser

🔒 ダッシュボードは既定で 127.0.0.1（ローカル専用）に bind します。0.0.0.0 などで外部公開したい場合のみ、リスクを理解したうえで --allow-remote を付けてください。

よく使う確認コマンド

LLM 接続確認:

python main.py llm-health --config config.live-local.yaml

LLM ウォームアップ:

python main.py llm-warmup --config config.live-local.yaml --zone back

公開調査 API 接続確認:

python main.py research-health --config config.live-public.yaml

主な出力先

state/: 中間状態 JSON
artifacts/drafts/: 明細書ドラフト
artifacts/research/: 調査レポート
artifacts/review/: レビュー結果
logs/gate_audit.log: gate 監査ログ

通常実行の state/、artifacts/、logs/、queues/、data/cache/ は Git 管理対象外です。

主な設定ファイル

config.yaml: 標準設定
config.demo.yaml: 安定デモ用設定
config.live-local.yaml: ローカル Ollama 検証用
config.live-public.yaml: 公開調査 API 検証用
config.live-public-smoke.yaml: 短時間の疎通確認用
config.live-public-prod.example.yaml: 本番寄り設定の例

デモ

デモ実行コマンド:

python main.py run data/demo/demo_idea.md --objective "ローカル資料から特許ドラフトを作成するデモ" --config config.demo.yaml

デモ出力先:

demo_output/

デモの説明順（推奨）

main.py run ... --config config.demo.yaml を実行
python scripts/demo-summary.py で passed_review / matched・uncovered queries / source mix / Semantic Scholar backend を確認
patent_specification.md でドラフト全体を見る
背景技術.md で先行技術の根拠を見せる
review.json でレビュー結果を見る

デモの詳しい手順は docs/demo-run.md を参照してください。

---

入力データ・フォルダ

Kuroko の入力は、ローカルにあるアイデアメモ・実験レポート・比較表・調査結果などのテキスト文書です。run コマンドにファイル単体でもディレクトリでも渡せます（ディレクトリの場合は配下の文書をまとめて読み込みます）。

パス	用途
`data/demo/demo_idea.md`	デモ用のサンプル発明アイデア
`data/demo/prior_art_demo.json`	デモ用の固定 prior art（特許風 fixture）
`data/synthetic/example_idea.md`	合成発明アイデアのサンプル
`data/synthetic/prior_art.json`	テスト用の合成先行技術
`data/datasets/`	Semantic Scholar データセット等の入力
`data/cache/`	公開調査・データセット索引のキャッシュ（Git 管理外）

自分のアイデアで実行する場合は、メモファイル（.md など）を用意して run の引数に渡してください。

python main.py run path/to/my_idea.md --objective "<目的文>" --config config.yaml

---

成果物データ

パイプライン実行後、設定ファイルの state_dir / artifacts_dir / logs_dir に以下が出力されます（標準設定では state/ artifacts/ logs/、デモでは demo_output/ 配下に同じ構造で出力）。

中間状態（`state/`）

state/session.json — セッション全体の進行状態
state/input_documents.json — 読み込んだ入力文書
state/internal_repr.json — 機密：内部表現（back 内のみ・ゲートを越えない）
state/public_queries.json — 抽象化された公開クエリ（ゲートを越えるもの）
state/prior_art.json — front が取得した公開文献
state/novelty.json — 新規性評価結果
state/draft_outline.json — 明細書アウトライン

成果物（`artifacts/`）

artifacts/drafts/patent_specification.md — 明細書ドラフト全体（節別 → 結合）
節別ファイル例：発明の名称.md / 技術分野.md / 背景技術.md / 発明が解決しようとする課題.md / 課題を解決するための手段.md / 発明の効果.md / 発明を実施するための形態.md / 特許請求の範囲.md / 要約.md ほか
artifacts/research/prior_art_report.md — 先行技術調査レポート
artifacts/review/review.json — Examiner のレビュー結果・修正履歴

ログ（`logs/`）

logs/gate_audit.log — 越境した全クエリ・全取得物の監査証跡（追記型）
logs/agent_activity.jsonl — ダッシュボード用のイベントタイムライン

通常実行の state/ artifacts/ logs/ は Git 管理対象外です。公開リポジトリに含めている demo_output/ は、同梱サンプル入力から生成したデモ用成果物のみです。

---

設定ファイル

ファイル	用途
`config.yaml`	標準設定（既定）。テスト用にクラウドモデル指定・ライブ API オフ
`config.demo.yaml`	安定デモ用。live Semantic Scholar ＋特許風 fixture。出力は `demo_output/`
`config.live-local.yaml`	ローカル Ollama 構成の検証用
`config.live-public-smoke.yaml`	live 配線確認用。外部 patent-source を切って短時間で end-to-end 確認
`config.live-public.yaml`	実験的な live public-source 用（キー欄は空でコミット）
`config.live-public-prod.example.yaml`	将来の本番寄り設定の例

設定は大きく llm / gate / novelty / research / pipeline のセクションに分かれます。主な項目：

llm.front_model / llm.back_model — front/back 各ゾーンのモデル。本番は back_model をローカルモデルへ差し替え。
llm.enable_live_llm — ライブ LLM 呼び出しの有効化。
gate.mode — strict（ホワイトリスト＋人間確認）／loose（自動）。
novelty.similarity_threshold — これを超える類似度に「新規性に注意」フラグ。
research.* — Semantic Scholar / PatentsView / Google Patents など公開ソースの有効化・接続先・キャッシュ設定。API キー欄は空にし、環境変数で供給。
pipeline.state_dir / artifacts_dir / logs_dir — 出力先。max_review_rounds で Reviewer Loop の上限回数を指定。

---

各種コマンド

すべて python main.py <サブコマンド> 形式です。

パイプライン実行

python main.py run <入力> --objective "目的文" --config config.yaml

LLM ヘルスチェック（Ollama 接続と解決済みモデルの確認）

python main.py llm-health --config config.live-local.yaml

LLM ウォームアップ（大型ローカルモデルの事前起動）

python main.py llm-warmup --config config.live-local.yaml --zone back

public research ヘルスチェック（公開 API の設定・接続確認）

python main.py research-health --config config.live-public.yaml

Semantic Scholar ローカル索引の作成

python main.py semantic-index --config config.live-public.yaml

Semantic Scholar バックエンド単体確認

python main.py semantic-query "document analysis patent drafting" --config config.live-public.yaml --limit 3

ダッシュボード起動

python main.py dashboard --open-browser

---

ディレクトリ構成

Kuroko/
├─ main.py                      # CLI エントリポイント（run / dashboard / *-health など）
├─ pyproject.toml               # パッケージ定義・optional dependencies
├─ AGENTS.md                    # Codex 用：アーキテクチャ要約と各エージェントの責務・禁止事項
├─ README.md                    # 本ファイル
├─ .gitignore                   # 出力物・秘密ファイル・ローカル資料の除外設定
│
├─ config.yaml                  # 標準設定
├─ config.demo.yaml             # 安定デモ用設定
├─ config.live-local.yaml       # ローカル Ollama 検証用
├─ config.live-public*.yaml     # live public-source 用（smoke / 実験 / 本番例）
│
├─ core/                        # コア実装
│  ├─ pipeline.py               # S0→S6 の逐次オーケストレータ（状態機械）
│  ├─ llm_client.py             # Ollama OpenAI 互換クライアント（front/back 切替）
│  ├─ config.py                 # 設定読み込み
│  ├─ ingest.py                 # ローカル資料の読み込み
│  ├─ abstractor.py             # 機密読解・抽象化／分解
│  ├─ gate.py                   # 漏洩ゲート（検査＋監査ログ）
│  ├─ public_research.py        # 公開調査（Semantic Scholar 等）
│  ├─ semantic_dataset.py       # Semantic Scholar ローカル索引
│  ├─ embeddings.py             # 埋め込み
│  ├─ retriever.py              # BM25＋ベクタのハイブリッド検索
│  ├─ novelty.py                # 新規性評価
│  ├─ drafting.py               # アウトライン作成・明細書ドラフト生成
│  ├─ review.py                 # Examiner（Reviewer Loop）
│  ├─ models.py                 # データモデル
│  ├─ state_store.py            # 状態の保存・読み込み
│  ├─ dashboard_server.py       # ダッシュボードサーバ（ローカル bind 検証・配信制限）
│  └─ dashboard_state.py        # ダッシュボード状態管理
│
├─ agents/                      # 役割別 rules.md（プロンプト＝契約）
│  ├─ abstractor.md  dialogue.md  public_researcher.md
│  ├─ novelty_evaluator.md  planner.md  examiner.md
│  └─ writers/                  # background / summary / detailed / claims
│
├─ dashboard/                   # ダッシュボードのフロントエンド（index.html / app.js / styles.css）
│
├─ data/                        # 入力・合成データ・キャッシュ
│  ├─ demo/                     # デモ用アイデア・固定 prior art
│  ├─ synthetic/                # 合成発明・合成先行技術
│  ├─ datasets/                 # データセット入力
│  └─ cache/                    # 公開調査・索引キャッシュ（Git 管理外）
│
├─ demo_output/                 # デモ実行の出力（公開リポジトリに同梱）
│
├─ scripts/                     # 実行補助スクリプト（demo-run / demo-summary / research-health）
├─ docs/                        # セットアップ・デモ・ダッシュボード・リリース等の手順
├─ tests/                       # テスト
│
├─ state/  artifacts/  logs/  queues/   # 実行時に生成（Git 管理外）
└─ 基本方針/  参考資料/                    # ローカルの企画・設計資料／参照素材（Git 管理外）

---

テスト

python -m unittest discover -s tests -p "*.py"

pytest を入れている場合は：

pytest

主なテスト：test_pipeline_smoke.py / test_gate.py / test_drafting.py / test_cli_commands.py / test_dashboard.py / test_live_clients.py。

---

既知の制約

本番の公開特許ソースは段階的に検証中です。Google Patents 系の live 経路は現時点でデモ本番向けには不安定で、主経路には非推奨です。
PatentsView はコード上の対応はありますが、現時点では既定で無効です。
Semantic Scholar dataset index は未構築でも動作しますが、その場合は live fallback になります。
reviewer loop は現状ルールベース中心の基礎実装段階で、実務上の厳密な特許チェックを完全に代替するものではありません。
ダッシュボードはローカル観測用途を優先した設計です。
Kuroko は自動提出の主体ではありません。 生成物はあくまで出願前のたたき台です。出願検討の前に、必ず弁理士または本人による人間レビュー（S6）を行ってください。

---

今後の改良候補

ローカル索引ベースの prior art を本番既定へ寄せる
Lens Patent API の追加
EPO OPS など、より安定した patent-source の追加
claims / abstract / CPC などを含む prior art 構造の拡張
レビュー品質の強化
機械学習・数理モデルによるシミュレーションエージェントの組み込み（より精緻なアイデア評価・提案）

---

Kuroko（特許出願支援のAIシステム）

Kuroko（黒衣）

目次

特徴

アーキテクチャ概要（back / gate / front）

セキュリティ方針

エージェント構成

パイプライン（処理フロー）

動作環境

インストール

パイプライン実行

ダッシュボード起動

よく使う確認コマンド

主な出力先

主な設定ファイル

デモ

入力データ・フォルダ

成果物データ

中間状態（`state/`）

成果物（`artifacts/`）

ログ（`logs/`）

設定ファイル

各種コマンド

パイプライン実行

LLM ヘルスチェック（Ollama 接続と解決済みモデルの確認）

LLM ウォームアップ（大型ローカルモデルの事前起動）

public research ヘルスチェック（公開 API の設定・接続確認）

Semantic Scholar ローカル索引の作成

Semantic Scholar バックエンド単体確認

ダッシュボード起動

ディレクトリ構成

テスト

既知の制約

今後の改良候補

関連ドキュメント

Kuroko（特許出願支援のAIシステム）

Kuroko（黒衣）

目次

特徴

アーキテクチャ概要（back / gate / front）

セキュリティ方針

エージェント構成

パイプライン（処理フロー）

動作環境

インストール

パイプライン実行

ダッシュボード起動

よく使う確認コマンド

主な出力先

主な設定ファイル

デモ

入力データ・フォルダ

成果物データ

中間状態（state/）

成果物（artifacts/）

ログ（logs/）

設定ファイル

各種コマンド

パイプライン実行

LLM ヘルスチェック（Ollama 接続と解決済みモデルの確認）

LLM ウォームアップ（大型ローカルモデルの事前起動）

public research ヘルスチェック（公開 API の設定・接続確認）

Semantic Scholar ローカル索引の作成

Semantic Scholar バックエンド単体確認

ダッシュボード起動

ディレクトリ構成

テスト

既知の制約

今後の改良候補

関連ドキュメント

中間状態（`state/`）

成果物（`artifacts/`）

ログ（`logs/`）