Metadata-Version: 2.4
Name: orbyte-flow
Version: 0.1.0
Summary: OFA: foundation model architecture berbasis Flow Processing/Mixing/Gating (bukan Self-Attention), bisa diperluas via Knowledge/Skills/Tools/Memory tanpa retraining.
Author: ZeroAboy
License: MIT
Project-URL: Homepage, https://github.com/ZeroAboy/orbyte-flow
Project-URL: Repository, https://github.com/ZeroAboy/orbyte-flow
Keywords: deep-learning,pytorch,foundation-model,language-model,flow-based,non-attention,orbyte
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# Orbyte Flow (OFA)

Foundation model architecture yang **tidak menggunakan Self-Attention**
sebagai mekanisme utama. Dilatih sekali, dikembangkan pengguna lewat
Knowledge, Skills, Tools, Memory, dan RAG **tanpa retraining**.

> **Status: Alpha / eksperimen awal.** Implementasi ini adalah bukti-
> konsep yang sudah diuji end-to-end (forward pass, backward pass,
> training loop, adapter, memory, knowledge, tools, verification) --
> BUKAN model yang sudah dilatih pada corpus besar dan siap pakai
> untuk tugas bahasa umum. Melatih OFA-100M sampai benar-benar
> kompeten butuh dataset besar dan compute yang jauh melebihi cakupan
> pengerjaan ini.

---

## 1. Apa ini, apa BUKAN ini

**OFA ADALAH:**
- Arsitektur neural network yang dilatih lewat backpropagation biasa
  di PyTorch (bukan zero-training, bukan rule-based).
- Pengganti Self-Attention dengan mekanisme **Flow Processing + Flow
  Mixing + Gating** yang kompleksitasnya O(n) terhadap panjang
  sequence untuk bagian percampuran informasi (dibanding O(n²) di
  Self-Attention).
- Dirancang supaya kemampuan (knowledge, skill, tool, memory) bisa
  ditambah lewat **Python objects di runtime**, bukan lewat mengubah
  bobot -- sehingga tidak perlu retraining tiap kali menambah
  kemampuan.

**OFA BUKAN:**
- **BUKAN** klaim "lebih pintar" atau "lebih murah" dari Transformer.
  Belum ada benchmark yang membandingkan keduanya secara adil (dataset
  sama, compute budget sama, evaluasi sama). Lihat [`BENCHMARKS.md`](BENCHMARKS.md).
- **BUKAN** penemuan paradigma yang sama sekali belum pernah ada.
  Pendekatan "campur informasi lewat proyeksi/konvolusi terpelajar,
  bukan pairwise similarity" berada dalam keluarga konsep yang sama
  dengan **MLP-Mixer**, **gMLP**, dan **State-Space Model** (S4/Mamba).
  OFA adalah desain dan implementasi spesifik ORBYTE dalam keluarga
  ini, disusun dari nol untuk proyek ini -- bukan port langsung dari
  salah satu di atas.
- **BUKAN** model yang sudah dilatih dan siap pakai. Yang ada di repo
  ini adalah arsitektur + infrastruktur (training loop, runtime,
  extension system) yang **sudah dibuktikan bisa belajar** (lihat
  `examples/train_minimal.py`, loss turun dari 5.5 ke 0.002 pada task
  overfitting kecil), tapi belum dilatih pada corpus bahasa nyata
  berskala besar.

---

## 2. Kenapa bukan Self-Attention?

| | Self-Attention | Flow Processing + Flow Mixing (OFA) |
|---|---|---|
| Cara campur info antar-posisi | Pairwise similarity semua-ke-semua (softmax(QK^T)V) | Causal depthwise convolution lokal (jendela kecil, akumulasi lewat penumpukan layer) |
| Cara campur info antar-channel | Digabung jadi satu dengan langkah di atas (lewat proyeksi V dan output) | Terpisah: MLP position-wise (Flow Mixing) |
| Kompleksitas vs panjang sequence | O(n²) | O(n) |
| Kontrol seberapa besar info baru masuk | Implisit lewat softmax weights | Eksplisit lewat Gating (sigmoid/highway), terpisah untuk temporal dan channel mixing |

