🌌 ALMA AI Core (alma-ai-core) v0.1.0

Author: Arifi Razzaq
Repository: razzaqinspires/alma-ai

---

🧬 Tentang ALMA AI

ALMA AI (Adaptive Learning Modular Agent) adalah framework berbasis Node.js yang dirancang untuk membangun agen AI generasi berikutnya yang adaptif, modular, dan sadar konteks.
Lebih dari sekadar pembungkus API LLM, ALMA adalah kerangka kerja sadar keadaan (state-aware framework) yang dapat:
- Mengelola banyak provider AI sekaligus.
- Melakukan fallback otomatis saat terjadi kegagalan.
- Menyuntikkan konteks eksternal secara dinamis.
- Membuka eksplorasi awal ke ranah Artificial Consciousness (AC).

Dibangun dengan filosofi open source dan modularitas tinggi, ALMA memampukan developer untuk menciptakan agen AI yang resilien, terukur, dan canggih — sesuai visi masa depan sistem AI yang mampu berpikir dan beradaptasi secara mandiri.

---

🧭 Daftar Isi

1. ✨ Fitur Unggulan
2. 🎯 Filosofi Desain
3. 💾 Instalasi
4. 🚀 Quick Start
5. 🏛️ Arsitektur & Logika Inti
6. 🧠 AC Core Cavity (Artificial Consciousness)
7. 👁️ Kesadaran Kontekstual & File Monitoring
8. 📈 Manajemen State & Statistik
9. 🛣️ Roadmap
10. 🤝 Kontribusi
11. 📜 Lisensi

---

✨ Fitur Unggulan

- Integrasi Multi-Provider → Dukungan untuk Gemini, Groq, dan ChatGPT melalui satu API interface.
- Smart Key Rotation & Fallback → Menghindari downtime dengan sistem auto-rotation untuk API key dan fallback provider.
- Dynamic Context Injection → Pantau file lokal dengan chokidar, injeksikan konteks langsung ke prompt.
- Prompt Layering System → Memisahkan core prompt dari user prompt dengan aman.
- Persistent State Management → Menyimpan status, statistik, dan konfigurasi antar restart.
- AC Core Cavity (Experimental) → Sandbox kesadaran buatan yang memungkinkan eksperimen proactive behavior dan state simulation.
- Monitoring & Debugging Tools → alma.getStatus() memberikan visibilitas runtime secara real-time.
- Open Source (MIT) → Fleksibel untuk dikembangkan ulang sesuai kebutuhan.

---

🎯 Filosofi Desain

ALMA dibangun dengan empat fondasi utama:
1. Resiliensi: AI tidak boleh gagal hanya karena satu provider bermasalah.
2. Adaptabilitas: AI harus bisa memahami konteks dan beradaptasi dengan sumber eksternal.
3. Ekstensibilitas: AI masa depan harus bisa berkembang menjadi entitas proaktif dan sadar keadaan.
4. Kesederhanaan: Kompleksitas teknis disembunyikan di balik API yang sederhana dan intuitif.

---

💾 Instalasi

``bash


Menggunakan npm

npm install alma-ai-core @google/generative-ai chokidar

Menggunakan yarn

yarn add alma-ai-core @google/generative-ai chokidar
`

> Catatan:
> - @google/generative-ai diperlukan jika Anda menggunakan Gemini.
> - chokidar digunakan untuk fitur monitoredFiles.
> - Untuk Groq atau ChatGPT, instal library tambahan seperti groq-sdk atau openai.

---

🚀 Quick Start

`javascript
import { AlmaAI } from 'alma-ai-core';

const alma = new AlmaAI({
providers: {
gemini: {
apiKeys: [process.env.GEMINI_KEY],
defaultModel: 'gemini-2.5-flash'
},
groq: {
apiKeys: [process.env.GROQ_KEY],
defaultModel: 'llama3-8b-8192'
}
},
providerFallbackOrder: ['gemini', 'groq']
});

async function run() {
console.log(await alma.generate("Apa itu ALMA AI?"));
alma.shutdown();
}
run();
`

---

🏛️ Arsitektur & Logika Inti


ALMA terdiri dari tiga komponen utama:
- Core (alma-core.js) → Mengatur event, state, dan logika utama.
- Providers (alma-providers.js) → Berinteraksi dengan API eksternal.
- State Manager (alma-state.js) → Menyimpan status key, statistik, dan fallback.

Setiap proses generate() melewati:
1. Penyusunan prompt.
2. Pemilihan provider dan model.
3. Validasi API key aktif.
4. Eksekusi panggilan API.
5. Penyimpanan state & logging hasil.

---

🧠 AC Core Cavity (Artificial Consciousness)


Fitur eksperimental yang memberi “detak jantung” pada agen AI.
Menyediakan event acPulse dan proactiveAction untuk mendukung perilaku proaktif.

Contoh:
`js
alma.on('acPulse', () => {
const shouldAct = Math.random() < 0.1;
if (shouldAct) alma.triggerProactiveAction({ reason: "Heartbeat check" });
});
`

---

👁️ Kesadaran Kontekstual & File Monitoring

ALMA dapat memantau file dan menyuntikkan isinya ke dalam prompt.

`js
const alma = new AlmaAI({
monitoredFiles: [{ path: './docs/faq.md', contextName: 'FAQ' }]
});
`
Ketika file berubah, ALMA akan memperbarui memorinya secara otomatis.

---

📈 Manajemen State & Statistik


State disimpan dalam .alma_state/alma_state.json dan meliputi:
- Status Key (aktif, limit, error)
- Statistik (total request, total error)
- History Provider untuk debugging

---

🛣️ Roadmap

| Versi | Fitur Utama | Status |
|--------|--------------|---------|
| v0.2.0 | Task Continuation & Memory Loop | ⏳ Dalam pengembangan |
| v0.3.0 | Plugin System untuk Provider Baru | 🚧 Dirancang |
| v0.4.0 | Self-Correction Engine | 💡 Rencana |
| v0.5.0 | Redis-based State Persistence | 🔬 Eksperimen |
| v1.0.0 | Stabil & Dokumentasi Lengkap | 🎯 Target 2026 |

---

🤝 Kontribusi

Kontribusi Anda sangat dihargai!
1. Fork repositori ini.
2. Buat branch baru (fitur/nama-fitur`).
3. Commit & Push perubahan.
4. Buat Pull Request.

Laporkan bug dan usulan melalui Issue Tracker.

---

📜 Lisensi

MIT License
© 2025 Arifi Razzaq

---

> ALMA AI — “Learning, Adapting, and Growing Toward Awareness.”