Metadata-Version: 2.1
Name: astraea-adk
Version: 1.0.1
Summary: Enterprise-Grade Mixture-of-Agents (MoA) Orchestration & Autonomous Agent Development Kit
Author: Hillario RZA
License: Proprietary & Confidential
Project-URL: Homepage, https://github.com/HillarioRZA/Astraea-ADK
Project-URL: Documentation, https://github.com/HillarioRZA/Astraea-ADK/blob/main/documentation.md
Keywords: agentic-ai,mixture-of-agents,moa,multi-agent,llm-orchestration,autonomous-agents,knowledge-graph
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Provides-Extra: secure-build
Requires-Dist: build>=1.0.0; extra == "secure-build"
Requires-Dist: twine>=4.0.0; extra == "secure-build"
Requires-Dist: cython>=3.0.0; extra == "secure-build"
Requires-Dist: wheel>=0.40.0; extra == "secure-build"

# Astraea ADK (LegionADK)
### Enterprise-Grade Mixture-of-Agents (MoA) Orchestration & Autonomous Agent Development Kit

[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
[![Pydantic](https://img.shields.io/badge/pydantic-v2%20(frozen=True)-green.svg)](https://docs.pydantic.dev/)
[![Architecture](https://img.shields.io/badge/architecture-Role--Agnostic%20MoA-orange.svg)]()
[![Status](https://img.shields.io/badge/checkpoints-O1--O12%20PASS%20100%25-brightgreen.svg)]()
[![API Documentation](https://img.shields.io/badge/docs-API%20Reference-blueviolet.svg)](documentation.md)
[![License](https://img.shields.io/badge/license-Proprietary%20%26%20Confidential-red.svg)](LICENSE)

Astraea ADK (**LegionADK**) adalah framework dan runtime tingkat enterprise untuk perancangan, orkestrasi, tata kelola keamanan (*governance*), memori graf lokal, serta komunikasi sistem multi-agen berbasis **Mixture-of-Agents (MoA)**. ADK ini dirancang dari nol dengan fokus pada determinisme matematis, pencegahan balapan data (*race condition*), efisiensi biaya inferensi token LLM, dan keandalan tingkat produksi (*production-grade resilience*).

---

## 📑 Daftar Isi

- [📖 Panduan Lengkap API (documentation.md)](documentation.md)
- [Arsitektur Sistem (Layer Breakdown)](#-arsitektur-sistem-layer-breakdown)
- [Fitur Utama (Core Features)](#-fitur-utama-core-features)
- [Konfigurasi Lingkungan (.env)](#-konfigurasi-lingkungan-env)
- [Panduan Penggunaan Cepat (Quickstart)](#-panduan-penggunaan-cepat-quickstart)
  - [A. Membangun Roster Agen Dinamis](#a-membangun-roster-agen-dinamis)
  - [B. Cara 1: Diskusi Multi-Putaran Eksplisit (run_moa_debate)](#b-cara-1-diskusi-multi-putaran-eksplisit-run_moa_debate)
  - [C. Cara 2: Triase Otonom & Pendelegasian Mandiri (run_autonomous_triage)](#c-cara-2-triase-otonom--pendelegasian-mandiri-run_autonomous_triage)
  - [D. Fasad Tingkat Atas: Router Otomatis (dispatch_envelope)](#d-fasad-tingkat-atas-router-otomatis-dispatch_envelope)
  - [E. Strict Chain-of-Command Rekursif (Hierarki Berjenjang)](#e-strict-chain-of-command-rekursif-hierarki-berjenjang)
- [Verifikasi & Checkpoint Test Suite](#-verifikasi--checkpoint-test-suite)
- [Lisensi](#-lisensi)

---

## 🏗 Arsitektur Sistem (Layer Breakdown)

![Astraea ADK System Architecture](docs/assets/system_architecture.png)

Astraea ADK dibangun dengan arsitektur berlapis (*layered architecture*) yang modular, deterministik, dan terisolasi dengan batas tanggung jawab (*separation of concerns*) yang jelas. Setiap lapisan saling berkolaborasi melalui protokol komunikasi yang terstandarisasi:

### 1. Protocol Layer (MoA Orchestration Engine)
Lapisan orkestrasi tingkat tinggi yang mengendalikan interaksi, kolaborasi, dan alur kerja antar-agen:
* **MoA Orchestration**: Mengelola eksekusi Mixture-of-Agents secara adaptif. Agen koordinator dapat menganalisis persoalan secara mandiri, menentukan pembagian peran, dan membagi tugas ke berbagai spesialis terkait.
* **Multi-Agent Debate**: Memfasilitasi pertukaran ide, sintesis kompromi, dan evaluasi silang (*cross-critique*) multi-putaran antar-spesialis sebelum draf akhir disatukan kembali oleh peran agregator.
* **Strict Chain-of-Command**: Mengatur hierarki delegasi berjenjang (atasan ke bawahan) dengan batas kedalaman eksekusi terkontrol, pelacakan tumpukan panggilan (*call stack tracking*), serta pencegahan siklus delegasi (*anti-cycle protection*).

### 2. Runtime Layer (10-Phase Agent Turn Engine)
Mesin eksekusi inti yang memandu siklus hidup giliran (*turn lifecycle*) setiap agen secara deterministik dan terukur:
* **10-Phase Execution Pipeline**: Menjalankan setiap giliran interaksi melalui tahapan terstandarisasi—mulai dari audit tata kelola awal (*preflight*), perakitan prompt dinamis, pemanggilan model terawasi (*watchdog invocation*), eksekusi aksi, evaluasi keamanan pasca-eksekusi, hingga finalisasi status.
* **Context Compaction & Token Budgeting**: Pengelolaan kuota token proaktif dengan strategi reduksi riwayat dua tingkat (*summarization & eviction*), menjaga relevansi konteks percakapan panjang tanpa melampaui jendela konteks model.
* **Immutable State Transitions**: Menjamin seluruh manipulasi status percakapan bersifat beku (*immutable frozen state*), mencegah mutasi data yang tidak terduga antar-giliran.

### 3. Gateway Layer (Resilient I/O & Routing)
Gerbang komunikasi berkecepatan tinggi yang menjembatani runtime agen dengan berbagai penyedia model LLM (*foundation models*):
* **Model Router & Load Balancer**: Manajemen lalu lintas inferensi multi-penyedia dengan isolasi kuota RPM/TPM, *failover cascade* otomatis, dan pemulihan mandiri (*auto-cooldown*) saat terjadi batasan laju (*rate-limiting*).
* **Byte-Stable Cache Boundary**: Segmentasi prompt statis dan dinamis dengan verifikasi hash deterministik untuk memastikan efisiensi biaya tertinggi dan retensi *prompt caching* penyedia LLM (>90% Cache HIT).
* **Multi-LLM Adapters**: Abstraksi konektor universal untuk penyedia model cloud terkemuka maupun model lokal (*self-hosted* / private inference).
* **Self-Healing Tool Repair**: Mekanisme penanganan anomali otomatis yang mampu memperbaiki payload JSON yang terpotong atau mengalami inkonsistensi sintaks sebelum diproses lebih lanjut.

### 4. Governance Layer (Security & Safety Guardrails)
Sistem pertahanan berlapis (*defense-in-depth*) yang menjamin keamanan dan kepatuhan eksekusi di lingkungan produksi:
* **Deterministic Verifier**: Validasi parametrik ketat terhadap seluruh aksi agen sebelum dieksekusi, mencegah manipulasi batas direktori kerja (*path traversal*) dan akses resource ilegal.
* **Smart Guardian**: Mesin audit perilaku agen secara *real-time* untuk mengevaluasi risiko eksekusi kode berbahaya, manipulasi instruksi (*prompt injection*), dan pola loop anomali.
* **Circuit Breakers**: Sakelar proteksi otomatis yang memutus rantai eksekusi saat layanan hilir mengalami kegagalan berulang, mencegah pemborosan kuota dan kelelahan sistem.
* **Parallel Execution Guards**: Pembatasan hak akses operasi mutasi bagi agen yang berjalan serentak, menjamin integritas data dan eliminasi total terhadap kondisi balapan (*race condition*).

### 5. Memory Layer (Local Knowledge Graph & Vault)
Infrastruktur memori graf pengetahuan lokal tanpa ketergantungan pada database eksternal yang rumit:
* **Knowledge Graph Vault**: Penyimpanan dokumen pengetahuan berbasis format terbuka dengan metadata terstruktur dan transaksi berkas atomik yang aman (*atomic file-locking*).
* **Wiki-Links & Semantic Relations**: Pengindeksan otomatis relasi dua arah (*bidirectional links*) dan penelusuran relasi dokumen secara deterministik untuk menemukan konteks yang relevan secara instan.

---

## 🌟 Fitur Utama (Core Features)

Astraea ADK dirancang untuk memenuhi standar keandalan, keamanan, dan efisiensi tingkat produksi (*enterprise-grade*) bagi ekosistem multi-agen modern:

* **100% Role-Agnostic Multi-Agent Ecosystem**
  Tidak ada peran atau persona yang di-*hardcode*. Pengembang memiliki kebebasan penuh merancang struktur tim agen, persona (*soul*), SOP operasional, serta wewenang alat secara dinamis sesuai kebutuhan spesifik domain industri.

* **Advanced Mixture-of-Agents (MoA) Collaboration**
  Mendukung kolaborasi multi-agen canggih melalui dua pola operasional: konsensus debat multi-putaran untuk eksplorasi dan sintesis ide, serta triase otonom di mana koordinator memecah dan mendelegasikan tugas ke sub-tim spesialis secara mandiri.

* **Strict Chain-of-Command & Anti-Cycle Hierarchies**
  Mendukung pendelegasian hierarkis berjenjang (atasan ke bawahan) dengan batas kedalaman terkontrol, jaminan zero double-call pada LLM untuk efisiensi token, serta perlindungan tumpukan panggilan (*call stack guard*) yang mencegah siklus delegasi tanpa akhir.

* **Byte-Stable Prompt Caching & Cost Optimizer**
  Optimalisasi biaya inferensi tingkat lanjut dengan memisahkan identitas agen statis dari konteks dinamis secara deterministik. Memaksimalkan rasio Cache HIT hingga >90% pada penyedia LLM modern, memangkas latensi dan biaya operasional secara signifikan.

* **Multi-Provider Resilience & Auto-Failover**
  Konektivitas terintegrasi ke berbagai penyedia model cloud terkemuka serta infrastruktur *self-hosted* / private proxy. Dilengkapi isolasi kuota RPM/TPM mandiri, mekanisme *failover cascade*, serta pemulihan otonom saat terkena batas laju (HTTP 429/5xx).

* **Self-Healing Tool Calling & JSON Repair**
  Mesin perbaikan otomatis yang secara mandiri menambal keluaran model yang terpotong oleh batasan token (*max_tokens*), menyeimbangkan tanda kurung, membersihkan format data, dan menjamin keberhasilan pemanggilan fungsi tanpa *crash*.

* **Enterprise-Grade Governance & Multi-Layer Guardrails**
  Validasi deterministik sebelum aksi (*pre-execution verifier*), audit keamanan perilaku dan analisis risiko kode secara *real-time*, sakelar pemutus sirkuit (*circuit breaker*), serta isolasi ketat terhadap sistem operasi dan direktori berkas.

* **Concurrency & Race-Condition Immunity**
  Eksekusi multi-agen paralel yang kebal terhadap konflik data berkat mekanisme isolasi hak akses mutasi pada agen paralel serta transaksi berkas atomik (*deadlock-free file locking*).

* **Local Knowledge Graph Memory Engine**
  Penyimpanan memori jangka panjang berbasis graf pengetahuan lokal dengan penautan semantik dua arah (*Wiki-Links*) dan penelusuran jalur keterkaitan dokumen yang cepat, sepenuhnya mandiri tanpa dependensi database eksternal yang kompleks.

---

## ⚙️ Konfigurasi Lingkungan (.env)

Buat berkas `.env` pada direktori root proyek untuk menghubungkan penyedia LLM Anda:

```env
# ============================================================================
# Universal Custom Provider (Aggregator / Private Proxy / Self-hosted vLLM)
# ============================================================================
CUSTOM_PROVIDER_API_KEY=your_api_key_here
CUSTOM_PROVIDER_BASE_URL=https://api.your-provider.com/v1

# Parameter Model Utama
TEST_PRIMARY_PROVIDER=custom
TEST_PRIMARY_MODEL=deepseek-v4.1-flash

# ============================================================================
# Official Providers (Opsional - Sesuai Kebutuhan)
# ============================================================================
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIzaSy...
OLLAMA_BASE_URL=http://localhost:11434/v1
VLLM_BASE_URL=http://localhost:8000/v1

# Matikan mode live pada test suite jika hanya ingin menguji algoritma offline:
# LEGION_SKIP_LIVE=1
```

---

## 🚀 Panduan Penggunaan Cepat (Quickstart)

### A. Membangun Roster Agen Dinamis
LegionADK bersifat **role-agnostic**. Anda bebas menentukan nama peran, *persona soul*, dan batasan SOP:

```python
from LegionADK.core.llm_spec import LLMSpec
from LegionADK.protocol import AgentRoster

roster = AgentRoster([
    LLMSpec(
        handle="@coordinator",
        agent_name="Koordinator Utama",
        soul_prompt="Kamu adalah koordinator tim yang analitis dan cermat.",
        system_prompt="Analisis topik dan delegasikan tugas ke spesialis terkait.",
        tool_permissions=["comm:delegate"],
    ),
    LLMSpec(
        handle="@architect",
        agent_name="Software Architect",
        soul_prompt="Kamu mengutamakan modularitas, skalabilitas, dan keandalan sistem.",
        system_prompt="Berikan rekomendasi arsitektur sistem yang konkret.",
        tool_permissions=["comm:delegate"],
    ),
    LLMSpec(
        handle="@security",
        agent_name="Security Specialist",
        soul_prompt="Kamu fokus pada keamanan memori, enkripsi, dan audit risiko.",
        system_prompt="Identifikasi kerentanan dan rekomendasikan kontrol pengamanan.",
    ),
])
```

---

### B. Cara 1: Diskusi Multi-Putaran Eksplisit (`run_moa_debate`)
Gunakan saat pengguna meminta beberapa agen berdiskusi mencari titik kompromi:

```python
import asyncio
from LegionADK.core.llm_spec import contract_message
from LegionADK.protocol import OrchestrationPolicy, run_moa_debate

async def main():
    env = contract_message(
        sender="@user",
        target="@coordinator",
        content="Silakan @architect berdiskusi dengan @security untuk merancang sistem autentikasi perbankan.",
    )

    policy = OrchestrationPolicy(max_discussion_rounds=2)
    result = await run_moa_debate(
        envelope=env,
        roster=roster,
        aggregator_handle="@coordinator",
        policy=policy,
    )

    print(f"Status Orkestrasi: {result.status}")
    print(f"Sintesis Akhir:\n{result.final_content}")

asyncio.run(main())
```

---

### C. Cara 2: Triase Otonom & Pendelegasian Mandiri (`run_autonomous_triage`)
Koordinator mengevaluasi topik. Jika sederhana, koordinator langsung menjawab (jalur cepat `STANDALONE`). Jika membutuhkan masukan tim, koordinator memanggil spesialis secara mandiri lalu menyintesiskan hasilnya:

```python
from LegionADK.protocol import run_autonomous_triage

async def main():
    env = contract_message(
        sender="@user",
        target="@coordinator",
        content="Kita mengalami lonjakan trafik transaksi 500% malam ini. Analisis dan buat rencana mitigasi.",
    )

    result = await run_autonomous_triage(
        envelope=env,
        roster=roster,
        coordinator_handle="@coordinator",
    )

    print(f"Mode Terpilih : {result.mode}") # AUTONOMOUS_TRIAGE atau STANDALONE
    print(f"Agen Spesialis: {result.proposer_handles}")
    print(f"Keputusan Akhir:\n{result.final_content}")

asyncio.run(main())
```

---

### D. Fasad Tingkat Atas: Router Otomatis (`dispatch_envelope`)
Pintu masuk terpadu yang otomatis menganalisis amplop dan memilih alur eksekusi terbaik:

```python
from LegionADK.protocol import dispatch_envelope

async def handle_incoming_message(envelope):
    # Otomatis mendeteksi:
    # 1. AUTONOMOUS_TRIAGE (jika target adalah koordinator)
    # 2. EXPLICIT_MOA (jika target >= 2 agen atau menyebut banyak @handle)
    # 3. STANDALONE (jika target 1 agen biasa)
    return await dispatch_envelope(envelope=envelope, roster=roster)
```

---

### E. Strict Chain-of-Command Rekursif (Hierarki Berjenjang)
Mendukung pendelegasian hierarkis berlapis: `User` $\to$ `@coordinator` $\to$ `@architect` $\to$ `@security` $\to$ `@architect` $\to$ `@coordinator` $\to$ `User`.

```python
policy = OrchestrationPolicy(
    max_delegation_depth=3,      # Batas kedalaman hierarki (mencegah runaway recursion)
    max_discussion_rounds=1,     # Putaran debat per level
)

result = await dispatch_envelope(
    envelope=env,
    roster=roster,
    policy=policy,
    triage_handles=["@coordinator"],
)

# Seluruh prompt, cached, dan completion tokens dari @security terakumulasi ke @architect
# dan teragregasi secara presisi ke dalam total @coordinator.
print(f"Total Token Tim: {result.total_prompt_tokens} prompt, {result.total_completion_tokens} completion")
```

---

## 🧪 Verifikasi & Checkpoint Test Suite

Seluruh kapabilitas LegionADK diverifikasi melalui rangkaian pengujian komprehensif dari Checkpoint 1 hingga Checkpoint 4.

### Menjalankan Seluruh Pengujian Checkpoint 4

```powershell
# Jalankan seluruh pengujian (O1 - O12) termasuk live LLM test:
$env:PYTHONPATH="."
python checkpoint_4_orchestrator.py

# Atau jalankan mode offline murni (melewati live LLM):
$env:LEGION_SKIP_LIVE="1"
python checkpoint_4_orchestrator.py
```

### Hasil Ringkasan Checkpoint 4 (100% PASS)

| Kode | Kategori | Nama Pengujian | Status | Rangkuman Hasil |
| :---: | :---: | :--- | :---: | :--- |
| **O1** | Offline | Parser `@handle` & Code-Fence | `PASS` | Email (`kontak@pm.com`) & dekorator kode diabaikan; urutan kemunculan terjaga deterministik. |
| **O2** | Offline | Resolusi Roster & `@all` | `PASS` | Ekspansi `@all` otomatis mengecualikan pengirim untuk mencegah *self-mention ping-pong*. |
| **O3** | Offline | Parallel Mutation Guard | `PASS` | Proposer paralel diblokir saat mencoba mengeksekusi tool mutasi Tier 1+ (`workspace:write_config`). |
| **O4** | Offline | Isolasi Kegagalan Proposer | `PASS` | 1 Proposer timeout/gagal tidak menggagalkan sintesis Aggregator (*graceful degradation*). |
| **O5** | Offline | Cara 1 (Debat Multi-Putaran) | `PASS` | 2 putaran diskusi Proposer terkirim via `dynamic_context` byte-stable dan disintesis sempurna. |
| **O6** | Offline | Cara 2 (Triase Otonom Koordinator) | `PASS` | Koordinator secara mandiri mengevaluasi direktori peran, memilih spesialis, dan menyintesis solusi. |
| **O9** | Offline | Recursive Strict Chain-of-Command | `PASS` | Rantai 3-tingkat terdelegasi mulus dengan pembuktian **Zero Double-Triage** dan agregasi token akurat. |
| **O10** | Offline | Governance Cutoff & Anti-Cycle | `PASS` | `max_delegation_depth=1` menahan rekursi berlebih; deteksi siklus call stack menghasilkan `[SIKLUS TERDETEKSI]`. |
| **O7** | Live LLM | Live Cara 1 (Debat Eksplisit) | `PASS` | Eksekusi nyata API: `@cto` dan `@pm` berdiskusi mencari titik kompromi, disintesis oleh `@supervisor`. |
| **O8** | Live LLM | Live Cara 2 (Triase Otonom) | `PASS` | Eksekusi nyata API: `@cos` mandiri menganalisis lonjakan biaya 300% dan memanggil tim teknis. |
| **O11** | Live LLM | Live Recursive Chain-of-Command | `PASS` | Eksekusi nyata API: Rantai hierarkis User $\to$ `@cos` $\to$ `@cto` $\to$ `@pm` tuntas disintesis berjenjang. |
| **O12** | Live LLM | Live Governance Cutoff | `PASS` | Eksekusi nyata API: `max_delegation_depth=1` berhasil ditegakkan tanpa memicu sub-triase liar. |

---

## 🔒 Lisensi

Proyek ini dilindungi di bawah lisensi **Proprietary and Confidential License**.
Hak Cipta &copy; 2025 Astraea ADK Contributors. Seluruh hak cipta dilindungi undang-undang.

Dilarang keras menyebarluaskan, mendistribusikan ulang, atau mereproduksi kode sumber ini tanpa izin tertulis eksplisit dari pemilik hak cipta.
