Forge: 自己ホスト LLM のツールコール向け信頼性レイヤー

Forge は、ガードレール（救援パース、リトライ誘導、ステップ強制）およびコンテキスト管理（VRAM 対応予算、階層圧縮）により、8B パラメータのローカルモデルをマルチステップエージェントワークフローにおいて同クラスの頂点へと引き上げます。現在の上位自己ホスト構成（llama-server を介した Ministral-3 8B Instruct Q8）は、Forge の 26 スケナリオからなる評価スイート全体で**86.5%のスコアを記録し、特に難易度が高いティアでは76%**という成績を出しています。

利用方法

• WorkflowRunner ツールを定義し、バックエンドを選択して構造化されたエージェントループを実行します。Forge はシステムプロンプト、ツール実行、コンテキスト圧縮、およびガードレールのライフサイクル全体を管理します。SlotWorker は、専用ワークフローが共有推論スロットを優先順位付けされたアクセス権を得るためのオートプリエメプション機能を提供し、専門領域のワークフローが GPU スロットを共有するマルチエージェントアーキテクチャにおいて特に最適です。Forge を直接構築する場合に最も適しています。
• Guardrails Middleware 独自のオーケストレーションループ内で Forge の信頼性スタック（合成可能ミドルウェア）を使用します。ループの制御はユーザー自身が行いますが、Forge がレスポンスを検証し、不適切なツールコールを救援し、必須のステップを強制します。
• Proxy Server 任意のクライアント（opencode、Continue、aider など）とローカルモデルサーバーの間で動作する OpenAI 互換のプラグアンドプレイプロキシです（

  python -m forge.proxy

  ）。これは透明にガードレールを適用し、クライアントはより賢いモデルと話しているかのように錯覚させます。

サポートされているバックエンド

• Ollama
• llama-server (llama.cpp)
• Llamafile
• Anthropic

要件

• Python 3.12 以上
• 動作する LLM バックエンド（下記参照）

インストール

# コア機能のみ
pip install forge-guardrails

# Anthropic クライアントを含む
pip install "forge-guardrails[anthropic]"

開発環境用

git clone https://github.com/antoinezambelli/forge.git
cd forge
pip install -e ".[dev]"

バックエンドのセットアップ（いずれかを選択）

1. llama-server（推奨） 上位 10 の評価構成はすべて llama-server で動作します。 https://github.com/ggml-org/llama.cpp/releases よりインストールしてください。

llama-server -m path/to/Ministral-3-8B-Instruct-2512-Q8_0.gguf --jinja -ngl 999 --port 8080

2. Ollama（代替） セットアップが容易ですが、ハードなワークロードではやや性能が劣ります。 https://ollama.com/download よりインストールしてください。

ollama pull ministral-3:8b-instruct-2512-q4_K_M

3. Anthropic（API） ローカル GPU が不要です。 完全な手順とモデルガイドについては Backend Setup を参照してください。

pip install -e ".[anthropic]"
export ANTHROPIC_API_KEY=sk-...

クイックスタート

import asyncio
from pydantic import BaseModel, Field
from forge import (
    Workflow, ToolDef, ToolSpec,
    WorkflowRunner, OllamaClient,
    ContextManager, TieredCompact,
)

def get_weather(city: str) -> str:
    return f"72°F and sunny in {city}"

class GetWeatherParams(BaseModel):
    city: str = Field(description="City name")

workflow = Workflow(
    name="weather",
    description="都市の天気を見付ける。",
    tools={
        "get_weather": ToolDef(
            spec=ToolSpec(
                name="get_weather",
                description="現在の天気を取得する",
                parameters=GetWeatherParams,
            ),
            callable=get_weather,
        ),
    },
    required_steps=[],
    terminal_tool="get_weather",
    system_prompt_template="あなたは親切なアシスタントです。利用可能なツールを使用してユーザーの質問に答えましょう。",
)

async def main():
    client = OllamaClient(
        model="ministral-3:8b-instruct-2512-q4_K_M", 
        recommended_sampling=True
    )
    ctx = ContextManager(strategy=TieredCompact(keep_recent=2), budget_tokens=8192)
    runner = WorkflowRunner(client=client, context_manager=ctx)
    await runner.run(workflow, "パリではどのような天気ですか？")

asyncio.run(main())

• マルチステップワークフロー、複数ターン会話: ユーザーガイドをご覧ください。
• 長時間稼働セッション (CLI、チャットサーバー、音声アシスタント): トランジェントなメッセージのフィルタリングに関する指針については、長時間稼働セッションのアドバイスをご覧ください。

プロキシサーバー

ローカルモデルサーバーのドロップイン代替品です。任意の OpenAI 互換クライアントをこのプロキシに指向するだけで、Forge のガードレールが無料で提供されます。

外部モード

llama-server

python -m forge.proxy --backend-url http://localhost:8080 --port 8081

マネージドモード

Forge が

llama-server

