Client インストール
Paprika に クライアント側から接続して使い始めます。SDK のインストール、ハブへの接続、最初のスクリプトまで 5 分です。サーバー自体を自前で立ち上げたい場合は Server インストール へ。
Paprika の動かし方
Paprika は 2 つの部分に分かれます。役割を分けて考えると分かりやすいです。
| これは何 | どう用意する | |
|---|---|---|
| 本体 | Hub・Worker・管理画面（ブラウザを動かすサーバ群） | Docker で起動 → Server インストール（5 分） / 構成パターンは サーバー構成 |
| SDK | paprika-client（本体を操作する Python / PHP ライブラリ） | このページ（pip install / composer require） |
本体を触らずに試すだけなら 管理画面（ブラウザだけで URL を投げて収集）から始めるのが一番手軽です。 このページは、稼働中のハブに対して スクリプトから操作する 人向けです。
SDK をインストール
必要なのは Python 3.10+ と、稼働中ハブへの到達性だけ（依存は httpx のみ）。
# ソースツリーから
pip install -e ./client/python
# または直接
pip install "git+https://github.com/paps-jp/paprika.git#subdirectory=client/python"必要なのは Python 3.10+ と、稼働中ハブへの到達性だけ（依存は httpx のみ）。
# ソースツリーから
pip install -e ./client/python
# または直接
pip install "git+https://github.com/paps-jp/paprika.git#subdirectory=client/python"必要なのは PHP 8.1+ と ext-curl、稼働中ハブへの到達性だけ。
composer require paprika/clientハブに接続
接続先は 引数 → 環境変数 PAPRIKA_HUB → http://localhost:8000 の順で解決されます。
引数なしの connect() にしておくと、ローカルでもサンドボックス内でも同じスクリプトが動きます。
export PAPRIKA_HUB=http://your-hub.example:8000import asyncio
from paprika_client import async_paprika
async def main():
async with async_paprika.connect() as cli: # PAPRIKA_HUB を自動参照
print(await cli.health())
# → {'ok': True, 'store': 'redis', 'workers': 25, 'lanes_busy': 3}
asyncio.run(main())from paprika_client import sync_paprika
with sync_paprika.connect() as cli: # PAPRIKA_HUB を自動参照
print(cli.health())
# → {'ok': True, 'store': 'redis', 'workers': 25, 'lanes_busy': 3}<?php
require 'vendor/autoload.php';
use Paprika\Client\Paprika;
$cli = Paprika::connect(); // PAPRIKA_HUB or http://localhost:8000
echo $cli->health(), "\n";最初のスクリプト
ページを開いてタイトルとリンクを取得する：
import asyncio
from paprika_client import async_paprika
async def main():
async with async_paprika.connect() as cli:
async with cli.session("https://news.ycombinator.com") as page:
print(await page.title())
# → "Hacker News"
for url in await page.links(urls_only=True):
print(url)
# → "https://news.ycombinator.com/item?id=12345"
# → "https://news.ycombinator.com/item?id=12346"
# → ... (ページ上の全リンク)
asyncio.run(main())async with cli.session(url) がブラウザのタブを 1 つ確保し、ブロックを抜けると自動で閉じます。
操作 API は Playwright とほぼ同じ（goto / click / fill / evaluate …）。一覧は API リファレンス。
from paprika_client import sync_paprika
with sync_paprika.connect() as cli:
with cli.session("https://news.ycombinator.com") as page:
print(page.title())
# → "Hacker News"
for url in page.links(urls_only=True):
print(url)
# → "https://news.ycombinator.com/item?id=12345"
# → ... (全リンクが順に出力される)with cli.session(url) がブラウザのタブを 1 つ確保し、ブロックを抜けると自動で閉じます。
await を外すだけで async 版と同じ API です。一覧は API リファレンス。
<?php
require 'vendor/autoload.php';
use Paprika\Client\Paprika;
$cli = Paprika::connect();
$job = $cli->fetch('https://news.ycombinator.com', scroll: true);
echo "status: {$job['status']}\n";
foreach ($cli->jobImages($job['job_id']) as $url) {
echo $url, "\n";
}PHP SDK は現在、Job API ＋ Session ライフサイクル（投入・状態取得・アセット・セッション開閉）まで対応しています。
Page 操作（$page->goto()・$page->click()・Locator チェーン等）と walk は順次対応中です。
当面 Page 操作が必要なときは Python 版または HTTP API をご利用ください。詳細は API リファレンス → PHP SDK。
await を外すだけの同期ファサード sync_paprika もあります（API → 同期版）。上のタブで「Python Sync」を選ぶと同期版のコード例が表示されます。コア概念
| 用語 | 意味 |
|---|---|
| Hub | 中央サーバ。ジョブを受け、ワーカーに配り、結果を集める。管理 UI / API もここ |
| Worker | Chrome を抱えたコンテナ。多数が並列で動く |
| Lane | 1 つの独立した Chrome（+ noVNC）。ワーカー 1 台に複数 |
| Session | 1 Lane の予約。cli.session() が握る対話的ブラウザ。タブ複数可 |
| Job | 「URL を収集する」作業単位。投入 → 実行 → 結果（assets） |
| Asset | 収集された 1 ファイル（画像 / 動画 / …）。Hub に集約される |
ジョブモード
ジョブ投入時に mode を選びます。options の全フィールド・既定値・制約は JobOptions リファレンス を参照してください。
| mode | 用途 |
|---|---|
fetch | 既定。URL を開いて画像/動画/HTML を取得。LLM 不要・最速 |
codegen-loop | 自然言語のゴール → LLM がスクリプト生成 → 実行 → 失敗時リトライ。CSS が効かない画面は page.agent()（Qwen-VL）をスクリプト内で呼べる |
rerun | 既存スクリプトをそのまま実行（Simple Macro が compile した Python もこれ） |
2 つの取得経路
「画像を取得する」には用途の違う 2 つの入口があります。混同しないようご注意ください。
| 経路 | 入口 | こういう時 |
|---|---|---|
| Job 経路 | cli.fetch() / cli.job_*() | URL を渡して一括取得（まとめ DL） |
| Session 経路 | cli.session() + page.*() | クリックやログインを挟んでから取得 |