compusly

Inspiration

During my time at university, I witnessed countless students spending hours navigating administrative offices, often visiting the wrong bureau multiple times before finding the right one. The frustration of not knowing where to go for a simple transcript or which documents were needed for registration was universal. This administrative maze wasted valuable study time and added unnecessary stress to already challenging academic lives.

The situation was compounded by scattered course materials. Students struggled to efficiently review lengthy PDFs before exams, manually creating study materials that AI could generate in seconds. I realized that the same AI technology revolutionizing other industries could solve these practical problems for Algerian university students.

This project was born from a simple question: What if students had an intelligent assistant that knew every administrative procedure and could transform any document into personalized study materials?

What it does

Compusly AI is a RESTful API backend that provides two core services:

Administrative Intelligence: Students ask natural language questions about university procedures, and the system provides accurate, contextual answers. It knows the location, hours, and responsibilities of every administrative bureau across multiple Algerian universities. Whether a student needs to authenticate documents, transfer between universities, or apply for scholarships, the assistant guides them with step-by-step instructions.

Academic Document Processing: Students upload PDF course materials, and the system automatically generates comprehensive study aids. The AI extracts text, creates concise summaries highlighting key concepts, generates practice quiz questions with difficulty levels, and produces flashcards for efficient memorization. This transforms passive reading into active learning.

The system supports multiple universities (currently USTHB and Batna 2) and handles both French and English content, making it practical for real-world academic environments.

How I built it

The architecture consists of several integrated components:

Backend Framework: I chose FastAPI for its automatic API documentation, type validation with Pydantic, and async capabilities. The application follows a clean architecture pattern with separate layers for routing, business logic, and external services.

AI Integration: The system uses Groq's API for primary inference, leveraging their GPT-OSS-120B model for fast, high-quality responses. I also integrated LangChain and LangGraph for orchestrating complex multi-step workflows. The agent architecture allows specialized behavior - one agent handles administrative questions while another manages academic content.

Document Processing Pipeline: PDF handling uses PyPDF2 for robust text extraction across multiple pages. The extracted content undergoes preprocessing (cleaning whitespace, removing artifacts) before being sent to the AI model with carefully engineered prompts. Each prompt is optimized for its specific task - summarization prompts emphasize key concepts, quiz prompts specify answer format and difficulty, flashcard prompts focus on term-definition pairs.

Fine-tuning Research: I experimented with fine-tuning LLaMA 3 8B using Unsloth and LoRA adapters. The process involved:

Creating a custom dataset of 8 French-language examples covering common administrative scenarios
Using 4-bit quantization to reduce memory requirements
Training with rank-16 LoRA adapters on specific bureau procedures
Achieving convergence in under 10 minutes on GPU

The mathematical formulation for LoRA updates follows:

$$h = W_0 x + \Delta W x = W_0 x + BA x$$

where $W_0$ is the frozen pretrained weight matrix, and $B \in \mathbb{R}^{d \times r}$, $A \in \mathbb{R}^{r \times k}$ are trainable low-rank matrices with $r \ll \min(d,k)$.

Deployment: The application is containerized with Docker,

Challenges I ran into

LLM Selection and Cost: Initially, I relied entirely on Groq's API, but encountered rate limits during testing. The solution required implementing a hybrid approach - Groq for production inference and Ollama with local models for development. Balancing response quality with inference speed was crucial, especially for the PDF analysis endpoint which processes large documents.

Prompt Engineering Complexity: Getting consistent, structured responses from LLMs proved challenging. Early iterations produced verbose answers or inconsistent formatting. I solved this through systematic prompt refinement:

Adding explicit output format instructions
Providing few-shot examples in prompts
Iterative testing with edge cases
Temperature tuning (0.3 for factual content, 0.7 for creative tasks)

PDF Processing Reliability: Not all PDFs are created equal. I encountered issues with:

Scanned documents without embedded text (would require OCR)
Password-protected files
Corrupted or malformed PDFs
Non-standard encodings

The solution involved comprehensive error handling, file validation before processing, clear error messages to users, and graceful degradation when features aren't available.

French Language Nuances: Administrative terminology in Algerian universities has specific French conventions. The model occasionally produced grammatically correct but contextually inappropriate responses. Fine-tuning on domain-specific examples significantly improved accuracy, though the small dataset size limited performance gains.

