README.md

---
title: ResearchOS
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
---

# ResearchOS on Hugging Face Spaces

AI-Powered Research Operating System MVP deployed on Hugging Face Spaces.

## What's Included

- **Frontend**: Next.js 14 app with project dashboard, manuscript editor, literature search, analysis upload, and peer review
- **API Gateway**: FastAPI router with JWT authentication
- **Auth Service**: User registration/login with bcrypt + JWT
- **Project Service**: Project CRUD with PostgreSQL/SQLite
- **Manuscript Service**: Document storage with versioning
- **Analysis Service**: Statistical engine with schema detection and APA output
- **Agent Service**: Literature search, writing generation, peer review simulation
- **Verification Service**: Cryptographic receipts + 3-probe verification
- **Collaboration Service**: WebSocket + Yjs real-time editing

## Environment Variables

Set these in your Space Settings:

| Variable | Required | Description |
|----------|----------|-------------|
| `JWT_SECRET` | Yes | Secret key for JWT tokens |
| `OPENAI_API_KEY` | No | For AI generation (falls back to HF API) |
| `HUGGINGFACE_API_TOKEN` | No | For HF Inference API fallback |

## Architecture on HF Spaces

Since HF Spaces is ephemeral:
- Uses **SQLite** instead of PostgreSQL (data resets on restart)
- File uploads stored in container (ephemeral)
- All services run in single container (simplified for MVP)

## Usage

1. Open the Space URL
2. Register a new account
3. Create a research project
4. Use Literature tab to search papers
5. Upload data in Analysis tab
6. Write manuscript in Writing tab
7. Run peer review simulation

## Limitations

- No persistent database (use external DB for production)
- Docker sandbox limited (analysis runs in-process)
- WebSockets may need polling fallback behind HF proxy
- File storage is ephemeral

## GitHub

Full source: [your-repo/researchos](https://github.com/your-repo/researchos)