Skip to content

Commit 8e2cd75

Browse files
MoSchmidtMoSchmidt
authored
Project Quick Start Up + Test Data Script (#54)
* add AI acknowledgment to README.md * add test data ingestion script * add full docker application start script
1 parent ec4d8da commit 8e2cd75

12 files changed

Lines changed: 643 additions & 80 deletions

File tree

‎.env.example‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Inquiro Docker Configuration
2+
# Copy this file to .env and fill in your values
3+
# Usage: cp .env.example .env
4+
5+
# Required: OpenAI API Key for AI-powered features (semantic ranking, summaries)
6+
OPENAI_API_KEY=your-openai-api-key-here
7+
8+
# Optional: Override default security keys (defaults are provided for development)
9+
# JWT_SECRET_KEY=your-64-char-hex-string
10+
# SAFETY_CANARY=your-base64-encoded-string

‎README.md‎

Lines changed: 115 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,139 +1,181 @@
1-
# Inquiro
1+
<p align="center">
2+
<picture>
3+
<source media="(prefers-color-scheme: dark)" srcset="frontend/src/assets/images/inquiro_logo_dark_mode.svg">
4+
<source media="(prefers-color-scheme: light)" srcset="frontend/src/assets/images/inquiro_logo.svg">
5+
<img alt="Inquiro" src="frontend/src/assets/images/inquiro_logo.svg" width="350">
6+
</picture>
7+
</p>
8+
9+
<p align="center">
10+
<em>AI-powered research discovery platform that matches your research interests with relevant scientific papers using intelligent semantic ranking.</em>
11+
</p>
212

3-
*Inquiro* is an AI-powered research discovery platform designed to match user research interests with relevant scientific papers using intelligent semantic ranking.
13+
---
14+
15+
## 📋 Prerequisites
16+
17+
| Tool | Required For | Installation |
18+
| --- | --- | --- |
19+
| **Docker** | All setups | [docker.com](https://www.docker.com/products/docker-desktop/) |
20+
| **Python** | 3.11.14 — Development setup only | [python.org](https://www.python.org/downloads/release/python-31114/) |
21+
| **Node.js** | 22.12.0+ — Development setup only | [nodejs.org](https://nodejs.org/) |
22+
23+
You also need an **OpenAI API key** for semantic ranking and paper analysis features.
24+
Get one at [platform.openai.com](https://platform.openai.com/).
425

526
---
627

7-
## ⚙️ Development Setup
28+
## 🚀 Quick Start (Docker)
29+
30+
Run the entire stack — database, backend, frontend, and test data seeding — in Docker with a few commands.
31+
32+
1. **Create your environment file:**
33+
34+
```bash
35+
cp .env.example .env
36+
```
37+
38+
2. **Add your OpenAI API key** by editing the `.env` file:
39+
40+
```
41+
OPENAI_API_KEY=sk-your-key-here
42+
```
43+
44+
3. **Start all services:**
45+
46+
```bash
47+
docker compose --profile full up -d
48+
```
849

9-
### 🧩 Prerequisites
50+
This will automatically:
51+
- Start the PostgreSQL database (with pgvector)
52+
- Launch the backend, which creates the database schema on startup
53+
- Seed the database with test papers and a test user (`test` / `My Test Project`)
54+
- Serve the frontend via nginx
1055

11-
Make sure the following tools are installed on your system:
56+
Once running, open [http://localhost](http://localhost) in your browser.
1257

13-
| Tool | Recommended Version | Installation Link |
14-
| ----------------------- |---------------------|-----------------------------------------------------------------------------------------------------|
15-
| **Docker** | Latest | [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/) |
16-
| **Python** | 3.11.14 | [python.org/downloads/release/python-31114](https://www.python.org/downloads/release/python-31114/) |
17-
| **Node.js** | 22.12.0+ | [nodejs.org](https://nodejs.org/) |
58+
| Service | URL |
59+
| --- | --- |
60+
| Frontend | [http://localhost](http://localhost) |
61+
| Backend API | [http://localhost:8000](http://localhost:8000) |
62+
| API Docs | [http://localhost:8000/docs](http://localhost:8000/docs) |
1863

19-
💡 **Note:** Docker is only required to run the PostgreSQL database locally.
20-
The backend and frontend are started manually.
64+
> To stop all services: `docker compose --profile full down`
2165
2266
---
2367

24-
## 🖥️ Frontend Setup
68+
## 🛠️ Development Setup
2569

26-
1. **Navigate to the frontend directory**:
70+
For active development, run only the database in Docker and start the frontend and backend manually. This gives you hot-reload and direct access to the code.
71+
72+
### 🖥️ Frontend
73+
74+
1. **Navigate to the frontend directory:**
2775

2876
```bash
2977
cd frontend
3078
```
31-
2. **Install dependencies**:
79+
80+
2. **Install dependencies:**
3281

3382
```bash
3483
npm install
3584
```
36-
3. **Start the development server**:
85+
86+
3. **Start the development server:**
3787

3888
```bash
3989
npm run dev
4090
```
4191

4292
The frontend will be available at [http://localhost:5173](http://localhost:5173) (or the port shown in the console).
4393

44-
---
94+
### ⚙️ Backend
4595

46-
## ⚙️ Backend Setup
47-
48-
1. **From the project root, start the database**:
96+
1. **From the project root, start the database:**
4997

5098
```bash
5199
docker compose up -d
52100
```
53-
2. **Navigate to the backend directory**:
101+
102+
2. **Navigate to the backend directory:**
54103

55104
```bash
56105
cd backend
57106
```
58107

59-
---
60-
61-
## (Optional but recommended) Create and activate a Python environment
62-
63-
You can choose **either** a standard `venv` (recommended if you already installed Python 3.11.14 manually) **or** an Anaconda environment.
64-
65-
### ✅ Option A — Create a virtual environment using `venv` (Python 3.11.14)
108+
3. **Set up a Python environment** *(optional but recommended)*
66109

67-
Ensure Python **3.11.14** is available on your system (check with `python --version` or `python3 --version`).
110+
Choose **either** a standard `venv` **or** an Anaconda environment.
68111

69-
🧠 **Linux / macOS**
112+
<details>
113+
<summary><strong>Option A — venv (Python 3.11.14)</strong></summary>
70114

71-
```bash
72-
# Create a virtual environment using the correct Python version
73-
python3.11 -m venv inquiro-env
115+
Ensure Python **3.11.14** is available on your system (`python --version` or `python3 --version`).
74116

75-
# Activate it
76-
source inquiro-env/bin/activate
77-
```
117+
**Linux / macOS:**
78118

79-
🪟 **Windows (PowerShell)**
80-
81-
```bash
82-
# Create a virtual environment
83-
py -3.11 -m venv inquiro-env
119+
```bash
120+
python3.11 -m venv inquiro-env
121+
source inquiro-env/bin/activate
122+
```
84123

85-
# Activate it
86-
inquiro-env\Scripts\activate
87-
```
124+
**Windows (PowerShell):**
88125

126+
```bash
127+
py -3.11 -m venv inquiro-env
128+
inquiro-env\Scripts\activate
129+
```
89130

90-
### ✅ Option B — Create an environment using Anaconda (Python 3.11.14)
131+
</details>
91132

92-
If you're using Conda, you can create a dedicated environment:
133+
<details>
134+
<summary><strong>Option B — Anaconda</strong></summary>
93135

94-
```bash
95-
conda create -n inquiro-env python=3.11.14
96-
conda activate inquiro-env
97-
```
136+
```bash
137+
conda create -n inquiro-env python=3.11.14
138+
conda activate inquiro-env
139+
```
98140

99-
This ensures all dependencies install cleanly—especially libraries like `torch`, `transformers`, and scientific packages.
141+
This ensures all dependencies install cleanly — especially libraries like `torch`, `transformers`, and scientific packages.
100142

101-
---
143+
</details>
102144

103-
3. **Install dependencies**:
145+
4. **Install dependencies:**
104146

105147
```bash
106148
pip install -r requirements.txt
107149
pip install -r requirements-dev.txt
108150
```
109-
110-
4. **Create a local environment file**:
111151

112-
Copy the example file and rename it to dev.env:
152+
5. **Create a local environment file:**
153+
154+
Copy the example file and rename it to `dev.env`:
155+
156+
**Linux / macOS:**
113157

114-
🧠 Linux / macOS
115-
116-
```bash
158+
```bash
117159
cp .env.example dev.env
118160
```
119-
120-
🪟 Windows (PowerShell)
161+
162+
**Windows (PowerShell):**
121163

122164
```bash
123165
copy .env.example dev.env
124166
```
125-
126-
Then adjust the values if needed (e.g., database port, credentials).
127167

128-
5. **Install Git hooks**:
168+
Then open `dev.env` and add your **OpenAI API key**. Adjust other values if needed (e.g., database port, credentials).
169+
170+
6. **Install Git hooks:**
129171

130172
```bash
131173
pre-commit install
132174
```
133175

134-
After this, the formatters and linters will run automatically every time you commit.
176+
After this, formatters and linters will run automatically on every commit.
135177

136-
6. **Start the FastAPI server**:
178+
7. **Start the FastAPI server:**
137179

138180
```bash
139181
uvicorn app.main:app --reload
@@ -146,20 +188,16 @@ This ensures all dependencies install cleanly—especially libraries like `torch
146188

147189
## 🧪 API Testing with Bruno
148190

149-
The *Inquiro* project includes a [**Bruno**](https://www.usebruno.com) collection under `/bruno` for testing and exploring the backend API.
150-
Bruno is a lightweight, file-based API client that stores requests in plain text, making it well-suited for collaborative development and version control.
191+
The project includes a [**Bruno**](https://www.usebruno.com) collection under `/bruno` for testing and exploring the backend API. Bruno is a lightweight, file-based API client that stores requests in plain text, making it well-suited for collaborative development and version control.
151192

152-
### ⚙️ Setup
193+
1. **Install Bruno** — Download from [usebruno.com/downloads](https://www.usebruno.com/downloads).
153194

154-
1. **Install Bruno**
195+
2. **Open the collection** — Launch Bruno, click **"Open Collection"**, and select the `/bruno/Inquiro Bruno` folder from the project root.
155196

156-
Download and install Bruno from [usebruno.com/downloads](https://www.usebruno.com/downloads).
197+
3. **Select an environment** — The `/bruno/Inquiro Bruno/environments` directory contains predefined environment files. For local development, select the **_Development_** environment.
157198

158-
2. **Open the collection**
159-
160-
* Launch Bruno.
161-
* Click **“Open Collection”** and select the `/bruno/Inquiro Bruno` folder from the project root.
199+
---
162200

163-
3. **Select or configure an environment**
201+
## 🤖 AI Acknowledgement
164202

165-
The `/bruno/Inquiro Bruno/environments` directory contains predefined environment files. For local development select the **_Development_** environment.
203+
AI-assisted tools, including ChatGPT, Claude (Code), and Cursor, were used during the development of this project for architectural planning, code generation, and debugging support. All AI-generated output was reviewed and adapted by the development team.

‎backend/.dockerignore‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Virtual environments
2+
.venv/
3+
venv/
4+
inquiro-env/
5+
env/
6+
7+
# Python cache
8+
__pycache__/
9+
*.pyc
10+
*.pyo
11+
*.pyd
12+
.Python
13+
14+
# Git
15+
.git/
16+
.gitignore
17+
18+
# Environment files
19+
.env*
20+
dev.env
21+
22+
# Documentation
23+
*.md
24+
25+
# IDE
26+
.idea/
27+
.vscode/
28+
29+
# Data directories
30+
ingestion/data/
31+
evaluation_data/
32+
evaluation_results/
33+
34+
# Testing
35+
.pytest_cache/
36+
.coverage
37+
htmlcov/

‎backend/Dockerfile‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Stage 1: Builder
2+
FROM python:3.11-slim AS builder
3+
4+
WORKDIR /app
5+
6+
# Install build dependencies
7+
RUN apt-get update && apt-get install -y --no-install-recommends \
8+
build-essential \
9+
git \
10+
&& rm -rf /var/lib/apt/lists/*
11+
12+
# Copy requirements first for layer caching
13+
COPY requirements.txt .
14+
15+
# Install Python dependencies
16+
RUN pip install --no-cache-dir --user -r requirements.txt
17+
18+
# Stage 2: Runtime
19+
FROM python:3.11-slim AS runtime
20+
21+
WORKDIR /app
22+
23+
# Install runtime dependencies
24+
RUN apt-get update && apt-get install -y --no-install-recommends \
25+
libpq5 \
26+
&& rm -rf /var/lib/apt/lists/*
27+
28+
# Copy installed packages from builder
29+
COPY --from=builder /root/.local /root/.local
30+
ENV PATH=/root/.local/bin:$PATH
31+
32+
# Copy application code
33+
COPY . .
34+
35+
# Expose port
36+
EXPOSE 8000
37+
38+
# Health check - use curl since httpx may not be CLI-accessible
39+
HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
40+
CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/docs')" || exit 1
41+
42+
# Run uvicorn
43+
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

‎backend/app/main.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,7 @@ async def lifespan(_app: FastAPI) -> AsyncGenerator[None, Any]:
4040
"""Initialize and tear down application resources."""
4141

4242
logger.info("🚀 Starting Inquiro API in '%s' mode...", settings.ENVIRONMENT)
43-
if settings.ENVIRONMENT == "dev":
44-
await init_db() # Auto-create tables only in dev
43+
await init_db()
4544

4645
# Start PDF conversion workers
4746
queue = ConversionQueue.get_instance()
@@ -86,6 +85,8 @@ async def lifespan(_app: FastAPI) -> AsyncGenerator[None, Any]:
8685
allow_origins=[
8786
"http://localhost:5173",
8887
"http://127.0.0.1:5173",
88+
"http://localhost",
89+
"http://127.0.0.1",
8990
],
9091
allow_credentials=True,
9192
allow_methods=["*"],

0 commit comments

Comments
 (0)