InNoHassle Search

Check the project website.

Table of contents

Did you know that GitHub supports table of contents by default 🤔

About the Project

This API powers the search functionality within the InNoHassle ecosystem — a unified digital platform designed to simplify daily life for students of Innopolis University.

• Services code: GitHub - one-zero-eight
• Frontend: GitHub - website
• API endpoints: api.innohassle.ru
• InNoHassle website: innohassle.ru

The search service acts as a smart assistant, helping users quickly find information across various Innopolis University services.

Functionality

Supported features:

• search - search by keywords. Provides answers in the form of cards linking to resource websites with the ability to preview.
• ask - search by queries in free form. Provides answers generated by LLM with links to resource data.
• act - dialogue with action-based assistant. Provides the ability to perform actions in other Innopolis services on behalf of the user.

Resources used:

• Campus life - general knowledge about the university for quick adaptation
• Eduwiki - reference book on the educational process
• Hotel - information about dormitories
• Residents - list of resident companies in Innopolis
• InNoHassle - an ecosystem that collects the functionality of Innopolis services in one place or links to them
• My University - a system for performing administrative requests

Technologies

• Environment: Python 3.11, uv
• API: FastAPI, Pydantic
• Database: MongoDB, Beanie
• Dev Tools: Ruff, pre-commit
• Deployment: Docker, Docker Compose, GitHub Actions

Development

Run with Docker

1. Set up project settings file (check settings.schema.yaml for more info).

   cp settings.example.yaml settings.yaml

   Put your openrouter_api_key in settings.yaml.

2. Set up database settings for docker-compose container in .env file

   cp .env.example .env

3. Start all services:

   uv run python -m src.ml_service
   docker compose up

Now you can find API docs on http://localhost:8004/docs.

Run locally

1. Install Python 3.11

2. Install uv

3. Install project dependencies with uv:

   uv sync

4. Set up pre-commit hooks:

   uv run pre-commit install --install-hooks -t pre-commit -t commit-msg

5. Check that your settings.yaml looks like:

   $schema: "./settings.schema.yaml"
   api_settings:
     db_url: "mongodb://mongoadmin:secret@localhost:27017/localhost?authSource=admin"
   minio:
     access_key: "minioadmin"
     secret_key: "password"
   ml_service:
   # infinity_url: http://127.0.0.1:7997
     api_key: "secret_token"
     mongo_url: "mongodb://mongoadmin:secret@db:27017/localhost?authSource=admin"
     openrouter_api_key: "your openrouter api key"
     timeout: 180.0

6. Set up a MongoDB and Minio instances.

   • Set up database settings for docker-compose container in .env file

     cp .env.example .env

   • Run the database instance:

     docker compose up -d db minio

   • Make sure to set up the actual database connection in settings.yaml.

7. Choose the way to run models: either use Infinity or local models.

   1. If you want to use local models, just not set infinity_url in settings.yaml
   2. If you want to use Infinity, set infinity_url in settings.yaml to the url of deployed Infinity engine. You can run Infinity engine locally:

      uv run --no-project --with "infinity_emb[all]" --with "transformers<4.49" infinity_emb v2 --model-id intfloat/multilingual-e5-large-instruct --model-id BAAI/bge-reranker-v2-m3

      Or use deployed Infinity engine provided by someone else.

8. Run ml client

   uv run python -m src.ml_service

9. Run the ASGI server

   uv run python -m src.api

   Check API docs on http://127.0.0.1:8001/docs.

PyCharm integrations

• Ruff – plugin: linting and formatting Enable Use ruff format in plugin settings.
• Pydantic – plugin: type hinting support
• Conventional commits – plugin: following conventional commits

Authentication

We use our own IAM service for authentication - InNoHassle Accounts. To authenticate the user, you need to pass the Authorization header with the Bearer: <jwt_token>. How to get token:

1. First of all, go to innohassle.ru and log in if you are not logged in (or register). That will add cookie with account secret needed for the next step.
2. Go to Accounts API and execute the the method GET /tokens/generate-my-token, copy the token from the response.
3. Go to the Swagger of API you want to authenticate and click on the Authorize button in the top right corner, paste the token in the Value field and click Authorize. Now you can use protected endpoints from the Swagger.

Testing

For testing we use pytest.

• To run tests enter in your terminal:

  uv run pytest tests
  

• To generate test coverage report run:

  uv run pytest  --cov-config=.coveragerc --cov=src/ tests/
  

  You can change coverage ignored folders/files in .coveragerc.
• To run evaluation script:

  uv run --script scripts/search_result_metrics.py
  

Deployment

We use Docker with Docker Compose plugin to run the website on servers.

1. Copy the file with environment variables: cp .env.example .env
2. Change environment variables in the .env file
3. Copy the file with settings: cp settings.example.yaml settings.yaml
4. Change settings in the settings.yaml file according to your needs (check settings.schema.yaml for more info)
5. Install Docker with Docker Compose
6. Build a Docker image: docker compose build --pull
7. Run the container: docker compose up --detach
8. Check the logs: docker compose logs -f

Contributing

We are open to contributions of any kind. You can help us with code, bugs, design, documentation, media, new ideas, etc. If you are interested in contributing, please read our contribution guide.