Detail matematis lengkap ada di [`ARCHITECTURE.md`](ARCHITECTURE.md).

---

## 3. Instalasi

```bash
pip install orbyte-flow    # setelah dipublish ke PyPI
# atau, dari source:
pip install -e .
```

Dependency wajib: **hanya `torch`**. Semua modul lain (memory, knowledge,
tools, verification) memakai Python standard library saja, sengaja
supaya instalasi tetap ringan.

---

## 4. Quickstart -- bangun & latih base model

```python
from orbyte_flow import OrbyteFlowModel, OFAConfig
import torch

# Pilih ukuran: "100M", "500M", "1B", "5B", atau OFAConfig custom
config = OFAConfig.preset("100M")
model = OrbyteFlowModel(config)
print(f"Parameter: {model.count_parameters():,}")

# Training loop standar PyTorch -- tidak ada API khusus/tersembunyi
optimizer = torch.optim.AdamW(model.parameters(), lr=3e-4)
input_ids = torch.randint(0, config.vocab_size, (4, 128))  # ganti dengan data asli Anda

for step in range(1000):
    optimizer.zero_grad()
    out = model(input_ids, labels=input_ids)
    out["loss"].backward()
    optimizer.step()

model.save_base_model("ofa_100m_base.pt")
```

Lihat `examples/train_minimal.py` untuk contoh yang benar-benar
dijalankan dan **terbukti loss-nya turun** (bukan cuma cuplikan kode).

---

## 5. Menambah kemampuan TANPA retraining

Ini inti dari desain OFA: base model dipisah total dari extension.

```python
from orbyte_flow import OrbyteFlowModel
from orbyte_flow.runtime import OrbyteFlowRuntime
from orbyte_flow.memory.store import ShortTermMemory, LongTermMemory
from orbyte_flow.knowledge.store import KnowledgeStore
from orbyte_flow.tools.registry import create_default_registry
from orbyte_flow.skills.module import SkillManager, SkillModule
from orbyte_flow.verification.checker import Verifier

model = OrbyteFlowModel.load_base_model("ofa_100m_base.pt")  # bobot BEKU, tidak diubah di bawah ini

# 1. Tambah knowledge/dokumen -- cukup panggil Python, tidak ada training
knowledge = KnowledgeStore()
knowledge.add_document("Isi dokumen Anda di sini...", source="manual.pdf")

# 2. Tambah memory persisten
long_term = LongTermMemory("./ofa_memory.json")

# 3. Tambah tools (calculator & python_exec sudah bawaan)
tools = create_default_registry()
tools.register("my_custom_tool", lambda x: x.upper())  # tool custom Anda sendiri

# 4. Tambah skill (paket instruksi + tools + knowledge tags)
skills = SkillManager()
skills.register(SkillModule(
    name="customer_support",
    instruction="Jawab dengan sopan, rujuk ke dokumentasi jika ada.",
    tool_names=["my_custom_tool"],
))
skills.activate("customer_support")

# Satukan semuanya -- base model TIDAK pernah disentuh di proses ini
runtime = OrbyteFlowRuntime(
    model=model,
    tokenizer=my_tokenizer,  # lihat bagian Tokenizer di bawah
    long_term_memory=long_term,
    knowledge=knowledge,
    tools=tools,
    skills=skills,
    verifier=Verifier(),
)

result = runtime.chat("Pertanyaan pengguna di sini")
print(result["output"])
print(result["verification"])  # cek apakah jawaban punya dukungan sumber
```

