puda

PUDA のコンテキスト

PUDA（Physical Unified Device Architecture）は、ハードウェアや LLM に依存しない、フィジカル AI 向けのランタイムです。AI エージェントとソフトウェアシステムに、物理マシンを制御するための統一された検証可能な制御プレーンを提供し、高レベルのエージェントロジックと低レベルのマシン実行を分離します。

PUDA は大まかに言うと、NATS を中心としたメッセージ駆動型アーキテクチャ、エージェントと人間向けの CLI ファーストなインターフェース、実験やワークフローの実行に使う宣言型プロトコル、コマンドをネイティブなマシンドライバーの呼び出しに変換するエッジサービス、コマンドとデータの来歴を保持するプロジェクト記録を採用しています。PUDA は、計画、マシン制御、実行ログ、生成レポートをつなぐ、エージェントネイティブなブリッジとして扱ってください。

PUDA、セットアップ、その他の質問について詳しくは、https://docs.puda.co/llms.txt を参照してください。

puda のセットアップ

1. CLI のインストール：puda がインストールされ、グローバルに実行できるよう PATH に含まれていることを確認してください。見つからない場合は、Puda のリリースページからお使いのプラットフォーム用のバイナリをダウンロードしてインストールし、PATH に追加してください。
2. 依存関係の確認：python3、pip、npx が利用可能であることを確認し、見つからない場合は先にインストールしてください。
3. ログイン：ユーザー名がまだわからない場合は、ユーザーに確認してください。推測してはいけません。puda login -u <username> でログインします。
4. NATS プロファイルの選択：puda profile list と puda profile current を確認してください。既存の適切なプロファイルがある場合は、puda profile switch <name> で切り替えます。新しいプロファイルを作成する場合は、ユーザーまたはデプロイ設定からプロファイル名とブローカー URL を取得してください。ラボ環境を推測してはいけません。平文の場合：puda profile add <name> --servers <nats-urls>。暗号化する場合：puda profile add <name> --servers <tls-urls> --ca <local-ca-path> --key <local-key-path>。暗号化された CLI プロファイルでは、両方のファイルが必要です。プロファイルが選択されていない場合は、最初のプロファイルが自動的に有効になります。それ以外の場合は、使用するプロファイルに明示的に切り替えてください。接続の設定または移行については、CLI プロファイルとテレメトリを参照してください。
5. スキルのインストール：puda skills install を実行して、puda 用のエージェントスキルをインストールします。

プロジェクトのセットアップ

puda init を実行します（例：puda init . または puda init <folder_name>）。

puda のセットアップとプロジェクトの初期化が完了してから、プロトコルの生成、マシンへのコマンド送信、実験ワークフローに進んでください。

CLI 0.1.x の設定とマシンの調査

puda --version と各コマンドの --help を使って、インストールされているインターフェースを確認してください。このスキルの対象は CLI 0.1.3 です。Python SDK のバージョンは別で、0.0.21 です。

• puda config list/get/set で管理できるのは、user.user_id と user.username のみです。ブローカー URL とセキュリティ関連のパスは puda profile で管理し、プロジェクト設定は puda project config で管理します。削除された puda config set nats_servers のワークフローは使用しないでください。
• puda machine list は応答するマシンを検出します。puda machine info <id>（エイリアスは ping）は、ライブステータス、SDK のバージョン、登録済みのライブストリーム、公開されているテレメトリストリームを返します。results[].tlm_streams[].subject を確認してください。マシン名だけからストリームの存在を推測してはいけません。
• puda machine watch <full-subject> --timeout 15 は、ライブトラフィックを監視します。puda.first.tlm.stream.pos のような、公開されているサブジェクトを使用してください。位置引数はマシン ID ではなくサブジェクトです。特定のマシンのすべてのトピックを監視するには、サブジェクトの代わりに --machines first,balance を使用してください。
• プロファイルとマシンの調査結果はデフォルトで JSON 形式です。watch は NDJSON を出力します。テキスト出力が必要な場合にのみ --human を使用してください。調査には時間制限付きの watch を優先し、継続的な watch は要求された場合に使用してください。これらの読み取り専用コマンドでは、プロジェクトの初期化やマシンの実行開始は必要ありません。

プロファイルの移行、編集可能な設定項目、マシン情報の出力、watch のワイルドカード、ハートビートのフィルタリング、サブジェクトの例については、CLI プロファイルとテレメトリを参照してください。

プロジェクトフォルダーの構成

.
├── project.md                        # single source of truth (puda-memory skill)
├── protocols/                        # generated protocol files (puda-protocol skill)
├── puda.config                       # puda config file
└── puda.db                           # puda database file

Clock sync (Chrony / NTP)

PUDA のタイムスタンプ、検出リース、実験の来歴情報は、ホストの時計に依存します。サイトまたはエッジホストをセットアップするとき、または時計、Chrony、NTP について話題になったときは、references/chrony.md を読んでください。エッジホストでは、サイトの NTP サーバーの IP をユーザーに尋ね、scripts/sync-clock.sh または scripts/sync-clock.ps1 を実行してください。IP を決めつけないでください。エッジコンテナ内で Chrony を実行しないでください。

Livestream (USB / IP cameras)

マシンホストに USB カメラ、ウェブカメラ、または IP カメラがあり、オペレーターがライブ映像を必要としている場合は、references/livestream.md を読んでください。PUDAP/livestream を使用してください。

ユーザーに尋ねる項目は、カメラ（USB の /dev/video* パスまたはネットワークの rtsp:// URL）、ライブストリーム名、短い説明、MediaMTX のホスト（MagicDNS、Tailscale IP、または Tailscale を使わない場合はマシンの IP）、このフィードを使用するマシン ID（1 つまたは複数）です。これらを決めつけないでください。その後、Docker スタックを起動し、puda livestream add --name --host --description --machines で登録してください。ライブストリームはフリートのレコードであり、エッジ設定ではありません。

Updating puda skills

puda スキルを更新または再取得するには：

puda skills update