llm-iaedu

Plugin for LLM that enables using the iaedu.pt API as a model — no adapter, no Docker.

Quick Start

Linux / macOS

# Install
pip install llm-iaedu

# Configure credentials (Endpoint, API Key, Channel ID)
llm-iaedu configure

# Ask anything
llm -m iaedu "What is the capital of Portugal?"

# Optional — make iaedu the default model:
llm models default iaedu
llm "What is the capital of Portugal?"

Ubuntu / Debian (PEP 668)

Ubuntu 23.04+ blocks system-wide pip install. Use one of:

Option 1: pipx (if you already pipx install llm):

# Install plugin into llm's venv
pipx inject llm llm-iaedu

# One-time setup — paste 3 values from iaedu.pt:
llm iaedu-configure

# That's it — no need for `llm keys set iaedu`
llm -m iaedu "What is the capital of Portugal?"

To upgrade after install:

pipx runpip llm install --upgrade llm-iaedu

Option 2: Virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install llm-iaedu
llm-iaedu configure
llm -m iaedu "What is the capital of Portugal?"

Option 3: From git clone:

git clone https://github.com/rodolfomatos/llm-iaedu.git
cd llm-iaedu
make ubuntu-setup   # shows instructions
make configure      # interactive credential setup
make check          # verify everything works

Setup

Quick (interactive) — one step

# From git clone (has Makefile):
make configure

# From pip install (no repo):
llm-iaedu configure

# From pipx inject (llm subcommand):
llm iaedu-configure

Paste the three values from iaedu.pt (Endpoint URL, API Key, Channel ID) when prompted. The script creates ~/.config/iaedu/env with everything needed — no llm keys set iaedu required, works from any directory.

Manual

Create ~/.config/iaedu/env:

IAEDU_ENDPOINT=https://api.iaedu.pt/agent-chat/api/v1/agent/your-agent-id/stream
IAEDU_CHANNEL_ID=your-channel-id
IAEDU_API_KEY=your-api-key

Or place a .env in any project directory for local config.

Config Precedence

1. Current shell (export IAEDU_*)
2. ./.env (local)
3. ~/.config/iaedu/env (global)
4. ~/.iaedu.env (legacy)

Usage

# One-off
llm -m iaedu "What is the capital of Portugal?"

# Default model (just skip -m)
llm models default iaedu
llm "What is the capital of Portugal?"

# Interactive chat
llm chat -m iaedu

# Pipe input
cat file.txt | llm -m iaedu

Development

git clone https://github.com/rodolfomatos/llm-iaedu.git
cd llm-iaedu

# Standard
make setup
# ... or Ubuntu/Debian:
make ubuntu-setup
# ... or pipx:
make pipx-setup

make configure
make check

How it works

The plugin calls the iaedu.pt API directly — no adapter server required. It loads config from environment variables or .env files, sends prompts as multipart form data, and streams token responses.

Requirements

• Python 3.8+
• llm CLI
• iaedu.pt account with API key, channel ID, and agent ID

Project

• VISION — problem, solution, value proposition
• REQUIREMENTS — functional and non-functional
• ROADMAP — backlog and progress
• CHANGELOG — version history
• CLAUDE.md — operational contract for AI agents