Metadata-Version: 2.4
Name: edgemind
Version: 1.0.2
Summary: Resource-Aware Agentic Coding Assistant for Local AI Software Engineering
Author: Akhilesh Venkiteswaran
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: ollama
Requires-Dist: langgraph
Requires-Dist: langchain
Requires-Dist: pydantic>=2.0
Requires-Dist: typer
Requires-Dist: psutil

<div align = "center">
 
# EdgeMind V2.1

</div>

<div align="center">

## A Resource-Aware Agentic Coding Assistant for Efficient Edge AI Deployment

*"Building intelligent software engineering agents that run locally on consumer hardware."*

![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
![LangGraph](https://img.shields.io/badge/LangGraph-Agentic_Workflow-orange)
![Ollama](https://img.shields.io/badge/Ollama-Local_LLM-green)
![SQLite](https://img.shields.io/badge/SQLite-Enriched_Memory-blue)
![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)
![Status](https://img.shields.io/badge/Status-V2.1_Production_Ready-success)

</div>

---

# 📖 Overview

EdgeMind is a **terminal-first autonomous software engineering assistant** designed to operate **entirely on local hardware**.

Unlike conventional AI coding assistants that rely heavily on cloud infrastructure, EdgeMind focuses on **resource-aware execution**, **dynamic model routing**, **streaming agent activity**, and **context-aware intent routing** to perform complex software engineering tasks locally.

EdgeMind behaves like a senior software engineering companion capable of:

- 🧠 **Context-Aware Intent Routing**: Automatically distinguishes between code execution tasks, follow-up questions ("What did you change?", "Why?"), and conversational architecture discussions.
- ⚡ **Real-Time Streaming Agent Activity**: Live progress updates (`● Understanding request...`, `✓ Found bad.java`, `→ Analyze → Fix → Convert to Python`, etc.).
- 🤖 **Intelligent Model Manager**: Automatically discovers installed local Ollama models (e.g. `qwen2.5-coder:7b`, `codellama`, `phi3`) and uses available local models without forcing unnecessary multi-GB downloads.
- 🛠️ **Autonomous Code Creation & Modification**: Intelligently infers whether a new file is required (e.g. `bad.java` -> `bad.py`) versus modifying an existing file (`fix bad.py`).
- 🛡️ **Hardened Multi-Layer Verification**: Disk-level post-write inspection, syntax validation, backup exclusion, and project-root security boundary enforcement.
- 🗂️ **Enriched SQLite Project Memory**: Remembers execution requests, plans, diffs, analysis findings, and validation results across interactive sessions.

---

# 🎯 Vision

EdgeMind explores a central research question:

> **Can autonomous software engineering agents operate efficiently on local consumer hardware while intelligently adapting to limited computational resources and user intent?**

The project combines:

- Edge AI & Local Inference (Ollama)
- Agentic AI (LangGraph execution graphs)
- Resource-Aware Computing
- Real-Time Streaming Agent Activity
- Persistent Project Memory (SQLite)

---

# ✨ Core Features in V2.1

### 1. Context-Aware Conversation & Follow-Up Routing
EdgeMind distinguishes execution requests from follow-up questions and conversational inquiries:
- **Follow-Up Questions** ("What did you change?", "Why did you change it?", "Explain that"): Loads previous execution context and SQLite history to explain edits without altering files or running new plans.
- **Conversational Queries** ("What do you think about this architecture?", "Do you think this approach is good?"): Responds conversationally using active project context as a pair-programming companion without triggering file edits.

### 2. Real-Time Streaming Agent Activity
Exposes safe, user-facing agent activity events live during execution:
```text
  ● Understanding request...
  ● Identifying source file...
  ✓ Found bad.java
  ● Determining requested operation...
  → Analyze → Fix → Convert to Python
  ● Creating execution plan...
  ✓ 3 tasks planned
  ● Analyzing bad.java...
  ✓ Analysis complete
  ● Generating Python implementation...
  ✓ Generated bad.py
  ● Validating generated code...
  ✓ Python syntax valid
  ● Reviewing changes...
  ✓ Source preserved
```

### 3. Intelligent Model Manager & First-Run Setup
- Automatically detects installed local Ollama models.
- Uses existing local models (e.g. `qwen2.5-coder:7b`, `codellama`, `deepseek-coder`, `phi3:mini`) without requiring downloads.
- If no model is present, recommends a resource-aware fallback (`qwen2.5-coder:3b`) and prompts before downloading (`Download model? [Y/n]`).

### 4. Enriched Execution Summary & File Review
Reports comprehensive file status and validation results:
```text
Files Status:
  Created  : bad_algorithm.py (NEW FILE)
  Modified : None
  Preserved: bad.java (UNTOUCHED)

Validation & Review:
  ✓ Source file preserved: /path/to/bad.java
  ✓ Target file created: /path/to/bad_algorithm.py
  ✓ Syntax validation passed: Validation Passed
```

---

# 🏗️ Architecture

```text
                       User Prompt
                            │
                            ▼
                  Intent Router (V2.1)
           ┌────────────────┼────────────────┐
           ▼                ▼                ▼
     Conversational     Follow-Up         Execution
        Handler          Handler           Request
           │                │                │
           │           (Load Memory          ▼
           │           & SessionState)  LangGraph Engine
           │                │           (Planner -> Discover ->
           │                │            Router -> Executor ->
           │                │            Reviewer -> Memory)
           └────────────────┼────────────────┘
                            │
                            ▼
                 Activity Streamer & CLI
```

---

# ⚙️ Installation & Setup

## Install via PyPI

```bash
pip install edgemind
```

To upgrade an existing installation:

```bash
pip install -U edgemind
```

Launch the interactive CLI shell:

```bash
edgemind
```

---

## Install from Source

```bash
git clone https://github.com/Akhilesh-Venkiteswaran/EdgeMind.git
cd EdgeMind
python3 -m venv venv
source venv/bin/activate
pip install -e .
```

---

## Prerequisites

1. **Ollama**: Download from [https://ollama.com](https://ollama.com)
2. **Local Models**: EdgeMind automatically detects any installed model. Recommended models:
   ```bash
   ollama pull qwen2.5-coder:3b
   ```

---

# 🧪 Running Tests

Run the complete test suite:

```bash
# Deterministic Unit Tests (No Ollama required)
pytest -m "not ollama" -v

# Live Ollama Integration Tests
pytest -m ollama -v

# Complete Test Suite (All 40+ tests)
pytest -v
```

---

# 📜 License

MIT License. Free to use, modify, and distribute.
