AIRA – AI Research Assistant

An interactive AI-powered research assistant that helps you explore topics, extract key ideas, and generate learning material from publicly available Wikipedia articles.

AIRA provides a FastAPI backend for scraping and processing text and a modern React/Vite frontend for an intuitive, single-page experience.

Features

Topic research from Wikipedia
Enter any topic and AIRA scrapes the corresponding Wikipedia page, cleans the text, and returns a readable preview.
Teaching mode (auto-explanations)
Extracts the most relevant sentences for a topic and returns them as an explanation and key bullet points, acting as a lightweight teaching aid.
Semantic search over an article
Ask a natural language question about a topic and AIRA finds the most relevant sentences from the article using TF‑IDF and cosine similarity.
TF‑IDF feature exploration (optional)
Computes TF‑IDF features from the cleaned article text so you can inspect key terms and feature counts.
Word2Vec similar-word lookup (optional/experimental)
Trains a small Word2Vec model over the article text and returns words most similar to a given query word.
Modern, responsive UI
React/Vite SPA using framer-motion and lucide-react icons with a clean, card-based layout.

Architecture Overview

The project is split into a Python backend and a JavaScript frontend.

Backend – FastAPI

Location: app/

app/main.py
- Creates the FastAPI app titled "AI Research Assistant".
- Includes API routes from app.api.routes.
- Configures permissive CORS (for local frontend development).
app/api/routes.py
- Defines the main REST endpoints:
  - /research – scrape and preview Wikipedia content.
  - /tfidf – preprocess and compute TF‑IDF features.
  - /word2vec – train Word2Vec and get similar words.
  - /search – semantic search over article sentences.
  - /teach – generate teaching content from semantic search results.
app/services/scraper.py
- Uses requests and BeautifulSoup to download and parse Wikipedia pages.
- Extracts and concatenates all non-empty paragraph text into a single string.
app/services/preprocessing.py
- Uses NLTK for standard NLP preprocessing:
  - Cleans text (removes references like [1], special characters, lowercasing).
  - Tokenizes text using word_tokenize.
  - Sentence splitting via nltk.sent_tokenize.
  - Removes stopwords.
  - Lemmatizes tokens using WordNetLemmatizer.
- Exposes a preprocess_pipeline(text) helper returning cleaned tokens.
app/services/embeddings.py
- Uses sklearn.feature_extraction.text.TfidfVectorizer to compute a TF‑IDF representation of the document.
- Returns the learned feature names and matrix shape for inspection.
app/services/semantic_search.py
- Splits the scraped article text into sentences.
- Filters out very short/empty sentences.
- Builds a TF‑IDF matrix over sentences and computes cosine similarity to the user query.
- Returns the top-k most relevant sentences with their similarity scores.
app/services/teaching_generator.py
- Reuses semantic_search to pick the most relevant sentences for the topic itself.
- Joins these into an explanation and also provides the individual key sentences as key points.
app/services/word2vec_model.py
- Trains a simple Word2Vec model (from gensim) on preprocessed sentences.
- Exposes a get_similar_words helper to query nearest neighbors in the embedding space.

Additional folders such as app/core/ and app/models/ are present for future configuration and model-loading utilities.

Frontend – React + Vite

Location: client/

client/src/App.jsx
- Main single-page application.
- Manages UI state: selected topic, query, loading state, and result data.
- Calls the API service helpers based on the user action:
  - Research
  - Teach
  - Semantic search
- Renders results via the ResultCard component.
client/src/components/SearchBar.jsx
- Styled search bar for entering the topic.
- Supports focus styling and icon display using lucide-react.
client/src/components/ResultCard.jsx
- Card component for displaying results.
- Chooses icon and accent color depending on result type (research, teach, search).
- Renders content as Markdown using react-markdown.
client/src/services/api.js
- Centralized API client for the frontend.
- Exposes helpers:
  - fetchResearch(topic) → GET /research.
  - fetchTeach(topic) → GET /teach.
  - fetchSearch(topic, query) → GET /search.
  - fetchTFIDF(topic) → GET /tfidf (optional).
  - fetchWord2Vec(topic, word) → GET /word2vec (optional).
