# NPC-Forge

> An open-source framework for building deterministic conversational agents with distinct personalities, multi-turn context, and tool-call support — no ML or LLMs required.

NPC-Forge is an open-source Python framework for building conversational agents that run entirely on the CPU, without relying on machine learning or large language models. Created by Giovanni Blu Mitolo and licensed under AGPL-3.0, it reached its first experimental release (version 0.0) in September 2026 and is actively developed with community contributions.

## What It Is

NPC-Forge sits in the category of deterministic conversational agent frameworks — a deliberate alternative to LLM-based chatbots. Instead of probabilistic model inference, it uses curated datasets and a rule-based NLU engine (FlintParser/FlintNPC) to produce agents with consistent, predictable behavior. Agents can handle multi-turn context, sentiment analysis, and tool calls, and they respond in milliseconds even on embedded systems or obsolete hardware.

## How the Deterministic Design Works

The framework's core philosophy is that many conversational problems don't require machine learning. Key design properties include:

- **No hallucination**: responses are fully determined by the dataset, not sampled from a model.
- **No safety alignment filters**: behavior is controlled entirely by the dataset author.
- **Typo and interjection tolerance**: the README states it handles typos, expletives, interjections, and word inversions better than NLP.js.
- **No training step**: update the dataset, run `npc-forge reboot`, and changes are live immediately.
- **OpenAI-compatible API**: the server exposes an endpoint compatible with tools like Open WebUI or GitHub Copilot, so NPCs can be dropped into existing LLM harnesses.

## TERMy — The Bundled Terminal Assistant

The first NPC shipped with the framework is TERMy, described as a "cynical, very knowledgeable, Turing-complete, Linux terminal assistant." TERMy translates natural language into shell commands without any neural network involvement. It also supports scripting: users can write a plain-English `.termy` file and pipe it to `termy -y` to transpile and execute a shell script automatically.

## CLI and Dataset Workflow

NPC-Forge ships a CLI for full lifecycle management of NPCs:

- `npc-forge list` — lists installed NPCs
- `npc-forge serve` / `stop` / `reboot` / `watch` — server lifecycle commands
- `npc-forge create` / `install <path>` — NPC creation and installation
- `npc-forge test` — runs the test suite

Datasets follow the NDF 0.0 (NPC-Forge Dataset Format) specification, documented in the repository. The quick-start path is a `git clone`, a setup script, and three commands — the README claims the full setup takes under sixty seconds.

## Current Status: Version 0.0 (Experimental)

The first release (0.0) was published on September 2, 2026. The README explicitly labels this an experimental release distributed "AS IS" without warranty, and notes that the current build works only on Linux and WSL. The repository had 252 stars and 15 forks as of late September 2026, with active pushes and open issues indicating ongoing development. Commercial licensing options are available directly from the author for organizations that need an exemption from the AGPL-3.0 terms.

## Features
- Deterministic conversational agents (no LLMs or ML)
- Multi-turn context support
- Sentiment analysis
- Tool-call support
- OpenAI-compatible API server
- CPU-only execution (no GPU required)
- Runs on embedded systems and obsolete hardware
- NDF 0.0 dataset format for easy NPC creation
- CLI for NPC lifecycle management
- TERMy bundled Linux terminal assistant
- Plain-English scripting via .termy files
- Typo and interjection tolerance
- No training step required
- AGPL-3.0 open-source license

## Integrations
Open WebUI, GitHub Copilot, OpenAI-compatible API harnesses

## Platforms
LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
0.0

## Links
- Website: https://github.com/gioblu/NPC-Forge
- Documentation: https://github.com/gioblu/NPC-Forge/tree/main/docs
- Repository: https://github.com/gioblu/NPC-Forge
- EveryDev.ai: https://www.everydev.ai/tools/npc-forge