StudentSafeAI

StudentSafeAI is a supervised research assistant that gives students access to AI-generated research responses via email, with mandatory parental approval before any response is delivered.

A student sends a question by email. The application generates an age-appropriate, cited research essay using OpenAI's GPT-5.4 (or optionally GPT-5.4 Pro) and forwards it to a parent or guardian for review. The response is only delivered to the student after the parent replies with approval.

How It Works

1. Student sends a question -- The student emails their question to the application's inbox (provisioned automatically via AgentMail).
2. AI generates a research response -- The question is sent to OpenAI's GPT-5.4 (configurable) with a system prompt that enforces academic tone, source citations, age-appropriate language, and structured essay format.
3. Parent reviews the response -- The generated response is emailed to the parent along with the original question. The parent is asked to reply with the word "approved" to release it.
4. Student receives the approved response -- Once the parent approves, the response (with the original question) is delivered to the student.

Student                    StudentSafeAI                   Parent
  |                              |                            |
  |-- Question email ---------->|                            |
  |                              |-- Query GPT-5.4 ------------->|
  |                              |<-- Research response ------|
  |                              |-- Response for approval ->|
  |                              |                            |
  |                              |<-- "approved" ------------|
  |<-- Approved response --------|                            |

Features

• Parental approval gate -- No AI-generated content reaches the student without explicit parent approval.
• Age-appropriate responses -- The system prompt is configured with the student's age and instructs the model to use appropriate vocabulary and complexity.
• Structured research format -- Responses are formatted as 6-10 paragraph essays with source citations, assumption analysis, cross-domain analogies, and suggestions for further research.
• Daily question limit -- A configurable cap on how many questions a student can ask in a rolling 24-hour window. When exceeded, the student receives an email with the time they can try again.
• HTML email formatting -- Responses render markdown bold as proper HTML bold in email clients, with clear "Question" and "Response" labels.
• Persistent state -- SQLite database tracks processed messages, pending approvals, and question counts across restarts.
• Graceful restart -- The application recovers its inbox and state on restart without reprocessing old messages.
• Docker support -- Ships with a multi-stage Dockerfile and docker-compose configuration with a persistent data volume.

Prerequisites

• Node.js 20 or later (for local development)
• Docker and Docker Compose (for containerized deployment)
• An OpenAI API key with access to GPT-5.4 (or GPT-5.4 Pro)
• An AgentMail API key

Quick Start

1. Clone the repository

git clone https://github.com/JonesSteven/studentsafeai.git
cd studentsafeai

2. Configure environment variables

cp .env.example .env

Edit .env with your values:

Variable	Description
OPENAI_API_KEY	Your OpenAI API key
AGENT_MAIL_API_KEY	Your AgentMail API key
STUDENT_EMAIL	The student's email address
PARENT_EMAIL	The parent/guardian's email address
STUDENT_AGE	The student's age (used to tailor response complexity)
MAX_DAILY_QUESTIONS	Maximum questions the student can ask in a 24-hour period
MODEL	(Optional) Set to GPT54PRO to use GPT-5.4 Pro. Defaults to GPT-5.4 if omitted

3a. Run with Docker (recommended)

docker compose up --build -d

The application data (SQLite database) is persisted in a Docker volume called app-data.

To view logs:

docker compose logs -f app

To stop:

docker compose down

3b. Run locally

npm install
npm start

For production builds:

npm run build
npm run start:prod

Project Structure

studentsafeai/
  src/
    index.ts        -- Application entry point and startup flow
    config.ts       -- Environment variable loading and validation
    agentmail.ts    -- AgentMail inbox creation, email sending, message listing
    poll.ts         -- Message polling loop, question handling, approval flow
    db.ts           -- SQLite database schema and data access functions
    openai.ts       -- OpenAI GPT-5.4 / GPT-5.4 Pro integration
  systemprompt.md   -- System prompt template (age is injected at runtime)
  Dockerfile        -- Multi-stage Docker build
  docker-compose.yml
  .env.example      -- Template for required environment variables

System Prompt

The system prompt (systemprompt.md) instructs the AI to:

• Write responses as structured essays (6-10 paragraphs)
• Use an impersonal, academic tone
• Challenge assumptions in the question
• Include the latest research with links
• Draw analogies to other fields
• Suggest further areas of research
• Cite at least 3 credible sources with hyperlinks
• Use vocabulary appropriate for the configured student age
• Only include verifiable factual claims

The {{STUDENT_AGE}} placeholder is replaced at runtime with the value from the .env file.

Daily Question Limit

The MAX_DAILY_QUESTIONS environment variable controls how many questions a student can submit in a rolling 24-hour window. When the limit is reached, the student receives an email stating:

The maximum number of questions has been asked today. Please try again at [time].

The time shown is when the oldest question in the current window ages past 24 hours, opening a new slot.

Data Storage

The application uses a SQLite database stored at data/studentsafeai.db (or /app/data/studentsafeai.db inside Docker). The database contains:

• app_state -- Key-value store for persistent configuration (inbox ID, deployment timestamp, welcome email status)
• processed_messages -- Tracks which messages have been handled to prevent reprocessing
• student_questions -- Records timestamps of student questions for rate limiting
• pending_approvals -- Stores the student's question and AI response while awaiting parental approval

Disclaimer

This software is provided as an open-source example. It is not legal advice, compliance advice, or a production-ready policy framework. Deployers are solely responsible for ensuring their use complies with applicable law, institutional policy, and child-safety requirements. See DISCLAIMER.md and LICENSE.md for full details.

License

This project is licensed under the MIT License. See LICENSE.md for the full license text and additional disclaimers.