Metadata-Version: 2.4
Name: recursive-adaptive-network
Version: 0.3.1
Summary: RAN: a from-scratch, non-Transformer, CPU-first neural architecture for people without GPUs -- now bundled with an extensible Agent/Tools/Memory/Skills framework (previously the separate ran-framework package).
Author: ZeroBoy
License: MIT
Project-URL: Homepage, https://github.com/REPLACE_ME/recursive-adaptive-network
Project-URL: Repository, https://github.com/REPLACE_ME/recursive-adaptive-network
Project-URL: Documentation, https://github.com/REPLACE_ME/recursive-adaptive-network/blob/main/docs/ARCHITECTURE.md
Project-URL: Bug Tracker, https://github.com/REPLACE_ME/recursive-adaptive-network/issues
Keywords: artificial intelligence,deep learning,neural network,cpu inference,low resource,recurrent neural network,adaptive computation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# RAN — Recursive Adaptive Network

**"AI pintar tidak boleh hanya bisa dibuat oleh orang yang memiliki GPU mahal."**

RAN is a from-scratch neural architecture and training framework built
as an alternative to the Transformer — no self-attention, no QKV — for
people whose only computer is a 2-4 core CPU laptop with 4-8GB of RAM
and no GPU.

Published as a single `recursive-adaptive-network` package on PyPI,
structured the same way `transformers` is: a `configuration_ran.py`
(hyperparameters only) separated from `modeling_ran.py` (the actual
architecture), a `RANConfig`/`RANModel` pair, and
`save_pretrained()`/`from_pretrained()` for a directory-based model
format.

**As of v0.2, this single package also bundles the Agent/Tools/Memory/Skills
framework** (`recursive_adaptive_network.framework`) that previously
shipped as a separate `ran-framework` package — `pip install
recursive-adaptive-network` now gives you both in one install, no
second `pip install` step needed. A small pretrained demo model is
bundled too (`RAN.from_pretrained("bundled-base")`), so you can try the
Agent immediately without training anything yourself first.

## Install

```bash
pip install recursive-adaptive-network
```

