🤖 Eco-Tech Knowledge - AI Engineering Toolkit V2

This reorganized toolkit (V2) is designed for Technical Watch in the field of Impact of Digital Technologies on social and environmental sphere. It automates the extraction of structured insights from URLs (PDFs, reports, articles) and generates Hugo-compatible markdown files for resource monitoring.

The project structure is inspired by elite AI engineering patterns, featuring a clean separation between the agentic logic and the API backend.

📁 Project Structure

• agent/: Core intelligence layer.
  • core/: LangGraph workflow orchestration (graph.py).
  • services/: Modular LLM, Scraper, and Arxiv providers.
  • tools/: Specialized tools used by the agents.
  • prompts/: Versioned English prompts with Jinja2 template support.
  • context_manager/: Advanced conversation history and token limit management.
  • analytics/: LLMOps session tagging for performance tracking.
• backend/: FastAPI implementation.
  • routes/: Domain-specific API endpoints (Chat, Extraction, Session, Config).
  • services/: Non-agent services like Hugo file generation and session persistence.
• frontend/: Modern React (Vite/MUI) streaming chat interface (ported from ml-intern).
• configs/: Centralized settings and environment variable management.
• models/: Shared Pydantic schemas for data validation.

---

🚀 Getting Started

1. Prerequisites

• Python 3.14+ with uv package manager.
• Node.js with pnpm for the frontend.
• LM Studio (optional, for local inference).

2. Installation

Backend

cd adagent
uv sync

Frontend

cd adagent/frontend
pnpm install
pnpm run build

---

3. Configuration (.env)

Create a .env file in the adagent/ directory. You can use the following template:

# --- LLM Provider Configuration ---

# Option A: Local Usage (via LM Studio)
OPENAI_API_BASE=http://localhost:1234/v1
OPENAI_API_KEY=lm-studio
MODEL_NAME=unsloth/Llama-3.2-3B-Instruct-GGUF

# Option B: Cloud Providers (Set the key for your preferred provider)
MISTRAL_API_KEY=your_mistral_key
GOOGLE_API_KEY=your_gemini_key
GROQ_API_KEY=your_groq_key
CROQ_API_KEY=your_xai_grok_key  # For x.ai (Grok)

# --- Publishing & Production (GitHub PR mode) ---
PUBLISH_MODE=dev              # Use "prod" to enable GitHub PR creation
GITHUB_TOKEN=your_gh_token
GITHUB_OWNER=les-enovateurs
GITHUB_REPO=eco-tech-knowledge

# --- Agent Parameters ---
MAX_TOKENS=4096
TRUNCATE_LIMIT=30000
CHUNK_SIZE=5000
MAX_HIGHLIGHTS=10

# --- Monitoring ---
PHOENIX_PROJECT_NAME=eco-tech-agents

---

4. Running the Application

First, activate the virtual environment:

cd adagent
source .venv/bin/activate

You have two ways to run the project:

Direct Execution

From the adagent/ directory (after activating venv):

uv run uvicorn backend.main:app --reload

The backend will be available at http://localhost:8000. If you have built the frontend, it will be served at the root.

Development Mode (Frontend Proxy)

If you want to edit the React frontend with hot-reload:

1. Start the backend: uv run uvicorn backend.main:app (on port 8000).
2. Start the frontend:

   cd adagent/frontend
   pnpm run dev

   (Note: This is a Vite project on port 5173).
3. Access the UI at http://localhost:5173.

📊 Observability (Arize Phoenix)

To track your agent's traces, tokens, and logic in real-time. Run this from the adagent/ directory (after activating venv):

cd adagent
source .venv/bin/activate
uv run phoenix serve

Access the dashboard at http://localhost:6006.

---

🌟 Key Features

1. Multi-Model Factory: Supports local models (LM Studio), Gemini, Mistral, Groq, and Grok out of the box.
2. Advanced Context Manager: Automatically summarizes conversation history and handles dangling tool calls to prevent LLM crashes.
3. Language Integrity: Although prompts are in English, the agent detects the source document's language and generates the Hugo resource file in that same language.
4. Surgical Audit: Every extracted statistic is fuzzy-matched against the source text to calculate a confidence_score. Low-confidence points are automatically sent to an Auditor agent.
5. Learning Loop: Every analysis performed is "learned" by the chat agent, allowing you to ask cross-document questions within the same session.

📊 Quality & Benchmarking

Use the scripts in the benchmarks/ folder to evaluate model performance against a reference dataset:

cd adagent
source .venv/bin/activate
uv run benchmarks/benchmark.py

🧪 Tests & Telemetry

• Run tests: source .venv/bin/activate && uv run pytest
• Launch Telemetry (Arize Phoenix): source .venv/bin/activate && uv run phoenix serve