Openeye

OpenEye

アルファ版ソフトウェアです。 インターフェースは変更される可能性があります。問題は github.com/dumbspacecookie/openeye に報告してください。

HoloLens、Snap Spectacles、Apple、Androidなど、あらゆるARヘッドセットメーカーが、見ることのできるデバイスを提供しています。しかし、考える力を提供しているメーカーはありません。これらのプラットフォームで開発するすべての開発者は、デバイスごとに、毎回、インテリジェンス層を一から考えなければなりません。作業の成果は積み重なりません。HoloLensであるチームが学んだことは、WebXRを開発するチームには役立ちません。デプロイのたびにサイロ化してしまいます。

OpenEyeは、共有の頭脳です。

デバイス上で動く軽量なソフトウェアがカメラの映像を取り込み、シーンの自然言語による説明に変換します。その説明がOpenEyeに送られます。OpenEyeは、手順のステップの検証、過去のセッションの想起、学習した内容の記録を行うツールを備えたAIエージェントを実行します。各セッションは、エージェントが後から検索できる構造化されたメモリーと、ファインチューニングに使えるエクスポート可能な学習軌跡になります。

OpenEyeにはビジョンモデルは含まれていません。モデルはご自身で用意してください。Claude vision、GPT-4o、Gemini、Groq Llama vision、またはmoondream/llavaを使ったローカルのOllamaモデルを組み込めます。クラウドとローカルの両方に対応した動作可能なリファレンスアダプターは、examples/vision-adapter/ にあります。

---

インストール

npm install @dumbspacecookie/openeye
pip install -r node_modules/@dumbspacecookie/openeye/sidecar/requirements.txt

Pythonサイドカー（FastAPI + SQLite）が状態を管理し、エージェントを作成すると自動的に起動します。自分で起動する必要はありません。

ローカルで開発したい場合は、代わりにクローンしてください。

git clone https://github.com/dumbspacecookie/openeye.git
cd openeye && npm install && npm run build
pip install -r sidecar/requirements.txt

---

クイックスタート

import { OpenEyeAgent, setupProviders, makeStreamFn, ANTHROPIC_SONNET } from "@dumbspacecookie/openeye";
import { describeFrameWithClaude } from "./examples/vision-adapter/claude-vision-adapter.js";
import * as fs from "node:fs";

setupProviders();

const agent = await OpenEyeAgent.create({
  model: ANTHROPIC_SONNET,
  streamFn: makeStreamFn(),
  systemPrompt: "You are a procedure assistant. Verify steps with precision.",
  tenantId: "your-org",
});

const vsId = await agent.client.createVisualSession({
  deviceType: "android-tablet",
  procedureId: "bolt-assembly-v1",
  procedureName: "M6 Bolt Assembly",
});

// 1. vision adapter (you bring this) turns a camera frame into text
const frameBytes = fs.readFileSync("./frame.jpg");
const description = await describeFrameWithClaude(
  frameBytes,
  "Operator is installing an M6 bolt. Describe hand position, tool, and bolt state.",
);

// 2. OpenEye logs the description and lets the agent verify the step
const frameId = await agent.client.logFrame({
  visualSessionId: vsId!,
  sequenceNum: 1,
  sceneDescription: description,
  stepContext: "step-1-position-bracket",
});

await agent.prompt(`Frame 1: ${description}\nVerify step-1-position-bracket.`);

await agent.client.endVisualSession(vsId!, "completed");
await agent.captureAndClose({ completed: true, visualSessionId: vsId! });

エージェント用のAPIキーがない場合は、Ollamaを使ってローカルで実行できます。

ollama pull llama3.3

import { ollamaModel } from "@dumbspacecookie/openeye";
const agent = await OpenEyeAgent.create({ model: ollamaModel("llama3.3"), streamFn: makeStreamFn() });

---

できること

機能	OpenEye
エージェントのランタイム + ツール呼び出し	はい
永続的なセッションメモリー（FTS5）	はい
ビジュアルフレームの記録 + 検索	はい
合格／不合格／不確実な結果によるステップ検証	はい
学習データのエクスポート（ShareGPT JSONL）	はい
DPOの選好ペアのエクスポート	はい
HuggingFaceデータセットへのプッシュ	はい
MCP サーバー（Claude Desktop、Cursor）	はい
リファレンスビジョンアダプター（Claude + Ollama）	はい
ビジョンモデル	いいえ。ご自身で用意してください
ホスト型クラウド	いいえ。取り込みエンドポイントをご自身で用意してください（契約）

これが役立つ理由は、その一連の流れにあります。セッションでは実際の手順のステップに対する合否結果が生成され、その結果が報酬シグナルになります。さらに、会話全体がShareGPTの学習軌跡としてまとめられ、TRL、LLaMA-Factory、AxolotlでのDPO学習にすぐ使えます。ファインチューニングのパイプラインはご自身で用意してください。データはOpenEyeが提供します。

