forge

자체 호스팅(self-hosted) LLM 도구 호출(tool-calling)을 위한 신뢰성 계층(reliability layer)입니다. Forge는 가드레일(guardrails: 파싱 구조 복구(rescue parsing), 재시도 유도(retry nudges), 단계 강제(step enforcement))과 컨텍스트 관리(context management: VRAM 인지 예산(VRAM-aware budgets), 계층적 압축(tiered compaction))를 통해 8B 로컬 모델을 다단계 에이전트 워크플로우(multi-step agentic workflows)에서 동급 최상위 수준으로 끌어올립니다. 현재 가장 뛰어난 자체 호스팅 설정(llama-server 상의 Ministral-3 8B Instruct Q8)은 Forge의 26개 시나리오 평가 스위트(eval suite)에서 86.5%를 기록했으며, 가장 어려운 단계에서는 76%를 기록했습니다.

사용 방법 세 가지:

• WorkflowRunner — 도구를 정의하고, 백엔드(backend)를 선택하며, 구조화된 에이전트 루프(agent loops)를 실행합니다. Forge는 시스템 프롬프트(system prompts), 도구 실행(tool execution), 컨텍스트 압축(context compaction), 가드레일을 포함한 전체 라이프사이클을 관리합니다. SlotWorker는 자동 선점(auto-preemption) 기능이 있는 공유 추론 슬롯(inference slot)에 대한 우선순위 큐 기반 액세스를 추가합니다. 이는 전문화된 워크플로우가 GPU 슬롯을 공유하는 멀티 에이전트 아키텍처(multi-agent architectures)에 적합합니다. Forge를 직접 사용하여 구축할 때 가장 좋습니다.

• Guardrails middleware — 자체 오케스트레이션 루프(orchestration loop) 내에서 Forge의 신뢰성 스택(조합 가능한 미들웨어(composable middleware))을 사용합니다. 사용자가 루프를 제어하며, Forge는 응답을 검증하고, 잘못된 형식의 도구 호출(malformed tool calls)을 복구하며, 필수 단계를 강제합니다.

• 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                # 핵심 기능만 설치
pip install "forge-guardrails[anthropic]"   # + Anthropic 클라이언트 포함

개발용:

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

백엔드 설정 (Backend setup) (하나를 선택하세요)

llama-server (권장 — 상위 10개 평가(eval) 설정 모두 llama-server에서 실행됨):

# https://github.com/ggml-org/llama.cpp/releases 에서 설치
lama-server -m path/to/Ministral-3-8B-Instruct-2512-Q8_0.gguf --jinja -ngl 999 --port 8080

Ollama (대안 — 설정이 더 간편하지만, 어려운 워크로드(workloads)에서는 성능이 약간 낮음):

# https://ollama.com/download 에서 설치
ollama pull ministral-3:8b-instruct-2512-q4_K_M

Anthropic (API 사용, 로컬 GPU 불필요):

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

전체 지침은 백엔드 설정 (Backend Setup)을, 사용자의 하드웨어에 적합한 모델은 모델 가이드 (Model Guide)를 참조하세요.

빠른 시작 (Quick Start)

