📘 Agentic Research Environment — Documentation

🧩 Overview

Agentic Research Environment (ARE) adalah kerangka kerja riset AI modular berbasis executor–provider pipeline. Ia mendukung eksekusi reasoning otomatis, integrasi LLM multi-platform, dan ekspor hasil ke format DOCX/PDF.

Arsitektur ini dirancang dengan prinsip plug-and-play, artinya setiap komponen (executor, provider, utilitas) dapat diganti atau dikembangkan tanpa mengganggu sistem utama.

---

🧱 Struktur Proyek

agent-researcher/
│
├── core/                 # Fondasi sistem
│   ├── logger.py
│   ├── base_executor.py
│   ├── registry.py
│   ├── context.py
│   ├── provider.py
│   ├── pipeline.py
│   ├── config.py
│   └── constants.py
│
├── providers/            # Abstraksi platform LLM
│   ├── openai_provider.py
│   ├── pollination_provider.py
│   ├── lmstudio_provider.py
│   ├── huggingface_provider.py
│   └── mock_provider.py
│
├── executors/            # AI task plugin layer
│   ├── title_generator.py
│   ├── outline_builder.py
│   ├── draft_writer.py
│   ├── exporter.py
│   └── data_prep.py
│
├── pipelines/            # YAML pipeline definition
│   ├── base_research.yaml
│   ├── data_driven_research.yaml
│   ├── literature_review.yaml
│   └── template_based.yaml
│
├── utils/                # Helper dan ekstensi
│   ├── doc_tools.py
│   ├── data_tools.py
│   ├── reference_tools.py
│   ├── visualize_tools.py
│   └── validator.py
│
├── cli.py                # Command line interface utama
├── main.py               # Entry point program
├── requirements.txt      # Dependency list
├── .env                  # Konfigurasi environment API
└── docs.md               # Dokumentasi proyek

---

⚙️ Cara Instalasi

1️⃣ Clone Repository & Setup Environment

git clone https://github.com/lahadiyani/ARE---Framework-DAG-Agent.git
cd agent-researcher
python -m venv venv
source venv/bin/activate  # atau di Windows: venv\Scripts\activate
pip install -r requirements.txt

2️⃣ Konfigurasi API Key

Edit file .env:

OPENAI_API_KEY=your_openai_api_key
POLLINATIONS_API_KEY=your_pollinations_token
HUGGINGFACE_API_KEY=your_huggingface_token
LMSTUDIO_BASE_URL=http://localhost:1234

---

🚀 Cara Menjalankan CLI

Jalankan executor langsung

python main.py run --executor title_generator --input "AI dalam pendidikan"

Jalankan pipeline YAML

python main.py run --pipeline base_research.yaml --provider pollinations

Melihat daftar executor

python main.py --list-executors

---

🧠 Pipeline Contoh: base_research.yaml

name: Base Research Flow
description: Pipeline dasar untuk riset AI
steps:
  - executor: title_generator
  - executor: outline_builder
  - executor: draft_writer
  - executor: exporter

---

🧰 Pengembangan Modular

Setiap lapisan bersifat independen. Jika kamu menambah executor baru:

1. Tambahkan file di executors/ (misal summary_builder.py)
2. Daftarkan di core/registry.py, core/base_executor.py dan jika kamu membutuhkan logger maka panggil core/logger.py kemudian gunakan beberapa class dan fungsi tertentu seperti BaseExecutor sebagai kontrak semua executor, dan executor_registry sebagai Sistem plugin untuk executor, juga get_logger sebagai cara untuk melihat error atau informasu alur atau lihat contoh executor file yang ada
3. Tambahkan ke YAML pipeline atau lihat dokumentasi pipeline.md
4. Jalankan pipeline baru
5. jika ada kekurangan anda bisa berkontribusi dengan cara fork repository ini

---

🧩 API Abstraction (Provider Layer)

Setiap provider harus mengimplementasikan minimal:

class BaseProvider:
    async def text2text(self, prompt: str, **kwargs) -> str:
        raise NotImplementedError

Provider yang tersedia:

• openai_provider.py
• pollination_provider.py
• huggingface_provider.py
• lmstudio_provider.py
• mock_provider.py

---

📦 Executor Pattern

Semua executor mengikuti kontrak BaseExecutor:

class BaseExecutor(ABC):
    name: str

    async def run(self, context):
        raise NotImplementedError

Contoh:

class TitleGenerator(BaseExecutor):
    async def run(self, ctx):
        topic = ctx.get("topic", "Artificial Intelligence")
        prompt = f"Buatkan 5 judul penelitian tentang {topic}."
        return await ctx.llm.text2text(prompt)

---

🧩 Extension Workflow

Lapisan	Fokus	Dapat Dikembangkan
Core	Pipeline dan context	Tambah event bus, cache, DAG executor
Providers	Koneksi LLM	Tambah backend (Anthropic, Ollama, dll)
Executors	Logic AI	Tambah task baru (summary, classification, dsb)
Utils	Tools bantu	Tambah fungsi visualisasi dan validasi
Pipelines	YAML Flow	Kombinasi executor baru

---

🔬 Testing & Debugging

Gunakan mode mock provider untuk pengujian tanpa API call:

python main.py run --pipeline base_research.yaml --provider mock

Logger disediakan via core/logger.py menggunakan loguru, dan dapat dikustomisasi untuk level info/debug/error.

---

🧱 Future Roadmap

• Integrasi Event Bus (Human-in-the-loop)
• Tambah Web UI untuk monitoring pipeline
• Support parallel DAG executor
• Integration ke Notion/Obsidian
• Auto citation dari CrossRef

---

🧭 Kontribusi

Pull request disambut terbuka!

1. Buat branch sesuai fitur: feature/provider-ollama
2. Gunakan commit convention: feat, fix, refactor, docs
3. Jalankan test sebelum push

---

📄 Lisensi

MIT License © 2025 — Agentic Research Environment