- Handles basic error reporting when the backend is not reachable.

Getting Started

Prerequisites

Python 3.10+ (recommended)
Node.js 18+ and npm

You will also need NLTK data packages for tokenization, stopwords, and lemmatization (see below).

Backend (FastAPI)

Create and activate a virtual environment (optional but recommended):

cd aira
python -m venv .venv
.venv\Scripts\activate  # on Windows

Install Python dependencies:
```
pip install -r requirements.txt
```

Download required NLTK data (run once in Python):

import nltk
nltk.download("punkt")
nltk.download("stopwords")
nltk.download("wordnet")

Run the FastAPI server with Uvicorn:

From the project root (where app/ lives):
```
uvicorn app.main:app --reload
```
The backend will be available at: http://127.0.0.1:8000.

Frontend (React + Vite)

Install Node dependencies:
```
cd client
npm install
```
Run the development server:
```
npm run dev
```
By default Vite will start on http://127.0.0.1:5173 (or similar). The frontend is configured to call the backend at http://127.0.0.1:8000.

Configuration & Environment

By default, the backend uses in-code defaults and does not require any environment variables for local development.
If you later add features like external APIs, caching, or logging, prefer wiring configuration through app/core/config.py and a .env file loaded at startup.
Keep secrets (API keys, tokens) out of version control by storing them in your local environment or an untracked .env file.

API Reference

All endpoints are prefixed from the FastAPI root (no additional API prefix).

`GET /research`

Fetch a cleaned preview of the Wikipedia article for a topic.

Query parameters

topic (string, required) – The topic to look up on Wikipedia.

Response (example shape)