That's it — the only hard dependency is NumPy. No PyTorch, no CUDA.
(Until this is actually published to PyPI, see "Building and publishing
this package yourself" below to build and install it locally.)

## Quickstart: the Agent framework

```python
from recursive_adaptive_network import RAN, Agent
from recursive_adaptive_network.framework.tools import ToolRegistry
from recursive_adaptive_network.framework.tools.builtin import ALL_BUILTIN_TOOLS
from recursive_adaptive_network.framework.skills import SkillRegistry
from recursive_adaptive_network.framework.skills.builtin import ALL_BUILTIN_SKILLS

model = RAN.from_pretrained("bundled-base")  # small demo model, bundled in this package

tools = ToolRegistry()
for t in ALL_BUILTIN_TOOLS:
    tools.register(t)
skills = SkillRegistry()
for s in ALL_BUILTIN_SKILLS:
    skills.register(s)

agent = Agent(model, tools=tools, skills=skills)
print(agent.respond("halo"))
print(agent.respond("jam berapa sekarang?"))
print(agent.respond("hitung 12 * (3 + 4)"))
```

Swap `RAN.from_pretrained("bundled-base")` for your own trained model
(`RAN.from_pretrained("my_model_dir")`, or `RAN(parameters="10m")` +
`.train(...)`) once you're past trying the framework out — the bundled
demo model is intentionally small (see docs/BASE_MODEL.md) and not
meant for real use.

## Status: v0.2 (early, honest)

This is a real, runnable implementation, not a pseudocode sketch. It
has been tested end to end: forward pass, backward pass, gradient
flow through every learnable component, an overfitting sanity check
(loss goes down), checkpoint save/resume, a `save_pretrained`/
`from_pretrained` round-trip, and the Agent framework's tools/memory/
skills wiring. All of that is covered by the automated test suite in
`tests/` (70 tests, run with `pytest tests/`).

**What v0.2 is NOT (yet):**
- **Benchmarked against a Transformer, and the result favors the
  Transformer at this scale.** `benchmarks/ran_vs_transformer.py`
  compares RAN against a parameter-matched from-scratch Transformer
  decoder (both on the same Tensor/autograd engine, so implementation
  quality isn't a confound). On this sandbox's 1-core CPU: the

  Transformer is **15-23x faster**, uses **~4x less memory**, and
  reaches **lower training loss** after the same steps on the same
  corpus. Profiling traces the gap to Python-level overhead in RAN's
  per-token loop (hundreds of thousands of function calls for a
  64-token sequence), not to the arithmetic itself — see
  `docs/ROADMAP.md` for the full numbers and what would need to change
  (a compiled/vectorized inner loop) before re-testing this. **No
  "RAN is more efficient than X" claim is made anywhere in this
  repo** — if anything, the one real measurement done so far points
  the other way, at this scale, in this implementation.
- Not trained on any real corpus at a meaningful scale. The example
  training run in `examples/` uses a few sentences and will not
  produce coherent text — it exists to prove the pipeline works, not
  to demonstrate language ability.
- No C++ backend yet (pure Python + NumPy). INT8 quantization exists
  for checkpoint-size reduction only (`quantization/int8.py`, ~3.9x
  smaller files, no speed/RAM benefit — see its module docstring for
  why). No distributed CPU training, no Model Hub. See
  `docs/ROADMAP.md` for what's built vs. planned, mapped to the
  original spec.
- No PyTorch/CUDA dependency at all in v0.1 — every learnable op runs
  on a small NumPy-based autograd engine (`core/tensor.py`), which is
  actually a feature here: the "runs without a GPU" promise holds
  from the very first line of code, on machines where even installing
  a GPU-capable PyTorch wheel is impractical.

## Why not just run a Transformer on CPU?

Self-attention is O(n²) in sequence length. RAN instead maintains a
fixed-size recurrent **State Engine** (O(1) per token), a **learned,
multi-tier Adaptive Neural Memory** instead of a growing KV-cache, an
**Importance Gate** that decides how much compute/memory a piece of
information deserves, and a **Recursive Reasoning Core** with adaptive
halting so a simple prompt costs less compute than a complex one.
None of these use QKV attention. See `docs/ARCHITECTURE.md` for the
full pipeline and the reasoning behind each piece.

## Quickstart

### Command line

```bash
ran doctor                     # check what your hardware can handle
ran init my_project && cd my_project

ran tokenizer train --data data/corpus.txt --vocab-size 4096 --out tokenizer/tokenizer.json
ran model create --parameters 10m --tokenizer tokenizer/tokenizer.json --out model
ran train --model model --data data/corpus.txt --steps 500
ran run --model model --prompt "Halo dunia"
```

### High-level Python API

```python
from recursive_adaptive_network import RAN

model = RAN(parameters="10m")
model.train_tokenizer(open("corpus.txt").read())
model.train(dataset_path="corpus.txt", steps=500)
model.save_pretrained("my_model")

model2 = RAN.from_pretrained("my_model")
print(model2.generate("Halo dunia"))
```

### Direct architecture access (HuggingFace-style)

For custom training loops, research, or composing RAN's components
into something else — config and model are separate classes, the same
way `AutoConfig`/`AutoModel` are in `transformers`:

```python
from recursive_adaptive_network import RANConfig, RANModel
import numpy as np

config = RANConfig(vocab_size=4096, hidden_dim=128, state_dim=128,
                    memory_slot_dim=64, max_reasoning_steps=4)
model = RANModel(config)

tokens = np.random.randint(0, 4096, size=(2, 16))  # (batch, seq_len)
logits_list, final_state, info = model.forward_sequence(tokens)

model.config.save_pretrained("my_config")          # config.json only
config2 = RANConfig.from_pretrained("my_config")
```

## Repository layout

```
src/recursive_adaptive_network/
├── configuration_ran.py     RANConfig — hyperparameters only, no layers
├── modeling_ran.py           RANModel, RANForCausalLM — the architecture
├── modeling_state_engine.py  State Engine (recurrent, replaces attention)
├── modeling_memory.py        Adaptive Neural Memory (4 tiers)
├── modeling_routing.py       Importance Gate
├── modeling_reasoning.py     Recursive Reasoning Core (adaptive halting)
├── modeling_utils.py         save_pretrained() / from_pretrained()
├── tokenization_ran.py       Byte-level BPE tokenizer
├── legacy_format.py          backward-compat with the old single-file .ran format
├── api.py                    RAN — high-level convenience wrapper
├── core/                     Tensor autograd engine, nn.Module base
├── data/                     Streaming, low-RAM dataset loader
├── training/                 CPU-first Trainer, hardware detection
├── optimization/             Adam optimizer, loss functions
├── quantization/             (not yet implemented)
├── inference/                (not yet implemented beyond RAN.generate())
├── distributed/               (not yet implemented)
├── hub/                       (not yet implemented)
└── cli/                       `ran` command-line tool
tests/             36 automated tests
benchmarks/        Honest, uncompared performance measurements
docs/              Architecture notes and roadmap
```

## Building and publishing this package yourself

This repo is ready to build and upload, but actually publishing to
PyPI requires *your* PyPI account and API token — that step isn't
something anyone else can do on your behalf.

```bash
pip install build twine
python -m build                 # produces dist/*.whl and dist/*.tar.gz
python -m twine check dist/*    # validate metadata before uploading

# test on TestPyPI first (recommended)
python -m twine upload --repository testpypi dist/*
pip install --index-url https://test.pypi.org/simple/ recursive-adaptive-network

# then the real thing
python -m twine upload dist/*
```

You'll need a PyPI account (https://pypi.org/account/register/) and an
API token (Account Settings -> API tokens) — `twine upload` will
prompt for credentials, or read them from `~/.pypirc`. Before your
first real upload, double check:
- the package name `recursive-adaptive-network` is still unclaimed on
  PyPI (verified unclaimed as of this writing, but names can be taken
  at any time)
- `pyproject.toml`'s `[project.urls]` section — currently placeholder
  GitHub URLs (`REPLACE_ME`) that should point at your actual repo
  before publishing
- the version number in `pyproject.toml`, since PyPI does not allow
  re-uploading the same version number even if you delete a release

## A note on how this was built

Every architectural claim in this repo — "gradients flow through the
memory write gates", "loss decreases during training", "the model
generalizes across model sizes" — was checked by actually running the
code, not assumed from the design. Real bugs were caught and fixed
this way during development: memory writes that silently broke the
autograd graph, a recursive backward pass that crashed on long
sequences, and an exploding-gradient issue from an unbounded
backward-graph across training batches. See `docs/ROADMAP.md` for
details and `tests/` for the regression tests that now guard against
them recurring.
