Metadata-Version: 2.4
Name: akasa-mas
Version: 0.1.0
Summary: Akasa-MAS: The Agentic Orchestrator for Educational RAG Pipelines
Author-email: Akasa-MAS Contributors <muhammadikhwanfathulloh17@gmail.com>
Project-URL: Homepage, https://github.com/Muhammad-Ikhwan-Fathulloh/Akasa-MAS
Project-URL: Bug Tracker, https://github.com/Muhammad-Ikhwan-Fathulloh/Akasa-MAS/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: scikit-learn>=1.0
Requires-Dist: pydantic>=2.0

# Akasa-MAS (The Agentic Orchestrator)

Akasa is the primary orchestrator that acts as the "brain" of your educational AI system. It decides when to use traditional ML models, localized LLMs (like Qwen 1.5B), or advanced reasoning LLMs (like Qwen 3B).

To be used alongside [Sutra-RAG](https://pypi.org/project/sutra-rag/) and [Mandala-GNN](https://pypi.org/project/mandala-gnn/).

## Key Features

1. **Smart Triage (Intent Classifier)**: A traditional ML model (e.g., Random Forest/SVM) that inspects input:
   - *Simple Input*: Answered directly by a template/traditional ML.
   - *Technical Input*: Routed to Qwen 1.5B.
   - *Reasoning Input*: Routed to Qwen 3B.

2. **Reinforcement Learning for Adaptation (RL)**:
   - *Memory Buffer*: Stores (Student State, Agent Action, Reward/Result).
   - *Policy Update*: Uses historical data to optimize the prompt sent to the LLM (Automated Prompt Tuning).

3. **Agent Roles**:
   - *Learner Profiling Agent*: Monitors student psychology and progress.
   - *Evaluation Agent*: Diagnoses misconceptions.
   - *Coordinator Agent*: Orchestrates the turn-taking of other agents.

## Installation
```bash
pip install akasa-mas
```

## Quick Start
```python
from akasa.orchestrator import AkasaOrchestrator
from akasa.rl_buffer import SQLiteMemoryBuffer

# 1. Custom model routing (Swap LLMs to your preference)
custom_routing = {
    "simple": "Local-Regex-Template",
    "technical": "Qwen-1.5B-Local",
    "reasoning": "Qwen-3B-Cloud"
}

# 2. Inject your own Database / Memory interface (e.g. MySQL, PgVector)
# For the simplest setup, use the built-in SQLite buffer.
memory = SQLiteMemoryBuffer(db_path="demo_memory.db")

orchestrator = AkasaOrchestrator(
    memory_buffer=memory,
    model_routing=custom_routing
)

user_query = "Why does the moon shine?"
route_info = orchestrator.process_request(user_id="std_01", query=user_query)

print(f"Routing to: {route_info['target_model']}")
print(f"Optimized Prompt: {route_info['optimized_prompt']}")
```

## Integration with Sutra-RAG and Mandala-GNN

Akasa-MAS is designed to sit at the top of the stack:
- **Akasa-MAS**: Orchestrates the intent and final prompt tuning.
- **Sutra-RAG**: Provides retrieval context for factual accuracy.
- **Mandala-GNN**: Manages learning paths and structured knowledge graphs.

Check `examples/02_full_stack_orchestration.py` for a complete implementation.

## Examples Breakdown

- **[01_fastapi_integration.py](examples/01_fastapi_integration.py)**: Basic lifecycle with routing and feedback.
- **[02_full_stack_orchestration.py](examples/02_full_stack_orchestration.py)**: Integration with **Sutra-RAG** and **Mandala-GNN**.
- **[03_custom_memory_adapter.py](examples/03_custom_memory_adapter.py)**: How to use an external database (Postgres, MySQL).
- **[04_training_custom_classifier.py](examples/04_training_custom_classifier.py)**: Training the intent model with your own dataset.
- **[05_advanced_agent_hooks.py](examples/05_advanced_agent_hooks.py)**: Manually using and extending the agents.

## Custom RL Buffer

You can inject your own database (MySQL, PostgreSQL, etc.) by implementing `BaseMemoryBuffer`:

```python
from akasa.rl_buffer import BaseMemoryBuffer

class MyPostgresBuffer(BaseMemoryBuffer):
    def add_experience(self, state, action, reward):
        # Your SQL implementation here
        pass
    
    def get_successful_actions(self, limit=3):
        # Return successful metadata
        return []

orchestrator = AkasaOrchestrator(memory_buffer=MyPostgresBuffer())
```