{
  "topic": "machine learning",
  "preview": "Machine learning (ML) is a field of inquiry devoted to..."
## Project Structure

```text
.
├── app/
│   ├── main.py                 # FastAPI application entrypoint
│   ├── api/
│   │   └── routes.py           # API route definitions
│   ├── core/
│   │   └── config.py           # Configuration and settings (extensible)
│   ├── models/
│   │   └── model_loader.py     # Model loading utilities (placeholder)
│   ├── services/
│   │   ├── embeddings.py       # TF‑IDF vectorization helpers
│   │   ├── keyword_extractor.py# Keyword extraction logic
│   │   ├── preprocessing.py    # Text cleaning and NLP preprocessing
│   │   ├── qa_system.py        # Question‑answering / semantic search orchestration
│   │   ├── scraper.py          # Wikipedia scraping
│   │   ├── semantic_search.py  # Sentence‑level semantic search
│   │   ├── summarizer.py       # Summarization utilities
│   │   ├── teaching_generator.py# Teaching‑mode content generation
│   │   └── word2vec_model.py   # Word2Vec training and querying
│   └── utils/
│       └── text_cleaner.py     # Lower‑level text cleanup helpers
│
├── client/                     # React + Vite frontend
│   ├── public/
│   └── src/
│       ├── App.jsx             # Root SPA component
│       ├── main.jsx            # React/Vite bootstrap
│       ├── components/
│       │   ├── ResultCard.jsx  # Generic result display card
│       │   └── SearchBar.jsx   # Topic/search input bar
│       ├── lib/
│       │   └── utils.js        # Frontend utility helpers
│       ├── pages/
│       │   └── Home.jsx        # Main page layout
│       └── services/
│           └── api.js          # HTTP client for backend APIs
│
├── notebooks/                  # Experimentation / exploratory notebooks
├── tests/                      # (Planned) automated tests
├── requirements.txt            # Python dependencies
├── package.json                # Frontend dependencies/scripts (under client/)
└── README.md                   # Project documentation

}


### `GET /teach`

Generate a teaching-style explanation from the article by selecting the most relevant sentences.

**Query parameters**

- `topic` (string, required)

**Response (example shape)**

```json
{
  "topic": "neural network",
  "explanation": "Neural networks are a subset of machine learning...",
  "key_points": [
    "Neural networks are inspired by biological neurons...",
    "They consist of layers of interconnected nodes..."
  ]
}

`GET /search`

Perform semantic search over the sentences in the Wikipedia article.

Query parameters

topic (string, required) – Article to search in.
query (string, required) – Natural language question / query.

Response (example shape)

{
  "query": "applications of reinforcement learning",
  "results": [
    ["Reinforcement learning has been used in robotics...", 0.71],
    ["In games such as Go and Atari, reinforcement learning...", 0.65]
  ]
}

`GET /tfidf` (optional)

Compute TF‑IDF features over the cleaned article tokens.

Query parameters

topic (string, required)

Response (example shape)

{
  "topic": "data science",
  "num_features": 420,
  "sample_features": ["analysis", "statistics", "data", "model", "prediction"]
}

`GET /word2vec` (optional / experimental)

Train a small Word2Vec model on the article and fetch words most similar to a given query word.

Query parameters

topic (string, required)
query_word (string, required)

Response (example shape)

{
  "query": "algorithm",
  "similar_words": [
    ["algorithms", 0.89],
    ["procedure", 0.76]
  ]
}

How It Works

Scraping
When you enter a topic, the backend constructs a Wikipedia URL and downloads the page HTML with a basic user agent header.
Parsing
BeautifulSoup is used to parse the HTML and extract paragraph (<p>) text, which is concatenated into one long document.
Preprocessing
The text is cleaned (references removed, punctuation stripped, lowercased), tokenized, stopwords removed, and lemmatized via NLTK utilities.
Vectorization and similarity \
- For TF‑IDF and semantic search, TfidfVectorizer builds a sparse representation of sentences.
- Cosine similarity is used to rank sentences given a user query.
Teaching content
The teaching endpoint runs semantic search with the topic itself as the query and stitches the top sentences into an explanation plus key points.
Frontend rendering
The React app sends requests to the API and displays responses as Markdown in a responsive card layout with simple animations.

Development Notes

This project uses live Wikipedia content, so responses depend on network connectivity and Wikipedia availability.
Some endpoints (especially Word2Vec) may be slower on very long articles or constrained hardware.
NLTK requires external data downloads; make sure the required corpora are available in your environment.

Running Tests

Place tests under the tests/ directory using your preferred structure (for example, tests/test_*.py).
From the project root, run:
```
pytest
```
(Make sure pytest is installed in your virtual environment.)

Troubleshooting

NLTK LookupError (e.g., Resource punkt not found)
Ensure you have run the NLTK download snippet from the Getting Started section:
```
import nltk
nltk.download("punkt")
nltk.download("stopwords")
nltk.download("wordnet")
```
Backend not reachable from frontend
Verify that Uvicorn is running on http://127.0.0.1:8000 and that the Vite dev server is using the same base URL for API calls (see client/src/services/api.js).

Future Improvements

Add caching for scraped articles to avoid repeated HTTP requests.
Add more robust error handling and user feedback in the UI.
Support multiple knowledge sources beyond Wikipedia.
Add configuration via environment variables (e.g., rate limits, logging, cache backend).
Add richer teaching modes (summaries by level, quizzes, flashcards, etc.).

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

AIRA – AI Research Assistant

Table of Contents

Features

Architecture Overview

Backend – FastAPI

Frontend – React + Vite

Getting Started

Prerequisites

Backend (FastAPI)

Frontend (React + Vite)

Configuration & Environment

API Reference

`GET /research`

`GET /search`

`GET /tfidf` (optional)

`GET /word2vec` (optional / experimental)

How It Works

Development Notes

Running Tests

Troubleshooting

Future Improvements

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
app		app
client		client
.gitignore		.gitignore
README.md		README.md
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

AIRA – AI Research Assistant

Table of Contents

Features

Architecture Overview

Backend – FastAPI

Frontend – React + Vite

Getting Started

Prerequisites

Backend (FastAPI)

Frontend (React + Vite)

Configuration & Environment

API Reference

GET /research

GET /search

GET /tfidf (optional)

GET /word2vec (optional / experimental)

How It Works

Development Notes

Running Tests

Troubleshooting

Future Improvements

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`GET /research`

`GET /search`

`GET /tfidf` (optional)

`GET /word2vec` (optional / experimental)

Packages