python -m forge.proxy --backend llamaserver --gguf path/to/model.gguf --port 8081

設定: クライアントの設定で API ベース URL を

http://localhost:8081/v1

合成レスポンスツールに関する注意: リクエストにツールが存在する場合、プロキシは自動的に人工的な

respond

respond(message="...")

respond

finish_reason: "stop"

バックエンド比較表

--jinja

インストールとモデルの選定については、Backend Setup と Model Guide を参照してください。

テストの実行

python -m pytest tests/ -v --tb=short
python -m pytest tests/ --cov=forge --cov-report=term-missing

評価ハネス

モデルとバックエンドの組み合わせが、マルチステップツールコールワークフローをどの程度信頼性を持ってナビゲートできるかを測定する 26 のシナリオ。これを OG-18 ベースラインティアと、上位分離用の 8 シナリオからなる advanced_reasoning ティアに分けています。完全な CLI リファレンスについては Eval Guide を参照してください。

単一実行

python -m tests.eval.eval_runner \
  --backend llamafile \
  --llamafile-mode prompt \
  --gguf "path/to/Ministral-3-8B-Instruct-2512-Q8_0.gguf" \
  --runs 10 \
  --stream \
  --verbose

バッチ評価（JSONL 出力、自動再開）

python -m tests.eval.batch_eval --config all --runs 50

レポート（ASCII テーブル、HTML ダッシュボード、Markdown ビュー）

python -m tests.eval.report eval_results.jsonl

プロジェクト構造

• src/forge/

  • __init__.py

    : パブリック API エクスポート

  • errors.py

    : ForgeError 階層

  • server.py

    :

    setup_backend()

    、

    ServerManager

    、

    BudgetMode

  • core/

    • messages.py

      : Message, MessageRole, MessageType, MessageMeta

    • workflow.py

      : ToolSpec, ToolDef, ToolCall, TextResponse, Workflow

    • inference.py

      :

      run_inference()

      — 共通の前半部分（圧縮、フォールド、検証、リトライ）

    • runner.py

      :

      WorkflowRunner

      — エージェントループ

    • slot_worker.py

      :

      SlotWorker

      — 優先順位付けされたスロットアクセス

    • steps.py

      : StepTracker

  • guardrails/

    • nudge.py

      : Nudge dataclass

    • response_validator.py

      : ResponseValidator, ValidationResult

    • step_enforcer.py

      : StepEnforcer, StepCheck

    • error_tracker.py

      : ErrorTracker

  • clients/

    • base.py

      : ChunkType, StreamChunk, LLMClient プロトコル

    • ollama.py

      : OllamaClient (ネイティブ FC)

    • llamafile.py

      : LlamafileClient (ネイティブ FC またはプロンプト注入方式)

    • anthropic.py

      : AnthropicClient (フロンティアベースライン)

  • context/

    • manager.py

      : ContextManager, CompactEvent

    • strategies.py

      : CompactStrategy, NoCompact, TieredCompact, SlidingWindowCompact

    • hardware.py

      : HardwareProfile,

      detect_hardware()

  • prompts/

    • templates.py

      : ツールプロンプトビルダー（プロンプト注入経路）

    • nudges.py

      : リトライおよびステップ強制用のナudge テンプレート

  • tools/

    • respond.py

      : 人工的なレスポンスツール (

      respond_tool()

      、

      respond_spec()

      )

  • proxy/

    • proxy.py

      : ProxyServer — プログラマティックな起動/停止 API

    • server.py

      : ラフ asyncio HTTP サーバー、SSE ストリーミング

    • handler.py

      : リクエストハンドラ — HTTP と

      run_inference

      の間のブリッジ

    • convert.py

      : OpenAI メッセージ ↔ Forge メッセージの変換

• tests/

  • unit/

    : 865 つの決定論的テスト — LLM バックエンドなしで実行可能

  • eval/

    : 評価ハネス — 実際のバックエンドに対するモデル資格確認

ドキュメント

• ユーザーガイド: 使用パターン、複数ターン、コンテキスト管理、ガードレール、スロットワーカー、長時間稼働セッションアドバイス。
• モデルガイド: ハードウェアに最適なモデルとバックエンド。
• バックエンドセットアップ: バックエンドインストールとサーバーセットアップ。
• 評価ガイド: 評価ハネス CLI リファレンス、バッチ評価。
• アーキテクチャ: 完全な設計ドキュメント。
• ワークフロー内部機構: ワークフロー設計およびランナー内部機構。
• コントリビュート: セットアップ方法、テスト実行、新規バックエンドまたはシナリオの追加方法。

論文

Forge ガードレールフレームワークとアブレーションスタディは、以下の通り発表されました：

Zambelli, A. Forge: A Reliability Layer for Self-Hosted LLM Tool-Calling. https://doi.org/10.1145/3786335.3813193

事前公開のプリプリント版も

docs/forge_ieee_preprint.pdf

ライセンス

MIT — Copyright (c) 2025-2026 Antoine Zambelli