Academy AI Assistant — Free/Test Edition

A free-to-run fork of Academy AI Assistant, for testing a source-restricted AI teaching assistant on academy-tech.ir without a paid API account.

Same feature set, same architecture, same "approved sources only" guarantee — the only change is the AI provider.

What's different from the paid edition

The original plugin uses Claude (chat) + OpenAI (embeddings), both paid APIs. This edition replaces both with Google Gemini, which offers a genuinely free tier (no credit card required) through Google AI Studio:

Everything else — the RAG pipeline, the source-restriction guarantee, the WP-Cron async job queue, the DB schema, the REST API shape — is identical in design to the paid edition, just renamed (AAI_ → AAIF_ class prefix, separate DB tables, separate REST namespace) so the two plugins could technically run side by side without colliding, though running one at a time is the normal case.

Why this exists

You (the site owner) wanted to test the assistant end-to-end — chat Q&A, hint-giving on code submissions, and grading — before committing to a paid Claude account. This lets you validate the whole flow on Google's free tier first, then flip to the Claude edition later if you need the higher rate limits or answer quality of a paid model for production use.

Free tier limits to know going in: Google's free Gemini tier enforces per-minute and per-day request caps (specifics vary by model/account, check your Google AI Studio dashboard). It's fine for a handful of test students; it is not meant to carry a full class's traffic indefinitely. If you outgrow it, either request a paid Gemini tier (same code, no plugin changes — just billing) or switch to the Claude edition.

Source restriction (the core requirement — unchanged)

The assistant's knowledge is only what you put in AI Sources (WP Admin → AI Sources). Nothing else is ever passed to the model as fact:

1. On publish, a source's content is chunked (AAIF_Chunker) and embedded via Gemini (AAIF_Gemini_Client::embed), then stored in wp_aaif_source_chunks.
2. On a student question, the question itself is embedded and compared against stored chunks (AAIF_Vector_Store::search); only the best-matching chunks become "context."
3. The system prompt (AAIF_Prompts) hard-instructs Gemini to answer only from that context and to explicitly say "I don't have that information" rather than guess.
4. An AI Source can be scoped to one course or left global (available to every course).

If you never add anything under AI Sources, the assistant will consistently say it has no information — by design.

Note on free-tier model reliability: smaller/free-tier models follow "don't use outside knowledge" instructions somewhat less consistently than a larger paid model. Spot-check answers during testing, especially for topics where the model might have strong general-knowledge priors that could leak through despite the system prompt.

Requirements

• WordPress 5.8+, PHP 7.4+, MySQL/MariaDB (standard on virtually all hosts).
• LearnPress active.
• A free Google AI Studio API key — no billing setup required for the free tier.
• Outbound HTTPS access from your host to generativelanguage.googleapis.com (allowed on virtually all shared hosts).

Installation

1. Zip the contents of this folder (or clone the repo) so the plugin's root files sit directly under a folder named academy-ai-assistant-free.
2. Upload via WP Admin → Plugins → Add New → Upload Plugin, or by SFTP into wp-content/plugins/academy-ai-assistant-free/.
3. Activate the plugin. This creates two tables: wp_aaif_source_chunks and wp_aaif_jobs.
4. Go to aistudio.google.com/apikey, sign in with a Google account, and generate a free API key.
5. Go to Settings → Academy AI Assistant (Free) and paste the key in.
6. Go to AI Sources → Add Approved Source, paste in the material the assistant is allowed to use (course notes, rubrics, answer keys), optionally scope it to a course, and publish. Re-indexing runs a couple of seconds later via WP-Cron.

Do not activate this alongside the paid edition on the same site — while table/route names are namespaced separately to avoid hard collisions, running both is untested and not the intended use; pick one.

Using it on the site

[aaif_chat_widget]

Floating "Ask AI" chat bubble. Only visible to logged-in users. Automatically scopes retrieval to the current course when placed on a course/lesson page.

[aaif_practice_check]

A code textarea with Get a Hint and Grade My Practice buttons. Submits to the job queue and polls until a result is ready.

Quiz grading for open-ended answers

