> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleverschool.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Tools

> Operational Workflows & Agent Architecture

## End-to-End AI Lifecycle & Tool Architecture

The AI Tools module provides school staff with secure, privacy-conscious artificial intelligence capabilities while ensuring administrative oversight, document grounding, and token governance.

```mermaid theme={null}
flowchart TD
    subgraph AdminTrack["Administrative Setup & RAG Architecture"]
        A1["1. Administrator defines AI Support Agent<br/>(Name, Description, System Instructions, Disclaimer)"]
        A2["2. Administrator attaches School Policy Documents<br/>(PDFs, Handbooks, Staff Guidance)"]
        A3["3. Automatic Vector Store Indexing & Semantic Embedding"]
        A1 --> A2 --> A3
    end

    subgraph StaffTrack["Staff Interaction & Content Generation"]
        S1["Staff accepts AI Terms of Use"]
        S2{"Select AI Capability"}
        S3["AI Image Studio<br/>• Text-to-Image Generation (Square, Landscape, Portrait)<br/>• Image Upload & Inpainting/Modification<br/>• Personal Asset Gallery"]
        S4["Custom Support Chat (RAG)<br/>• Real-time Streaming Responses<br/>• Vector Store FileSearch Citations<br/>• Human-in-the-Loop Safeguards"]
        S5["General Chat Assistant<br/>• Lesson Plan Ideation<br/>• Social Stories Drafting<br/>• Professional Communication"]
        
        S1 --> S2
        S2 --> S3
        S2 --> S4
        S2 --> S5
    end

    subgraph AuditTrack["Governance & Telemetry"]
        T1["Real-Time Token Usage Logging<br/>(Prompt Tokens, Completion Tokens, Total Tokens)"]
        T2["Per-Staff Telemetry & Activity Auditing"]
        S3 --> T1
        S4 --> T1
        S5 --> T1
        T1 --> T2
    end

    A3 -.->|Grounds Knowledge Base| S4
```

***

## 1. AI Terms of Use & Access Verification

To maintain data protection compliance and ethical usage standards across school tenants:

**1. Access AI Tools**

Staff navigate to **AI Tools** from the main application sidebar.

**2. Review Acceptable Use Policy**

Before accessing interactive generative tools, staff must review the **AI Terms of Use** (`/ai/terms`).

**3. Acknowledge Guidelines**

Staff acknowledge critical safeguarding and privacy principles:

* **No PII Input**: Never enter pupil identifiable data, confidential safeguarding notes, or sensitive medical records into generative prompts.
* **Human in the Loop**: AI-generated responses must always be reviewed by a human professional prior to taking educational or operational action.

***

## 2. Image Studio & Creative Generation Workflow

The Image Studio (`/ai/images`) allows staff to generate and modify high-resolution educational illustrations without requiring third-party accounts:

### Generation from Text Prompts

1. Navigate to **AI Tools** > **AI Images**.
2. Select the desired aspect ratio:
   * **Landscape** (16:9): Ideal for presentation slides, website banners, and display boards.
   * **Square** (1:1): Suitable for worksheets, flashcards, and student profile icons.
   * **Portrait** (9:16): Optimised for posters, parent newsletters, and mobile announcements.
3. Enter a descriptive image prompt (e.g. *"A friendly cartoon owl sitting in a library reading a book"*).
4. Click **Generate**. The synthesised image is processed and saved to your personal gallery.

### Image Manipulation & Inpainting

* Staff can upload existing images (PNG, JPG, or GIF) to perform contextual modifications.
* Provide targeted instructions (e.g. *"Add a graduation cap to the student and replace the background with a science laboratory"*).
* Download the generated assets directly or manage saved items in **Your images** gallery.

***

## 3. Custom Support Agent & Document Grounding (RAG)

School leaders can configure dedicated AI support agents grounded in school policies, staff handbooks, and operational guides:

```mermaid theme={null}
flowchart LR
    StaffQuery["Staff queries Agent in Chat"] --> FileSearch["FileSearch Retrieval Engine"]
    FileSearch --> VectorStore["Indexed Policy Documents"]
    VectorStore --> Context["Relevant Policy Excerpts"]
    Context --> Model["LLM Synthesis"]
    Model --> VerifiedResponse["Streaming Response with Document Citations"]
```

### Step 1: Agent Definition

In **AI Administration** (`/ai/admin`), an Administrator clicks **New Agent** and configures:

* **Name & Description**: Identifies the agent's role (e.g. *HR & Staff Policy Assistant*, *Curriculum Guidance Bot*).
* **System Instructions**: Defines persona, tone, and boundary conditions (e.g. *"Base all policy answers strictly on uploaded documents; cite the specific document name"*).
* **Disclaimer**: Explains the human-in-the-loop verification protocol displayed above every chat session.

### Step 2: Document Indexing

1. Select the agent and open **Agent Documents** (`/ai/admin/chat/{agent}`).
2. Upload school policy documents (PDF, Word, or plain text).
3. The system parses document chunks, generates semantic embeddings, and stores them in a secure tenant vector store.

### Step 3: Staff Support Chat

* Staff open the assigned agent from the AI portal (`/ai/chat/{agent}`).
* Real-time streaming generates immediate responses while querying the grounded document library.
* The agent provides transparent citations referencing the exact policy document name and section used to formulate the answer.

***

## 4. General Assistant & Social Stories Workflow

Staff can leverage the general assistant (`/ai/chat-gpt`) for routine educational drafting tasks:

* **Lesson Planning & Differentiation**: Brainstorming scaffolding strategies, Tier 2/Tier 3 vocabulary exercises, and stretch tasks.
* **Social Stories Generation**: Generating empathetic, structured social narratives for SEN/pastoral support explaining upcoming routine changes (e.g. fire drills, school trips, or timetable changes) tailored for specific pupil age groups.
* **Drafting Correspondence**: Formulating professional newsletter blurbs or parent invitations.

***

## 5. Token Telemetry & Activity Auditing

To ensure budget control and oversight, the module tracks token consumption across all generative operations:

> [accordion] Real-Time Telemetry Metrics
>
> * **Prompt Tokens**: Volume of tokens consumed in input instructions, system prompts, and retrieved document context.
> * **Completion Tokens**: Volume of tokens generated in model responses and image generation.
> * **Total Tokens**: Cumulative computation cost logged per interaction.

> [accordion] Staff Activity Log (/ai/activity)
>
> * Administrators can inspect tenant-wide activity or filter by individual staff member.
> * Shows chronological timestamps, tool used (Chat, Support Agent, Images), and token totals.

***

## Next Steps & Guides

> [card] [Introduction & Architecture](https://docs.cleverschool.systems/ai/introduction.md)
>
> Understand role permissions, vector stores, and RAG anti-hallucination mechanics.

> [card] [Tutorials & Practical Guides](./tutorials)
>
> Practical walkthroughs for generating images, uploading policies, and querying agents.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.