**Web search & Python sebagai tool:** `python_exec` sudah bawaan
(dengan guard keamanan dasar -- baca warning di
`orbyte_flow/tools/registry.py` sebelum dipakai untuk input tidak
tepercaya). `web_search` sengaja TIDAK dibawakan implementasinya
karena butuh API key/dependency jaringan spesifik pilihan Anda --
tinggal `tools.register("web_search", fungsi_anda)`, lihat contoh di
`examples/register_web_search.py`.

**Pola tool-calling manual (bukan otomatis dari output model):**
`chat()` saat ini tidak mem-parsing output model untuk mendeteksi
permintaan tool secara otomatis (lihat catatan jujur di docstring
`OrbyteFlowRuntime.chat()`). Untuk memanggil tool sebelum `chat()`
dan menyuntikkan hasilnya ke context, lihat pola lengkap di
`examples/agent_loop.py`.

---

## 6. Fine-tuning/Adapter (OPSIONAL, bukan wajib)

Kalau menambah knowledge/tools/skill saja belum cukup dan Anda ingin
menyesuaikan **kemampuan internal** model:

```python
from orbyte_flow.adapters.lora import attach_lora_adapters, count_trainable_parameters

attach_lora_adapters(model, rank=8)  # bobot dasar otomatis dibekukan
print(count_trainable_parameters(model))  # jauh lebih kecil dari total params

# Training seperti biasa -- HANYA adapter (LoRA) yang berubah,
# terverifikasi lewat test: bobot dasar identik sebelum/sesudah.
optimizer = torch.optim.AdamW([p for p in model.parameters() if p.requires_grad], lr=1e-3)
```

Ini pilihan tambahan, bukan langkah wajib dalam alur pemakaian OFA.

---

## 7. Model turunan (chatbot, coding AI, math AI, dst)

Base model yang sama bisa jadi fondasi berbagai turunan cukup dengan
kombinasi Skill + Knowledge + Tools yang berbeda -- **tidak perlu
arsitektur atau bobot berbeda per turunan**:

| Turunan | Skill aktif (contoh) | Tools relevan |
|---|---|---|
| Chatbot | `general_chat` | - |
| Coding AI | `code_assistant` | `python_exec` |
| Math AI | `math_assistant` | `calculator` |
| Education AI | `education_tutor` + knowledge kurikulum | - |
| Research AI | `research_assistant` + `KnowledgeStore` dokumen | `web_search` (daftarkan sendiri) |
| Game AI | `game_npc_dialogue` | tool spesifik game engine |
| Agent AI | gabungan beberapa skill + banyak tools | semua tools relevan |

Contoh konkret ada di `examples/derived_models/`.

---

## 8. Tokenizer

OFA **tidak membawa tokenizer bawaan** untuk produksi -- ini keputusan
sadar supaya library tidak memaksakan satu skema tokenisasi. Untuk
pemakaian nyata, latih BPE/SentencePiece sendiri dan set `vocab_size`
di `OFAConfig` sesuai vocab Anda.

Untuk **pengujian cepat tanpa training tokenizer**, `examples/simple_tokenizer.py`
menyediakan `ByteTokenizer` (byte-level, vocab_size=257) -- dipakai di
semua contoh di repo ini. Baca docstring-nya: ini sengaja BUKAN pilihan
produksi (context window efektif jauh lebih pendek dibanding subword
tokenizer).

---

## 9. Ukuran model

| Preset | hidden_size | num_layers | flow_lanes | Parameter aktual (terukur) |
|---|---|---|---|---|
| 100M | 768 | 12 | 8 | **95.5M** |
| 500M | 1536 | 18 | 12 | **474.3M** |
| 1B | 2048 | 24 | 16 | belum terukur di lingkungan dev ini (OOM pada RAM ~4GB, lihat catatan di bawah) |
| 5B | 3584 | 32 | 16 | belum terukur (RAM dev jauh tidak cukup) |