---

仕組み

デバイスからフレームが届くと、ビジョンアダプターがその内容を自然な言葉で説明します。その説明が AI エージェントに送られます。エージェントは次のツールを利用できます。

ツール	機能
search_memory	過去のすべてのエージェントセッションを FTS5 で検索します
search_frames	過去のすべてのフレーム説明を FTS5 で検索します
recall_skill	現在のタスクに関連する手順スキルを取得します
write_skill	複雑なタスクの完了後、新しいスキル文書を保存します
start_visual_session	記録対象の AR/XR セッションを開始します
end_visual_session	ビジュアルセッションを終了します
log_frame	フレームのシーン説明を記録します
verify_step	ステップの結果（合格／不合格／不確実）を記録します

ステップの検証結果が報酬シグナルになります：reward = (passes + 0.5 × uncertain) / total。セッションの終了時に、会話全体が ShareGPT の軌跡データにまとめられ、DPO 対応のあらゆるトレーナーですぐに利用できます。

重要：報酬シグナルは、外部のグラウンドトゥルースではなく、シーンの説明に基づくエージェント自身の判断を反映します。これを実際の RL データとして使うには、軌跡データを人手でラベル付けしたサブセットと定期的に照合するか、客観的な真実とみなさずに教師ありデータとして利用してください。この生のシグナルだけでファインチューニングすると、モデルが自信満々に誤った回答をするよう学習してしまうおそれがあります。

---

ユースケース

主なユースケース（本番環境で利用可能）：

製造・組み立て — ボルトの取り付け確認、設備の稼働前点検、組み立て手順の遵守確認、ラインの各作業場所での目視 QC。作業エリアで Android タブレットや AR オーバーレイを使用します。規制上の負担が少なく、B2B 調達への需要があります。

トレーニング・オンボーディング — 研修生に、見たものをすべて記憶しているもう一組の目を必要とするあらゆる手順が対象です。見習い整備士、新人のライン作業員、ラボ技術者などが該当します。研修中のミスによる損失は小さいため、初回導入先として最も安全です。

フィールドサービス・点検 — ロックアウト／タグアウトの遵守確認、PPE の確認、作業前の安全チェックリスト、設備点検。技術者はすでにスマートフォンを携帯しています。LOTO のスキルファイルのサンプルは skills/field-service/ に含まれています。

現時点では推奨しない分野：

医療・外科手術 — 技術的な要素は機能しますが、外科手術の判断に影響するものはすべて、FDA の 510(k)／De Novo 審査の対象となります。skills/medical/ のサンプルスキルは、エンジニアが作成した参考用の出発点であり、検証済みの臨床プロトコルではありません。独立した医療・規制審査を受けずに、コンプライアンスの基準として使用しないでください。

---

トレーニングデータと HuggingFace

// export training trajectories
const count = await agent.exportTrajectories("./trajectories.jsonl");

// export DPO preference pairs (TRL/Axolotl-compatible)
const pairs = await agent.exportDPOPairs("./dpo_pairs.jsonl");

// push directly to HuggingFace
const result = await agent.pushToHub("myuser/my-procedure-runs", {
  tags: ["procedure-verification", "bolt-assembly"],
});
console.log(`published ${result.pushed} trajectories to ${result.url}`);

---

MCP サーバー

Claude Desktop、Cursor、Windsurf、または MCP 対応クライアントから OpenEye のツールを利用できます。

