HumpBack / README.md
gregrsea's picture
HumpBack: add code tool calling (run_code, write_file), website generation, truthful docs, weights update
c7e559d
|
Raw History Blame Contribute Delete
3.05 kB
---
language: en
license: mit
tags:
- neural-network
- evolutionary
- metacognition
- tool-use
- 3-vector-weights
pipeline_tag: text-generation
---
# HumpBack: 3-Vector Neural Model (Python)
**A small, from-scratch neural architecture.** Not a wrapper around a pretrained model. Not an "agent" claiming self-awareness. It learns by storing facts, evolving connection weights, and calling tools when uncertain.
## What it actually is
- A graph of ~30 neurons, each with three weight vectors: **concept**, **spatial**, **temporal** (128 dimensions each).
- Hebbian plasticity + gradient-free genetic evolution optimize the graph.
- Associative memory stores facts via hashed text → vector retrieval.
- Metacognition assesses confidence; uncertainty triggers web search or code execution tools.
- All training data lives in `humpback/corpus.py` — no hidden internet training.
## What it can do
- Answer factual queries about its corpus (~98% recall after 5 epochs).
- Call tools: `calculator`, `read_file`, `list_dir`, `run_code`, `write_file`, plus optional web search.
- Generate code (fibonacci, sort, etc.) and run it through `run_code`.
- Create simple websites by writing HTML/CSS to disk via `write_file`.
- Persist/save/load full network state (`model.json`) and pack weights into `weights.zip`.
## Truthful limitations
- This is **not** a large language model. No transformers, no billion-parameter backbones.
- "Metacognition" is a confidence threshold over cosine similarity scores, not consciousness.
- Code generation uses pattern-matched templates from the training corpus, not deep reasoning.
- Self-consciousness is not claimed or demonstrated here. The science does not support it.
## Quick start
```bash
pip install -r requirements.txt
python -m humpback.server --host 127.0.0.1 --port 8000
```
Open http://127.0.0.1:8000
## API
| Endpoint | Method | Description |
|---|---|---|
| `/` | GET | Web UI (chat + viz) |
| `/v1/chat/completions` | POST | OpenAI-compatible chat |
| `/v1/models` | GET | List models |
| `/train` | POST | Run one evolution step, return stats |
| `/viz.png` | GET | Static network visualization |
| `/viz.html` | GET | Interactive D3.js graph |
## Training
```python
from humpback.agent import HumpbackModel
m = HumpbackModel()
m.train(epochs=5) # learns 62 facts → 98% recall
m.save("model.json")
m.evolution.evolve(steps=20)
```
Or from CLI:
```bash
python _train.py
```
## Tools
After training, you can query the model directly:
```python
result = m.think("make a website")
print(result["answer"]) # generates generated_site/index.html via write_file tool
result = m.think("run code fibonacci")
print(result["answer"]) # executes fibonacci, prints fib(10)=55
```
The same endpoints work over HTTP for automation.
## Architecture
See `humpback/server.py` for the web harness, `humpback/corpus.py` for training data, and `humpback/tools/registry.py` for the built-in tools. `generated_site/index.html` was produced by the model itself as proof of tool calling.
## License
MIT