LearnPress only auto-grades objective question types. For free-text answers, call the REST endpoint directly from your quiz results template:

fetch(AAIF_Settings.restUrl + 'grade-quiz-answer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-WP-Nonce': AAIF_Settings.nonce },
  body: JSON.stringify({ answer: studentAnswerText, question_id: questionId, course_id: courseId }),
}).then(r => r.json()).then(({ job_id }) => { /* poll GET /job/{job_id} */ });

LearnPress assignment/quiz submission hooks

AAIF_Assignment_Hooks and AAIF_Quiz_Hooks attempt best-effort integration with LearnPress hooks so grading can fire automatically on submission. These hook names vary across LearnPress core vs. add-ons and across versions — verify against your actual install before relying on them. The [aaif_practice_check] shortcode is the dependable fallback regardless.

REST API

All routes are under /wp-json/academy-ai-free/v1/ (note the different namespace from the paid edition's /academy-ai/v1/, so both could run without route collisions) and require a logged-in user (X-WP-Nonce header).

Data model

• wp_aaif_source_chunks — source_id, chunk_index, content, embedding (JSON), created_at.
• wp_aaif_jobs — job_type, status, user_id, ref_id, input (JSON), result (JSON), error, created_at, updated_at.
• aaif_source (custom post type) — the approved-content library. Post meta _aaif_course_id scopes a source to a course; absent = global.

File structure

academy-ai-assistant-free.php   Plugin bootstrap
uninstall.php                   Drops plugin tables/options on uninstall (keeps AI Source content)
includes/
  class-aaif-activator.php      Creates DB tables on activation
  class-aaif-chunker.php        Splits source text into overlapping chunks
  class-aaif-gemini-client.php  Google Gemini API wrapper (chat + embeddings, one client)
  class-aaif-vector-store.php   Chunk storage + brute-force cosine-similarity search
  class-aaif-prompts.php        All system prompts (grounding/guardrail wording lives here)
  class-aaif-jobs.php           Async job table CRUD
  class-aaif-job-processor.php  Runs queued jobs on WP-Cron
  class-aaif-source-cpt.php     "AI Source" custom post type + re-indexing on save
  class-aaif-rest-routes.php    REST API endpoints
  class-aaif-assignment-hooks.php  Best-effort LearnPress assignment integration
  class-aaif-quiz-hooks.php     Best-effort LearnPress quiz integration
  class-aaif-admin-settings.php Settings → Academy AI Assistant (Free) page
  class-aaif-frontend.php       Shortcodes + asset enqueueing
assets/
  css/chat-widget.css
  js/chat-widget.js             [aaif_chat_widget] behavior
  js/practice-check.js          [aaif_practice_check] behavior

Security notes

• The API key is stored as a WordPress option (aaif_gemini_api_key) — visible only to admins in Settings, never exposed to the frontend.
• All REST routes require is_user_logged_in(); job results are scoped to their creating user.
• All DB access uses $wpdb->prepare()/parameterized $wpdb methods; all output is escaped (esc_html, esc_attr, esc_url_raw).
• Nonces guard all state-changing requests.

Known gaps / next steps

• LearnPress hook names are unverified against the specific LearnPress version/add-ons running on academy-tech.ir — see callouts in class-aaif-assignment-hooks.php and class-aaif-quiz-hooks.php.
• Course-detection meta key (_lp_course) is a best-effort guess — confirm against your LearnPress version's actual post meta.
• JSON grading reliability: free-tier flash models follow strict-JSON-only instructions less consistently than Claude, so this edition uses Gemini's native responseMimeType: application/json mode plus a markdown-fence-stripping fallback (see class-aaif-job-processor.php) — worth spot-checking grading output during testing.
• At larger scale (many thousands of chunks, high concurrent chat volume, or exceeding free-tier rate limits), move to a real vector DB, a proper job queue, and/or a paid model tier.
• No admin UI yet for browsing job history/results across all students — query wp_aaif_jobs directly if needed.

License

Proprietary — built for academy-tech.ir testing purposes. Not licensed for redistribution.