README.md

# full.llama.cpp.agent.python

# 🦙 LLaMA Local AI Agent

A **fully offline**, powerful, and extendable AI agent that runs **LLaMA 3/gguf models locally** via `llama.cpp`. Supports **Chat, Document Q&A, Vision (OCR + Image Captioning), Voice (STT & TTS)**, and **Tools** like Python exec, browser search, and email generation — all from your machine.

---

## 🧠 Features

- 🔁 LLaMA-3 / GGUF Models (Runs Locally via `llama.cpp`)
- 💬 Chat Interface with History & Token Auth
- 📄 File Upload + Document Q&A (TXT/PDF)
- 🧰 Tools: Calculator, Python Exec, Joke, Web Search
- 🖼️ Image Captioning + OCR
- 🗣️ Voice Transcription (Whisper) + Text-to-Speech (TTS)
- 🔐 JWT Auth for Admin/Users
- 📜 Chat Export with Embedding Search
- 📊 Agent Analytics & Logs
- 🧭 ReAct / LangGraph Planning (Coming Soon)

---

## 🚀 Quick Start

```bash
git clone https://github.com/yourusername/llama-agent
cd llama-agent
docker-compose up --build
```

Then go to `http://localhost:8501` to access the Streamlit UI.

---

## 🧩 Architecture

- `main_api.py`: FastAPI backend (chat, tools, auth, vector store)
- `streamlit_app.py`: Rich UI frontend
- `llama.cpp`: LLM inference backend via `llama_cpp` Python bindings
- `whisper`, `pyttsx3`: Voice STT/TTS
- `duckduckgo_search`, `playwright`: Web tools
- `faiss`, `sentence-transformers`: Vector search
- `PDFMiner`, `Pillow`, `Tesseract`: PDF/Image Processing

---

## 📸 Screenshots

<p align="center">
  <img src="screenshots/agent-ui.png" width="600" />
  <img src="screenshots/chat-demo.png" width="600" />
</p>

---

## 🔧 Tools

### Tool Dispatch Logic

```python
from app.repl_tool import run_code
from app.email_tool import send_email
from app.translation_tool import translate
from app.vision import describe_image

def tool_dispatch(command, args):
    if command == "run_code":
        return run_code(args)
    if command == "send_email":
        return send_email(*args)
    if command == "translate":
        return translate(args)
    if command == "describe_image":
        return describe_image(args)
    return "❌ Unknown command"
```

---

## 🛠️ Logging

```python
import logging

logging.basicConfig(
    filename="agent.log",
    level=logging.INFO,
    format="%(asctime)s | %(levelname)s | %(message)s",
)

def log_event(event: str):
    logging.info(event)
```

---

## 📤 Email Tool

```python
from email.message import EmailMessage
import smtplib, ssl

EMAIL_SENDER = "[email protected]"
EMAIL_PASSWORD = "yourpassword"

def generate_email(recipient_name: str, product_name: str, discount: float):
    return f"""
    Dear {recipient_name},

    Great news! We're excited to offer you a special {discount}% discount on our premium product: {product_name}.

    Visit our site to take advantage of this limited-time offer.

    Best regards,
    Your AI Assistant
    """

def send_email(to, subject, body):
    msg = EmailMessage()
    msg.set_content(body)
    msg["Subject"] = subject
    msg["From"] = EMAIL_SENDER
    msg["To"] = to

    with smtplib.SMTP_SSL("smtp.gmail.com", 465, context=ssl.create_default_context()) as smtp:
        smtp.login(EMAIL_SENDER, EMAIL_PASSWORD)
        smtp.send_message(msg)
    return "✅ Email sent"
```

---

## 📝 License

MIT License — Open-source, feel free to extend it.

---

## 🙏 Credits

- [`llama.cpp`](https://github.com/ggerganov/llama.cpp)
- [`whisper`](https://github.com/openai/whisper)
- [`Streamlit`](https://streamlit.io)