Angka "parameter aktual" di atas diukur langsung lewat
`model.count_parameters()`, bukan estimasi. Preset 1B dan 5B **belum
diverifikasi terukur** di lingkungan pengembangan ini karena RAM
container dev (~4GB) tidak cukup untuk inisialisasi model sebesar itu
dalam FP32 -- ini keterbatasan lingkungan testing, bukan indikasi
arsitektur gagal (100M dan 500M lolos dengan mulus mengikuti pola
scaling linear yang sama). Jika Anda punya mesin dengan RAM/VRAM
lebih besar, verifikasi ini dengan `python -c "from orbyte_flow import OFAConfig, OrbyteFlowModel; m = OrbyteFlowModel(OFAConfig.preset('1B')); print(m.count_parameters())"`
dan laporkan hasilnya.

Butuh ukuran lain? Buat `OFAConfig` custom dan cek
`config.num_parameters_estimate()` sebelum membangun model penuh.

---

## 10. Efisiensi compute & memori

- Flow Processing (depthwise conv) dan Flow Mixing (MLP) keduanya
  O(n) terhadap panjang sequence, dibanding O(n²) untuk Self-Attention.
  **Ini berlaku untuk SATU forward pass** (training, atau prefill atas
  prompt) -- diukur langsung, waktu per-posisi flat di seluruh rentang
  seq_len yang diuji (lihat `BENCHMARKS.md`).
- **Klaim O(n) ini TIDAK otomatis berlaku untuk `generate()` saat ini.**
  `generate()` belum memakai KV-cache -- setiap langkah forward ulang
  DARI AWAL atas seluruh sequence yang sudah ada (prompt + token yang
  sudah dihasilkan). Akibatnya, total biaya menghasilkan `m` token baru
  adalah jumlahan deret yang **kuadratik terhadap `m`**, pola yang
  secara struktural sama seperti Self-Attention tanpa KV-cache. Diukur
  langsung: waktu per-token-baru naik dari ~2.0ms ke ~7.9ms seiring
  jumlah token yang digenerate bertambah dari 100 ke 1600 (model kecil,
  CPU). Detail matematis di `ARCHITECTURE.md` §5b, metode pengukuran
  lengkap di `BENCHMARKS.md`.
- **Belum dibandingkan langsung dengan Transformer nyata** pada
  hardware yang sama -- baik untuk satu forward pass maupun untuk
  generate. Angka di atas mengukur OFA terhadap dirinya sendiri di
  berbagai panjang sequence, bukan head-to-head vs implementasi
  Transformer. Lihat `BENCHMARKS.md`.
- Membangun KV-cache-equivalent untuk Flow Processing (menyimpan state
  konvolusi antar langkah, bukan menghitung ulang dari nol) adalah
  prasyarat agar keunggulan O(n) OFA per forward pass terwariskan ke
  `generate()` secara keseluruhan -- target optimisasi lanjutan,
  dicatat di `ROADMAP.md`, bukan bagian dari implementasi awal ini.
- Tied embedding (lm_head berbagi bobot dengan token_embedding) aktif
  secara default, mengurangi parameter total secara signifikan.

---

## 11. Struktur package

```
orbyte_flow/
  core/          -- base model: config, flow (mixing/gating), block, model
  memory/        -- short-term & long-term memory (data, bukan bobot)
  knowledge/     -- RAG store (TF-IDF default, embedder custom opsional)
  tools/         -- tool registry + calculator & python_exec bawaan
  skills/        -- skill module system
  verification/  -- verifikasi klaim vs sumber
  adapters/      -- LoRA-style fine-tuning (OPSIONAL)
  runtime.py     -- penyatu semua komponen di atas
```

Setiap folder independen -- knowledge/tools/skills/memory bisa dipakai
tanpa runtime.py sama sekali kalau Anda mau menyusun orkestrasi sendiri.

---

## 12. Menjalankan test

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

## 13. Roadmap & keterbatasan yang sudah diketahui

Lihat [`ROADMAP.md`](ROADMAP.md) dan [`BENCHMARKS.md`](BENCHMARKS.md).

## Lisensi

MIT.