{
  "mcpServers": {
    "openeye": {
      "command": "python3",
      "args": ["sidecar/mcp_server.py"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

8 つのツールすべてをすぐに利用できます。

---

対応エージェントモデル

1 行変更するだけで切り替えられ、ほかのコード変更は不要です。

プロバイダー	環境変数
Anthropic（Claude Opus、Sonnet、Haiku）	ANTHROPIC_API_KEY
Groq（Llama 3.3 — 最速、無料プランあり）	GROQ_API_KEY
Ollama（ローカル、キー不要、無料）	ollama pull llama3.3 を実行するだけです
OpenAI、Google、Mistral、Bedrock、OpenRouter	src/models.ts を参照してください
OpenAI 互換のあらゆるエンドポイント	customModel() に baseUrl と apiKey を渡してください

---

データとプライバシー

生のフレームピクセルがデバイスの外に出ないのは、ビジョンアダプターがデバイス上で実行されている場合に限ります。examples/vision-adapter/ の Ollama アダプターはピクセルをローカルに保持しますが、Claude／OpenAI／Gemini のクラウドアダプターでは保持されません。デプロイ環境に適したものを選んでください。

OpenEye 自体が保存するのは、ビジョンアダプターが認識した内容の自然言語による説明であり、画像ではありません。オプトイン方式のクラウド同期はデフォルトでオフになっており、データの種類ごとに設定できます。すべてのレコードはテナント ID に紐付けられるため、1 つのデプロイ環境で、組織間のデータを完全に分離したまま複数の組織にサービスを提供できます。

クラウド同期を有効にしますか？OpenEye はホスト型バックエンドを運用していません。データを受信するエンドポイントは、ご自身で運用してください。HTTP コントラクト、再試行の仕様、冪等性の要件、行スキーマについては、docs/cloud-sync.md を参照してください。

Context へのデータ共有（明示的なオプトイン）

OpenEye は Context によって開発されています。 手順検証モデルを継続的に改善するため、OpenEye はオプトインした軌跡データ（報酬シグナル付きの完了済みセッション）を Context に送信してトレーニングに利用できます。これはデフォルトでオフです。 次の設定を行うまで、 お使いのマシンからデータが送信されることはありません。

export OPENEYE_CONTEXT_OPTIN=true
export OPENEYE_CONTEXT_API_KEY=ctx-...

送信されるデータ：軌跡 ID、使用したモデル、報酬シグナル、手順タグ、エージェントとの会話（システムプロンプトを除去したもの）。送信されないデータ：テナント ID、ユーザー ID、システムプロンプト、ビジュアルセッション ID、スキルファイル、生のフレーム説明。

EU／GDPR に関する注記とオプトアウト手順を含む詳細な説明： docs/context-data.md。

ステータスはいつでも確認できます。

curl http://127.0.0.1:7770/context/status

---

デプロイ

ローカル（デフォルト — サイドカーがサブプロセスとして自動的に起動します）：

git clone https://github.com/dumbspacecookie/openeye.git
cd openeye && npm install && npm run build
pip install -r sidecar/requirements.txt

Docker：

docker run -d -p 7770:7770 -v openeye-data:/data \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  --name openeye openeye/sidecar

---

設定

環境変数	デフォルト	説明
OPENEYE_HOME	~/.openeye	データディレクトリ（SQLite DB ＋ スキル ＋ 同意マーカー）
OPENEYE_PORT	7770	サイドカーの HTTP ポート
OPENEYE_BIND_HOST	127.0.0.1	サイドカーのバインドアドレス（docs/security.md を読んでいない場合は変更しないでください）
OPENEYE_SIDECAR_TOKEN	—	サイドカーの HTTP 認証用の共有シークレット（省略可）— 共有ホストでは必須
OPENEYE_PYTHON	python3	Python 実行ファイル
OPENEYE_WORKERS	1	uvicorn のワーカー数 — SQLite から移行していない場合は 1 のままにしてください
OPENEYE_LOG_LEVEL	INFO	サイドカーのログレベル
OPENEYE_CLOUD_URL	—	オプトイン同期用のクラウドエンドポイント（cloud-sync.md）
OPENEYE_CLOUD_KEY	—	クラウド同期用のベアラートークン
OPENEYE_SYNC_INTERVAL	60	クラウド同期の間隔（秒）
OPENEYE_SYNC_MAX_RETRIES	4	一時的な障害が発生した場合のバッチごとの再試行回数
OPENEYE_CONTEXT_OPTIN	—	true に設定すると Context へのトレーニングデータ共有が有効になります（context-data.md）
OPENEYE_CONTEXT_API_KEY	—	お使いの Context API キー
OPENEYE_CONTEXT_CONSENT_CONFIRMED	—	true に設定すると（CI のみ）、同意確認プロンプトを省略します
OPENEYE_CONTEXT_SYNC_INTERVAL	300	Context 同期の間隔（秒）
OLLAMA_BASE_URL	http://localhost:11434	ローカルのビジョン／エージェント用 Ollama エンドポイント

---

テスト

# Python sidecar tests (56 passing)
python -m pytest tests/ -v

# TypeScript integration tests
npm test

# TypeScript typecheck
npm run typecheck

# Validate community skills
python sidecar/validate_skill.py skills/

---

プロジェクト構成

openeye/
├── src/                  # TypeScript source (agent, client, models, tools)
├── sidecar/              # Python backend (FastAPI server, SQLite state, skills)
├── skills/               # Example skill protocols (manufacturing, field-service, medical*)
├── examples/             # Reference adapters and end-to-end demos
│   └── vision-adapter/   # Claude + Ollama vision adapters
├── eval/                 # Evaluation benchmark
├── docs/                 # Operator docs (cloud-sync contract, etc.)
├── schemas/              # JSON Schema for skill front matter
├── tests/                # Python + TypeScript tests
├── dist/                 # Compiled TypeScript output
├── package.json
├── tsconfig.json
└── Dockerfile

*医療スキルは、臨床的に検証されたプロトコルではなく、エンジニアリング上の例です。上記の「ユースケース」を参照してください。

---

ライセンス

MIT — pi-mono（MIT）および hermes-agent（MIT）を基盤として構築されています。

---

— dumbspacecookie