NPC-Forge README

The project's README from github.com/gioblu/NPC-Forge. As one markdown file: README.md.

NPC-Forge Discord

NPC-Forge

NPC-Forge is a framework for building conversational agents with distinct personalities, multi-turn context, sentiment analysis, and tool-call support. NPCs run on the CPU (web browser or OS) even on embedded systems and obsolete hardware without relying on machine learning or LLMs.

Instead of praying for a model to do the right thing, you can now use NPC-Forge to quickly build a deterministic agent and hook it up to your favourite workflow, API or harness.

Why NPC-Forge?

Many problems you encounter can be solved without machine-learning or LLMs. NPC-Forge gives you a way to solve those problems more efficiently:

NPC-Forge CLI

Administer, install, and run your NPCs with the following terminal commands:

npc-forge list           # Lists the installed NPCs
npc-forge test           # Run NPC-Forge test suite
npc-forge serve          # Starts OpenAi/Copilot compatible API server
npc-forge stop           # Stops server
npc-forge reboot         # Reboots server
npc-forge watch          # Starts server and watch logs in real-time
npc-forge create         # Creates new NPC using the example profile
npc-forge install <path> # Installs a new NPC

Additional information can be found in the NPC-Forge CLI documentation.

TERMy terminal assistant

TERMy is the first NPC baked into the NPC-Forge framework. It is a cynical but very knowledgeable Linux terminal assistant that translates your natural language into shell commands without a single artificial neuron. Just type termy followed by your prompt:

Terminal demonstration

You can also write a script in plain english, create a file test.termy with the following content:

search on wiki the programma 101
append it to p101.txt
open it in the browser

Then digit termy -y < test.termy and watch TERMy transpile it to a Shell script and execute it.

[!TIP] If you want to expand the capabilities of TERMy check out the dataset directory and the TERMy documentation

Quick start to redemption

Reclaim control on your workflow in less than sixty seconds:

# Clone the forge from the cloud
git clone https://github.com/gioblu/NPC-Forge.git

# Step into the forge and install it
cd NPC-Forge && chmod +x setup.sh && ./setup.sh

# Install TERMy
npc-forge install npcs/termy

# Chat with TERMy
termy how are you

Consider that this experimental release of npc-forge works only on Linux and WSL.

[!WARNING] First experimental release of NPC-Forge distributed "AS IS" without any warranty, use it at your own risk.

Documentation

Contributing to the forge

I am developing NPC-Forge with the conviction that democratic and sustainable use of Artificial Intelligence can be achieved with deterministic designs driven by curated and tested datasets crafted by the community; if you can, help me out. NPC-Forge thrives on your contributions, the community grows stronger when you:

Or are you just going to sit there waiting for the water to reach the boiling point?

The following list contains the contributors; with their support, expertise, kindness and talent NPC-Forge and TERMy are getting better by the day: Fred Larsen, Kevin Mathis, Cristiano Pizzarelli, David Starkweather, SyN-droMe, AnonymousMonkeyNo12

License

Licensed under the AGPL-3.0, feel free to contact me directly for commercial licensing options. Let's see if your corporate checkbook can purchase an exemption.

NPC-Forge (gioblu/NPC-Forge)

Searching Database…

269 ·GitHub
NPC-Forge
What is this?NPC-Forge is an open-source neuro-symbolic framework for building conversational agents with distinct personalities, multi-turn context, sentiment analysis and tool-call support. Its agents run on the CPU without machine learning or LLMs.
Is it a framework I build on, or a finished assistant I can just run?It is a framework: you build and administer NPCs through the NPC-Forge CLI, writing their datasets in the NDF 0.0 format. It also ships with a ready-made assistant, TERMy, baked into the framework.
What's the fastest way to try it?Install it on Linux or WSL and follow the quick start, which the README says takes under sixty seconds; everything is administered through the NPC-Forge CLI's terminal commands. Then just type 'termy' followed by your prompt.
Does it run on macOS or Windows?Not natively: the current experimental release works only on Linux and WSL, and it is distributed AS IS with no warranty. And since agents are deterministic, they can't hallucinate — but they can only do what their dataset covers.
Is it free for commercial use?It is licensed under AGPL-3.0, so it is free for open-source use; for commercial licensing the author asks you to contact him directly.
Why did the author build deterministic agents instead of using LLMs?He argues many problems are solved more efficiently without machine learning, and that sustainable, democratic use of AI comes from deterministic designs driven by curated, community-tested datasets rather than hoping a model behaves.
How does it compare to NLP.js?Per the README, NPC-Forge tolerates typos, expletives, interjections and word inversions much better than NLP.js, while responding in milliseconds on the CPU.
How mature is the project?It is an early project: the current release is explicitly experimental and comes without warranty, but it already documents the CLI, API, FlintParser, FlintNPC, the NDF and TCS specs, and lists active contributors.
What are similar projects?Proteus, OpenIntelligentUI, turnstone, rasa, CopilotKit, aichat, tambo, agentscope
Which topics is it in?wsl, assistant, cpu, tool-calling, embedded-systems, lightweight, natural-language-processing, agent-framework, openai-compatible, nlp, agpl, chatbot
Creator
gioblu
Size
56.6 MB
Stars
269
Updated
CommitOct 14Release0.1Oct 07
Age
3mo
Commits · 90 Days