adelie-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kimhyunbin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,335 @@
+<p align="center">
+  <img src="docs/adelie_logo.jpeg" alt="Adelie Logo" width="200" />
+</p>
+
+<h1 align="center">Adelie</h1>
+
+<p align="center">
+  <strong>Self-Communicating Autonomous AI Loop System</strong><br/>
+  An AI orchestrator that plans, codes, reviews, tests, deploys, and evolves — autonomously.
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.10+-blue?logo=python" alt="Python 3.10+" />
+  <img src="https://img.shields.io/badge/LLM-Gemini%20%7C%20Ollama-orange" alt="LLM Support" />
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" />
+  <img src="https://img.shields.io/badge/tests-374%20passed-brightgreen" alt="Tests" />
+</p>
+
+---
+
+## What is Adelie?
+
+Adelie is an **autonomous AI loop system** that orchestrates multiple specialized AI agents to build, maintain, and evolve software projects — with minimal human intervention.
+
+Think of it as an AI team that continuously works on your project:
+
+| Agent | Role |
+|-------|------|
+| **Expert AI** | Makes strategic decisions, dispatches tasks, manages state |
+| **Writer AI** | Creates and maintains the Knowledge Base (documentation) |
+| **Coder AI** | Writes actual source code in a layered architecture |
+| **Reviewer AI** | Reviews code quality, feeds back to coders |
+| **Tester AI** | Runs tests, reports failures back for fixes |
+| **Runner AI** | Builds, deploys, and runs the project |
+| **Monitor AI** | Checks system health, triggers restarts |
+| **Analyst AI** | Provides project-level insights and analysis |
+| **Research AI** | Searches the web for external information |
+| **Scanner AI** | Scans existing codebases on first run |
+
+All agents communicate through a **file-based Knowledge Base** and are coordinated by the **Orchestrator** — an endless loop with a built-in state machine.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   ORCHESTRATOR                       │
+│                                                     │
+│   ┌──────────┐    ┌──────────┐    ┌──────────────┐ │
+│   │ Writer AI│───>│Expert AI │───>│ Coder Manager│ │
+│   └──────────┘    └──────────┘    └──────┬───────┘ │
+│        │               │                 │         │
+│        v               │          ┌──────┴──────┐  │
+│   ┌──────────┐         │          │  Layer 0-2  │  │
+│   │Knowledge │         │          │   Coders    │  │
+│   │   Base   │<────────┘          └──────┬──────┘  │
+│   └──────────┘                           │         │
+│                                          v         │
+│   ┌──────────┐  ┌──────────┐  ┌──────────────────┐│
+│   │ Reviewer │  │ Tester   │  │ Runner / Monitor ││
+│   │    AI    │  │    AI    │  │       AI         ││
+│   └──────────┘  └──────────┘  └──────────────────┘│
+│                                                     │
+│   ┌──────────────────────────────────────────────┐ │
+│   │  Loop Detector │ Scheduler │ Process Supv.   │ │
+│   └──────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Project Lifecycle (Phases)
+
+Adelie evolves your project through 6 phases:
+
+```
+INITIAL ──> MID ──> MID_1 ──> MID_2 ──> LATE ──> EVOLVE
+Planning    Coding   Testing   Optimizing  Maintaining  Autonomous
+```
+
+| Phase | Focus | Coder Layers |
+|-------|-------|-------------|
+| Initial | Documentation, architecture, roadmap | None |
+| Mid | Implementation, feature coding | Layer 0 (features) |
+| Mid-1 | Integration, testing, roadmap check | Layer 0-1 (+ connectors) |
+| Mid-2 | Stabilization, optimization, deployment | Layer 0-2 (+ infra) |
+| Late | Maintenance, new features | All layers |
+| Evolve | Autonomous evolution, self-improvement | All layers |
+
+Phase transitions are **gated** by quality metrics (KB file count, test pass rate, review scores) and confirmed by the Expert AI.
+
+---
+
+## Safety Harnesses
+
+Adelie includes multiple built-in safety mechanisms:
+
+| Harness | Purpose |
+|---------|---------|
+| **Loop Detector** | Detects 5 types of repetitive patterns with escalating interventions |
+| **Phase Gates** | Prevents premature transitions with quality thresholds |
+| **Context Budget** | Per-agent token budgets prevent unbounded prompt growth |
+| **Process Supervisor** | Timeout enforcement, orphan cleanup, concurrent limits |
+| **Reviewer Loop** | Code review → feedback → retry cycle (max 2 retries) |
+| **Tester Loop** | Test failure → coder fix → re-test cycle (max 2 retries) |
+| **Expert Fallback** | JSON retry + regex extraction + safe fallback decision |
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- **Python 3.10+**
+- **Node.js 16+** (for the CLI wrapper)
+- **Gemini API key** or **Ollama** running locally
+
+### Installation
+
+```bash
+# Install via npm (recommended)
+npm install -g adelie
+
+# Or install from source
+git clone https://github.com/kimhyunbin/Adelie.git
+cd Adelie
+npm install -g .
+```
+
+### Setup
+
+```bash
+# Initialize a workspace in your project directory
+cd /path/to/your/project
+adelie init
+
+# Configure LLM provider
+adelie config --provider gemini --api-key YOUR_GEMINI_API_KEY
+
+# Or use Ollama (local, free)
+adelie config --provider ollama --model gemma3:12b
+
+# Set display language (ko or en)
+adelie config --lang en
+```
+
+### Run
+
+```bash
+# Start the autonomous AI loop
+adelie run --goal "Build a REST API for task management"
+
+# Or run a single cycle
+adelie run once --goal "Analyze and document the codebase"
+```
+
+---
+
+## CLI Reference
+
+```
+Workspace
+  adelie init [dir]              Initialize workspace (default: current dir)
+  adelie ws                      List all workspaces
+  adelie ws remove <N>           Remove workspace #N
+
+Run
+  adelie run --goal "..."        Start AI loop
+  adelie run ws <N>              Resume loop in workspace #N
+  adelie run once --goal "..."   Run exactly one cycle
+
+Configuration
+  adelie config                  Show current config
+  adelie config --provider ...   Switch LLM provider (gemini/ollama)
+  adelie config --model ...      Set model name
+  adelie config --interval N     Set loop interval (seconds)
+  adelie config --api-key KEY    Set Gemini API key
+  adelie config --lang ko|en     Set display language
+
+Monitoring
+  adelie status                  System health & provider status
+  adelie inform                  Generate project status report
+  adelie phase                   Show current project phase
+  adelie phase set <phase>       Set phase manually
+
+Knowledge Base
+  adelie kb                      Show KB file counts per category
+  adelie kb --clear-errors       Clear error files
+  adelie kb --reset              Reset entire KB (destructive)
+
+Project Management
+  adelie goal                    Show current project goal
+  adelie goal set "..."          Set project goal
+  adelie feedback "message"      Send feedback to the AI loop
+  adelie research "topic"        Search the web and save to KB
+  adelie git                     Show git status & recent commits
+  adelie metrics                 Show recent cycle metrics
+
+Ollama
+  adelie ollama list             List installed models
+  adelie ollama pull <model>     Download a model
+  adelie ollama run [model]      Interactive chat
+
+Telegram
+  adelie telegram setup          Setup bot token
+  adelie telegram start          Start Telegram bot
+```
+
+---
+
+## Environment Variables
+
+All settings are stored in `.adelie/.env` (created by `adelie init`):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LLM_PROVIDER` | `gemini` | `gemini` or `ollama` |
+| `GEMINI_API_KEY` | — | Required for Gemini provider |
+| `GEMINI_MODEL` | `gemini-2.0-flash` | Gemini model name |
+| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama server URL |
+| `OLLAMA_MODEL` | `llama3.2` | Ollama model name |
+| `FALLBACK_MODELS` | — | Comma-separated fallback chain (e.g. `gemini:gemini-2.5-flash,ollama:llama3.2`) |
+| `LOOP_INTERVAL_SECONDS` | `30` | Seconds between loop cycles |
+| `ADELIE_LANGUAGE` | `ko` | Display language (`ko` or `en`) |
+
+---
+
+## Knowledge Base Structure
+
+The KB uses 6 categories:
+
+```
+.adelie/workspace/
+├── skills/          # How-to guides, procedures, capabilities
+├── dependencies/    # External APIs, libraries, services
+├── errors/          # Known errors, root causes, recovery
+├── logic/           # Decision patterns, planning docs
+├── exports/         # Reports, roadmaps, outputs
+└── maintenance/     # System health, status updates
+```
+
+All KB files are Markdown with tag-based and semantic (embedding) retrieval.
+
+---
+
+## Testing
+
+```bash
+# Run all tests
+python -m pytest tests/ -v
+
+# Run specific test file
+python -m pytest tests/test_orchestrator.py -v
+```
+
+Currently **374 tests** covering all agents, context engine, loop detection, scheduling, and more.
+
+---
+
+## Project Structure
+
+```
+Adelie/
+├── adelie/                  # Core package
+│   ├── orchestrator.py      # Main loop controller (state machine)
+│   ├── cli.py               # CLI commands
+│   ├── config.py            # Configuration & env loading
+│   ├── i18n.py              # Internationalization (ko/en)
+│   ├── llm_client.py        # LLM abstraction (Gemini + Ollama)
+│   ├── scheduler.py         # Per-agent scheduling
+│   ├── phases.py            # Project lifecycle phases
+│   ├── hooks.py             # Event-driven plugin system
+│   ├── loop_detector.py     # Stuck-loop detection
+│   ├── context_engine.py    # Per-agent context assembly
+│   ├── context_compactor.py # Token budget enforcement
+│   ├── process_supervisor.py# Subprocess management
+│   ├── feedback_queue.py    # User feedback injection
+│   ├── git_ops.py           # Git auto-commit
+│   ├── web_search.py        # Web search for Research AI
+│   ├── kb/                  # Knowledge Base
+│   │   ├── retriever.py     # Tag + semantic KB retrieval
+│   │   └── embedding_store.py
+│   ├── agents/              # AI agents
+│   │   ├── writer_ai.py     # KB file generation
+│   │   ├── expert_ai.py     # Decision-making
+│   │   ├── coder_ai.py      # Code generation
+│   │   ├── coder_manager.py # Multi-layer coder orchestration
+│   │   ├── reviewer_ai.py   # Code review
+│   │   ├── tester_ai.py     # Test execution
+│   │   ├── runner_ai.py     # Build & deploy
+│   │   ├── monitor_ai.py    # Health checks
+│   │   ├── analyst_ai.py    # Project analysis
+│   │   ├── research_ai.py   # Web research
+│   │   ├── scanner_ai.py    # Codebase scanning
+│   │   └── inform_ai.py     # Status reports
+│   └── integrations/
+│       └── telegram_bot.py  # Telegram integration
+├── tests/                   # 374 tests
+├── bin/                     # Node.js CLI wrapper
+├── scripts/                 # Install scripts
+├── requirements.txt         # Python dependencies
+└── package.json             # npm package config
+```
+
+---
+
+## How It Works
+
+Each orchestrator cycle runs these steps:
+
+1. **Writer AI** creates/updates Knowledge Base files
+2. **Expert AI** reads the KB and makes a structured decision (JSON)
+3. **Research AI** searches the web if the Expert requested external info
+4. **Coder Manager** dispatches code generation tasks by layer
+5. **Reviewer AI** reviews the generated code; retries on failure
+6. **Staging → Project** promotes approved code to the project
+7. **Tester AI** runs tests; retries on failure
+8. **Runner AI** builds and deploys
+9. **Monitor AI** checks health; restarts if needed
+10. **Phase Gates** check if the project is ready for the next phase
+
+The loop runs continuously until shutdown, with the **Scheduler** controlling how often each agent runs and the **Loop Detector** intervening when the system gets stuck.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.
+
+---
+
+<p align="center">
+  Made with Adelie
+</p>

package/adelie/.python-version

@@ -0,0 +1 @@
+3.10

package/adelie/__init__.py

@@ -0,0 +1 @@
+"""Adelie — Self-communicating autonomous AI loop system."""

package/adelie/a2a/__init__.py

@@ -0,0 +1,16 @@
+"""
+adelie/a2a/__init__.py
+
+Agent-to-Agent (A2A) protocol for Adelie.
+Allows external agents to create tasks, query status,
+and receive real-time events.
+"""
+
+from adelie.a2a.types import (
+    TaskState,
+    A2ATask,
+    A2AEvent,
+    EventType,
+)
+
+__all__ = ["TaskState", "A2ATask", "A2AEvent", "EventType"]

package/adelie/a2a/persistence.py

@@ -0,0 +1,83 @@
+"""
+adelie/a2a/persistence.py
+
+Task persistence — stores A2A tasks to disk for durability.
+Inspired by Gemini CLI's a2a-server persistence module.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Dict, Optional
+
+from adelie.a2a.types import A2ATask, TaskState, A2AEvent, EventType
+
+
+class TaskStore:
+    """
+    Persists A2A tasks to JSON files.
+
+    Storage: {store_dir}/{task_id}.json
+    """
+
+    def __init__(self, store_dir: Optional[Path] = None):
+        if store_dir is None:
+            from adelie.config import ADELIE_ROOT
+            store_dir = ADELIE_ROOT / "a2a_tasks"
+        self._dir = store_dir
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._cache: Dict[str, A2ATask] = {}
+
+    def save(self, task: A2ATask) -> None:
+        """Save a task to disk and cache."""
+        self._cache[task.task_id] = task
+        path = self._dir / f"{task.task_id}.json"
+        path.write_text(
+            json.dumps(task.to_dict(), indent=2, ensure_ascii=False),
+            encoding="utf-8",
+        )
+
+    def load(self, task_id: str) -> Optional[A2ATask]:
+        """Load a task from cache or disk."""
+        if task_id in self._cache:
+            return self._cache[task_id]
+
+        path = self._dir / f"{task_id}.json"
+        if not path.exists():
+            return None
+
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            task = A2ATask(
+                task_id=data["task_id"],
+                prompt=data.get("prompt", ""),
+                state=TaskState(data.get("state", "submitted")),
+                created_at=data.get("created_at", ""),
+                updated_at=data.get("updated_at", ""),
+                result=data.get("result", ""),
+                error=data.get("error", ""),
+                metadata=data.get("metadata", {}),
+            )
+            self._cache[task_id] = task
+            return task
+        except Exception:
+            return None
+
+    def delete(self, task_id: str) -> bool:
+        """Delete a task."""
+        self._cache.pop(task_id, None)
+        path = self._dir / f"{task_id}.json"
+        if path.exists():
+            path.unlink()
+            return True
+        return False
+
+    def list_tasks(self) -> list[A2ATask]:
+        """List all persisted tasks."""
+        tasks = []
+        for f in sorted(self._dir.glob("*.json")):
+            task = self.load(f.stem)
+            if task:
+                tasks.append(task)
+        return tasks

package/adelie/a2a/server.py

@@ -0,0 +1,199 @@
+"""
+adelie/a2a/server.py
+
+A2A HTTP server — extends the Gateway with agent-to-agent endpoints.
+
+Endpoints:
+    POST /a2a/tasks          — Create a new task
+    GET  /a2a/tasks           — List all tasks
+    GET  /a2a/tasks/<id>      — Get task status
+    POST /a2a/tasks/<id>/cancel — Cancel a task
+
+Inspired by Gemini CLI's a2a-server HTTP layer.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import threading
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from typing import Any, Callable, Dict, List, Optional
+from urllib.parse import urlparse
+
+from adelie.a2a.types import A2ATask, TaskState, EventType
+from adelie.a2a.persistence import TaskStore
+
+logger = logging.getLogger("adelie.a2a")
+
+
+class A2AServer:
+    """
+    Agent-to-Agent protocol server.
+
+    Can run standalone or alongside the Gateway on a different port.
+    """
+
+    def __init__(
+        self,
+        port: int = 8090,
+        host: str = "127.0.0.1",
+        token: str = "",
+        store: Optional[TaskStore] = None,
+    ):
+        self._port = port
+        self._host = host
+        self._token = token
+        self._store = store or TaskStore()
+        self._server: Optional[HTTPServer] = None
+        self._thread: Optional[threading.Thread] = None
+        self._task_handler: Optional[Callable[[A2ATask], None]] = None
+
+    def start(self) -> bool:
+        """Start the A2A server in background."""
+        if self._server:
+            return False
+        try:
+            handler = _make_a2a_handler(self)
+            self._server = HTTPServer((self._host, self._port), handler)
+            self._thread = threading.Thread(
+                target=self._server.serve_forever,
+                daemon=True,
+                name="adelie-a2a",
+            )
+            self._thread.start()
+            logger.info(f"A2A server started on http://{self._host}:{self._port}")
+            return True
+        except Exception as e:
+            logger.error(f"A2A server start failed: {e}")
+            return False
+
+    def stop(self) -> None:
+        if self._server:
+            self._server.shutdown()
+            self._server = None
+            self._thread = None
+
+    @property
+    def is_running(self) -> bool:
+        return self._server is not None
+
+    def on_task(self, handler: Callable[[A2ATask], None]) -> None:
+        """Register handler for new tasks (called when task is submitted)."""
+        self._task_handler = handler
+
+    # ── Task Operations ──────────────────────────────────────────────────
+
+    def create_task(self, prompt: str, metadata: Dict = None) -> A2ATask:
+        """Create a new task."""
+        task = A2ATask(prompt=prompt, metadata=metadata or {})
+        self._store.save(task)
+        if self._task_handler:
+            self._task_handler(task)
+        return task
+
+    def get_task(self, task_id: str) -> Optional[A2ATask]:
+        return self._store.load(task_id)
+
+    def list_tasks(self) -> List[A2ATask]:
+        return self._store.list_tasks()
+
+    def cancel_task(self, task_id: str) -> bool:
+        task = self._store.load(task_id)
+        if not task or task.is_terminal:
+            return False
+        task.transition(TaskState.CANCELLED)
+        self._store.save(task)
+        return True
+
+    def check_auth(self, headers: dict) -> bool:
+        if not self._token:
+            return True
+        auth = headers.get("Authorization", "")
+        return auth == f"Bearer {self._token}"
+
+
+# ── HTTP Handler ─────────────────────────────────────────────────────────────
+
+
+def _make_a2a_handler(server: A2AServer):
+
+    class A2AHandler(BaseHTTPRequestHandler):
+
+        def log_message(self, format, *args):
+            logger.debug(f"A2A: {format % args}")
+
+        def _send_json(self, data: dict, status: int = 200):
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.end_headers()
+            self.wfile.write(json.dumps(data, ensure_ascii=False, default=str).encode("utf-8"))
+
+        def _read_body(self) -> dict:
+            length = int(self.headers.get("Content-Length", 0))
+            if length == 0:
+                return {}
+            body = self.rfile.read(length)
+            try:
+                return json.loads(body.decode("utf-8"))
+            except Exception:
+                return {}
+
+        def do_GET(self):
+            if not server.check_auth(dict(self.headers)):
+                return self._send_json({"error": "unauthorized"}, 401)
+
+            path = urlparse(self.path).path
+
+            # GET /a2a/tasks
+            if path == "/a2a/tasks":
+                tasks = server.list_tasks()
+                self._send_json({
+                    "tasks": [t.to_dict() for t in tasks],
+                    "count": len(tasks),
+                })
+                return
+
+            # GET /a2a/tasks/<id>
+            m = re.match(r"^/a2a/tasks/([a-f0-9]+)$", path)
+            if m:
+                task = server.get_task(m.group(1))
+                if task:
+                    self._send_json(task.to_dict())
+                else:
+                    self._send_json({"error": "task not found"}, 404)
+                return
+
+            self._send_json({"error": "not found"}, 404)
+
+        def do_POST(self):
+            if not server.check_auth(dict(self.headers)):
+                return self._send_json({"error": "unauthorized"}, 401)
+
+            path = urlparse(self.path).path
+            body = self._read_body()
+
+            # POST /a2a/tasks
+            if path == "/a2a/tasks":
+                prompt = body.get("prompt", "")
+                if not prompt:
+                    return self._send_json({"error": "prompt is required"}, 400)
+                task = server.create_task(prompt, metadata=body.get("metadata", {}))
+                self._send_json(task.to_dict(), 201)
+                return
+
+            # POST /a2a/tasks/<id>/cancel
+            m = re.match(r"^/a2a/tasks/([a-f0-9]+)/cancel$", path)
+            if m:
+                success = server.cancel_task(m.group(1))
+                if success:
+                    self._send_json({"ok": True, "action": "cancelled"})
+                else:
+                    self._send_json({"error": "task not found or already terminal"}, 404)
+                return
+
+            self._send_json({"error": "not found"}, 404)
+
+    return A2AHandler