import asyncio
from pydantic import BaseModel, Field
from forge import (
...

다단계 워크플로(multi-step workflows), 다회차 대화(multi-turn conversations) 및 백엔드 자동 관리(backend auto-management)에 대해서는 사용자 가이드 (User Guide)를 참조하세요. 장기 실행 세션(CLI, 채팅 서버, 음성 비서)을 구축하는 경우, 일시적인 메시지(transient messages) 필터링에 관한 중요한 지침이 포함된 장기 실행 세션 권고 사항 (long-running session advisory)을 참조하세요.

프록시 서버 (Proxy Server)

로컬 모델 서버를 즉시 대체할 수 있는 도구입니다. OpenAI 호환 클라이언트를 이 프록시로 지정하기만 하면 Forge의 가드레일(guardrails)을 무료로 사용할 수 있습니다.

# 외부 모드 (External mode) — llama-server를 직접 관리하며, Forge가 이를 프록시합니다
python -m forge.proxy --backend-url http://localhost:8080 --port 8081

...

그런 다음 클라이언트의 API 기본 URL(API base URL)을 http://localhost:8081/v1로 설정하세요.

참고: 프록시(proxy)는 요청에 도구(tools)가 포함되어 있을 때 합성된 respond 도구를 자동으로 주입합니다. 모델은 일반 텍스트를 생성하는 대신 respond(message="...")를 호출하며, 이를 통해 Forge의 전체 가드레일(guardrail) 스택이 적용되는 도구 호출(tool-calling) 모드를 유지합니다. respond 호출은 외부로 나가는 응답에서 제거되므로, 클라이언트는 일반적인 텍스트 응답(finish_reason: "stop")을 받게 되며 해당 도구의 존재를 전혀 알 수 없습니다. 이는 텍스트와 도구 호출 사이에서 올바른 선택을 할 것이라고 신뢰하기 어려운 소규모 로컬 모델(~8B)에게 필수적입니다. 도구 사용을 유도하는 것은 반드시 필요합니다. 전체 분석 내용은 ADR-013을 참조하세요.

백엔드 (Backends)

백엔드	최적의 용도	네이티브 함수 호출 (Native FC)?
Ollama	가장 쉬운 설정, 모델 관리 기능 내장	예
...
설치 방법은 백엔드 설정 (Backend Setup)을, 어떤 모델을 선택할지는 모델 가이드 (Model Guide)를 참조하세요.

테스트 실행 (Running Tests)

python -m pytest tests/ -v --tb=short

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

평가 하네스 (Eval Harness)

모델과 백엔드 조합이 다단계 도구 호출(multi-step tool-calling) 워크플로우를 얼마나 안정적으로 수행하는지 측정하는 26개의 시나리오로 구성되어 있습니다. 이는 최상위 성능 구분을 위해 OG-18 베이스라인 티어와 8개 시나리오의 advanced_reasoning 티어로 나뉩니다. 전체 CLI 참조는 평가 가이드 (Eval Guide)를 참조하세요.

# llama-server (먼저 다른 터미널에서 시작하세요; 평가 가이드 참조)
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

...

프로젝트 구조 (Project Structure)

src/forge/
  __init__.py          # 공개 API 내보내기 (Public API exports)
  errors.py            # ForgeError 계층 구조 (ForgeError hierarchy)
...

문서 (Documentation)

문서 (Documentation)

• User Guide — 사용 패턴 (Usage patterns), 멀티 턴 (multi-turn), 컨텍스트 관리 (context management), 가드레일 (guardrails), 슬롯 워커 (slot worker), 장기 실행 세션 권고 사항 (long-running session advisory)
• Model Guide — 하드웨어에 적합한 모델 및 백엔드 (Which model and backend for your hardware)
• Backend Setup — 백엔드 설치 및 서버 설정 (Backend installation and server setup)
• Eval Guide — 평가 하네스 CLI 레퍼런스 (Eval harness CLI reference), 배치 평가 (batch eval)
• Architecture — 전체 설계 문서 (Full design document)
• Workflow Internals — 워크플로 설계 및 러너 내부 구조 (Workflow design and runner internals)
• Contributing — 설정, 테스트, 새로운 백엔드 또는 시나리오 추가 방법 (How to set up, test, and add new backends or scenarios)

논문 (Paper)

Forge 가드레일 프레임워크와 어블레이션 연구 (ablation study)는 다음과 같이 발표되었습니다:

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

출판 전 프리프린트 (preprint) 버전은 docs/forge_ieee_preprint.pdf에서 확인할 수 있으며, 이는 역사적 기록물 (historical artifact)로 보관됩니다. 위에서 언급한 출판된 버전을 인용하십시오. DOI 링크는 출판사의 출시 시점에 따라 즉시 연결되지 않을 수 있습니다.

라이선스 (License)

MIT — Copyright (c) 2025-2026 Antoine Zambelli