An automated academic job sourcing, metadata refinement, and AI candidate matching engine. Connects researchers, postdocs, and PhD candidates with top global academic vacancies through real-time scraping, multilingual translation, vector similarity, and Telegram notifications.
Finding the right academic position (PhD, Postdoc, or Faculty) across universities and research institutions worldwide is often fragmented across multiple national portals and languages. Academix automates the entire discovery, extraction, and matching workflow:
- Multi-Portal Discovery & Sourcing: Continuously crawls 6 major academic job boards worldwide (EURAXESS, AcademicTransfer, ABG, NatureCareers, ResearchGate, and EuroScienceJobs).
- Multilingual NLP & Translation: Paragraph-aware language detection (Lingua & OpenLID) and NLLB-200 translation for non-English academic vacancy listings.
- Structured CV Parsing: Asynchronously extracts degrees, institutions, specialized technical skills, and research domains from uploaded candidate CVs (PDF).
- Hybrid Multi-Factor Matching: Evaluates candidates using Nomic Embed v1.5 vector similarity, BM25 keyword matching, and prerequisite degree compatibility.
- Interactive Telegram Assistant (
@AcadamixBot): Full candidate interface for CV uploading, progress tracking, single-card carousel job browsing, and instant match alerts. - Unified Modular Architecture: 20 decoupled microservices orchestrable via Docker Compose (CPU, GPU, or Postgres) or a single lightweight local runner.
- Python >= 3.12
- uv (recommended) or Docker & Docker Compose
- Local or remote OpenAI-compatible LLM service (e.g., Ollama)
Copy .env.example to .env:
cp .env.example .envConfigure your .env variables:
PORT=8000
API_SECRET_KEY=dev_secret_key
DATABASE_URL=sqlite:///data/academix.db
TELEGRAM_BOT_TOKEN=your_token_from_botfather
# LLM & Embedding Settings
LLM_SERVICE_URL=http://localhost:11434/v1
LLM_MODEL=hf.co/unsloth/gemma-4-E2B-it-GGUF:gemma-4-E2B-it-Q3_K_M.gguf
EMBEDDING_MODEL=nomic-ai/nomic-embed-text-v1.5
MATCH_THRESHOLD=0.75
DEGREE_SIMILARITY_THRESHOLD=0.71
ENABLE_MATCH_EXPLANATION=trueTelegram Bot Ready: Set
TELEGRAM_BOT_TOKENto enable real-time CV matching and instant vacancy alerts directly inside Telegram via@AcadamixBot.
uv sync --all-packagesRun database schema migrations:
uv run python -m core.infrastructure.db.run_migrations(Supports SQLite local file or PostgreSQL server)
uv run python run_all.pyThis starts the FastAPI gateway, Telegram bot, background NLP workers, and all crawler agents under a unified supervisor process.
- Default CPU Stack (Gateway + Workers + Crawlers):
docker compose up --build -d- GPU Mode (Hardware accelerated inference):
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up --build -d- Production Stack with PostgreSQL & NGINX:
docker compose -f docker-compose.yml -f docker-compose.postgres.yml -f docker-compose.prod.yml up --build -d/start- Starts the assistant or opens the personal dashboard./upload_cv- Step-by-step prompt to upload your academic CV (PDF)./status- Visual progress bar tracking CV extraction, translation, and matching./profile- View extracted skills, highest degree, and research domains./edit- Interactive button wizard to edit skills, research domains, or degree fields./matches- Single-card carousel to browse matched academic vacancies with direct links./delete- Reset and permanently delete your profile and CV document./help- Command guide and usage instructions.
- Start a conversation with
@AcadamixBotand tap Upload CV or send/upload_cv. - Attach and send your CV as a
.pdffile. - The AI pipeline parses your qualifications and calculates semantic compatibility against open European vacancies.
- When matches are computed, receive instant notifications with match percentage, job details, and direct links to apply.
POST /profiles/upload-cv
- Uploads a candidate's CV document (PDF format) and queues asynchronous parsing.
curl -X POST http://localhost:8000/profiles/upload-cv \
-F "file=@/path/to/cv.pdf" \
-F "name=Marie Curie" \
-F "telegram_chat_id=123456789"GET /profiles/{profile_id}/matches?limit=10
- Returns ranked academic positions meeting compatibility thresholds with optional LLM reasoning explanation.
GET /jobs/refined
- Returns structured academic vacancies enriched with prerequisite degree levels, fields, and deadlines.
GET /status or GET /health
- Checks service health and database connectivity.
- Lint with Ruff:
uv run ruff check .- Format code with Ruff:
uv run ruff format .- Run complete test suite:
uv run pytestIf you find Academix useful in your academic job search or research workflow, consider supporting its open-source development:
- Every coffee helps cover server hosting costs, multi-portal crawler infrastructure, and ongoing maintenance.
This project is licensed under the Business Source License 1.1 (BSL 1.1).
- Free for Personal & Educational Use: You are free to view, study, modify, and run Academix for personal, academic, research, and non-commercial purposes.
- Commercial Protection: Offering Academix as a commercial matching service or SaaS to third parties requires a commercial license.
- Conversion: Automatically converts to open-source GNU General Public License v3.0 (GPLv3) after the change date.
See the LICENSE file for complete legal terms.