Context Window Limitations: Processing 50+ page PDFs approached the 2048-token context limit. I implemented chunking strategies for long documents.

Accomplishments that I'm proud of

Real-World Applicability: This isn't a toy demo - it addresses genuine pain points faced daily by thousands of students. The administrative assistant knows actual bureau locations and procedures from real universities.

Production-Ready Architecture: The codebase follows professional software engineering practices:

Comprehensive error handling with proper HTTP status codes
Structured logging for debugging and monitoring
Type hints throughout for maintainability
Docker deployment for consistency across environments
Automated testing framework (unit and integration tests)
Clear documentation (README, API docs, architecture guide)

AI Engineering Depth: Beyond simply calling API endpoints, the project demonstrates:

Multi-agent orchestration with LangGraph
Custom fine-tuning pipeline with LoRA
Prompt engineering for consistent outputs
Performance optimization (quantization, inference modes)
Hybrid cloud/local LLM deployment

Extensible Design: The agent architecture makes adding new capabilities straightforward. Supporting additional universities requires only updating the knowledge base, not restructuring code. New document processing features (like image analysis or citation extraction) can be added as new agents.

What I learned

LLM Prompt Engineering is a Craft: Effective prompts require iteration, testing, and domain knowledge. Small wording changes significantly impact output quality. System messages defining agent roles proved crucial for consistent behavior.

Fine-Tuning Requires Scale: My 8-example dataset showed promise but wasn't sufficient for production. The mathematical efficiency of LoRA is elegant:

$$\text{Parameters to train} = 2 \times r \times (d + k) \ll d \times k$$

But data quality matters more than algorithmic sophistication. Future work needs 100+ examples with proper validation splits.

User Experience Drives Architecture: Initially, I separated summarization, quiz, and flashcard generation into separate endpoints. User feedback (simulated through thinking about student workflows) revealed they want all study materials at once. The unified /analyze/pdf endpoint emerged from understanding user journeys, not technical constraints.

Docker Simplifies Deployment: What started as a complex setup process (install Python, set up virtual environment, download models, configure ports) became a single docker-compose up command. This reduces friction for demonstrating to juries and deploying to production.

Documentation is Development: Writing comprehensive API documentation forced me to think about edge cases, error messages, and response formats I hadn't considered during initial development. The README evolution from technical instructions to narrative storytelling made the project accessible to non-technical stakeholders.

What's next for Compusly AI

Immediate Enhancements:

Expand administrative knowledge base to 20+ Algerian universities
Implement conversation memory for multi-turn dialogues
Add Arabic language support (critical for broader accessibility)
Integrate OCR for scanned document processing
Create mobile-first frontend (React Native or Flutter)
Study Plan Generation: Analyze student schedules, course syllabi, and exam dates to create personalized revision plans. Optimize study time allocation using constraint satisfaction:

$$\text{maximize} \sum_{i=1}^{n} w_i \cdot \text{coverage}i \quad \text{subject to} \sum{i=1}^{n} t_i \leq T$$

where $w_i$ is course importance, $\text{coverage}_i$ is material reviewed, $t_i$ is time allocated, and $T$ is total available time.

Collaborative Learning: Enable students to share AI-generated study materials, creating a crowdsourced knowledge base. Implement voting mechanisms for quality control.
Analytics Dashboard: Track which administrative questions are most common, identify confusing procedures, and provide insights to university administrations for process improvement.

Research Directions:

Experiment with mixture-of-experts models for multi-domain expertise
Investigate reinforcement learning from human feedback (RLHF) using student ratings
Explore multilingual embeddings for seamless French-Arabic translation
Develop confidence scoring to flag uncertain responses for human review

Scaling Strategy:

Implement Redis caching for frequently asked questions
Add rate limiting and API key authentication
Set up monitoring with Prometheus and Grafana
Create distributed task queue with Celery for async processing
Deploy on cloud infrastructure (AWS/GCP) with auto-scaling

The ultimate vision is a comprehensive digital companion that accompanies students throughout their academic journey - from admission procedures through graduation requirements, from first lecture notes to thesis preparation. Compusly AI aims to be the intelligent layer between students and institutional complexity, making higher education more accessible and efficient across Algeria.

Built With

fastapi
langchain
nestjs
pydantic
pytorch
reactnative
uvicorn