Local Agent Forge

Local Agent Forge is a pre-release, source-available toolkit for probing local inference servers, classifying prompts with a deterministic heuristic, exposing experimental MCP tools, and recording runtime cost comparisons.

IMPORTANT

This repository is not a published or production-approved release. As checked on 2026-08-30, neither@nymrel/local-forge on npm nor local-agent-forge on PyPI exists. Use the source checkout for evaluation. Do not treat the package names, version, examples, or workflow definitions as evidence of a registry release, configured provider account, deployed service, available local model, customer activation, privacy certification, cost reduction, or revenue.

What is implemented

TypeScript adapters for Ollama, vLLM, LM Studio, ComfyUI, and Whisper-compatible HTTP servers.
A Python adapter surface for the same five endpoint families.
Deterministic prompt classification and routing-decision objects.
A local CLI, an experimental JSON-RPC/MCP server, and a loopback-only HTTP proxy.
Runtime token and cost-comparison ledgers.
Node and Python unit contracts plus deterministic npm and Python distribution validators.

The adapters default to loopback endpoints. A caller can supply a remote HTTP(S) endpoint, so local execution and data residency are never inferred from the adapter name. Custom endpoints are validated as credential-free HTTP(S) base URLs before requests are constructed.

Current boundaries

The 0.85 routing threshold is a hand-authored heuristic, not a benchmarked accuracy guarantee or a service-level objective.
A CLOUD routing decision is advisory metadata. It does not configure credentials, authorize spend, or execute a cloud-provider request.
Model identifiers in the current router are defaults and compatibility labels, not proof that a model is installed, current, licensed, or reachable.
Cost tables are illustrative comparison inputs. They may become stale and omit hardware, electricity, operations, provider discounts, and other real costs. Validate pricing and measured usage before relying on a comparison.
The MCP implementation exercises a bounded protocol surface and reports protocol version 2024-11-05; it is not an independent compatibility certification.
The test suites prove the checked contracts, not full behavioral parity, exhaustive security, or a coverage percentage.

Supported development floor

Runtime	Policy
Node.js	`>=22.19 <27`
npm	`>=11.5 <12` (repository pin: `11.19.1`)
Python	`>=3.11` (CI policy: 3.11 through 3.14)
TypeScript	Repository compiler pin: `5.9.3`

Evaluate from source

Node.js

npm ci --ignore-scripts --no-audit --no-fund
npm run check
node .\bin\local-forge.js help

Useful source-checkout commands:

node .\bin\local-forge.js health
node .\bin\local-forge.js route "Summarize this function"
node .\bin\local-forge.js start --port 4000
node .\bin\local-forge.js mcp

The proxy listens on 127.0.0.1 by default. Stop it when evaluation is complete.

Python

python -m unittest discover -s tests -p test_*.py
python -m build --outdir python-dist
python scripts\check_python_package.py python-dist
python -m pip install --force-reinstall .\python-dist\*.whl
local-forge-py --help

These are local source-build instructions. They are not registry installation instructions.

Security model

The HTTP proxy binds to IPv4 loopback only.
Default adapter endpoints use 127.0.0.1.
Custom adapter endpoints must be absolute http: or https: URLs without embedded credentials, query strings, or fragments.
URL validation is a syntax boundary, not a trust decision or a complete SSRF defense. Treat every configured endpoint as a data recipient and apply host, network, and egress policy appropriate to the deployment.
Local inference servers can have their own authentication, logging, persistence, plugin, model, and network behavior. Audit them separately.
MCP clients can invoke tools with sensitive prompts. Review client permissions and tool exposure before enabling the server.

See SECURITY.md for reporting and supported-boundary details.

Package and release policy

npm run check:package proves the npm archive allowlist. python scripts/check_python_package.py python-dist proves the wheel and source-archive contracts. Publication remains manual, existing-tag-only, main-ancestry-gated, checksum-producing, attested, and OIDC-only in the workflow definition.

Those controls do not prove that npm or PyPI trusted publishing, GitHub environments, repository Actions, ownership, or release approval are configured. RELEASE_READINESS.md is the release gate.