Search

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.

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

• Python 3.11 & uv
• FastAPI
• Database and ORM: MongoDB & Beanie
• Formatting and linting: 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. Start all services:

   uv run -m src.ml_service
   docker compose up

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

Set up for development

1. Install uv and Docker
2. Install dependencies:

   uv sync

3. 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

4. Set up a MongoDB and Minio instances.
   • Run the database instance:

     docker compose up -d db minio

   • Make sure to set up the actual database connection in settings.yaml.
5. 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.
6. Run ml client

   uv run -m src.ml_service

7. Run the ASGI server

   uv run -m src.api

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

Set up PyCharm integrations

1. Run configurations (docs). Right-click the __main__.py file in the project explorer, select Run '__main__' from the context menu.
2. Ruff (plugin). It will lint and format your code. Make sure to enable Use ruff format option in plugin settings.
3. Pydantic (plugin). It will fix PyCharm issues with type-hinting.
4. Conventional commits (plugin). It will help you to write 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 service on servers.

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

FAQ

Be up to date with the template!

Check https://github.com/one-zero-eight/fastapi-template for updates once in a while.

How to update dependencies

1. Run uv sync --upgrade to update uv.lock file and install the latest versions of the dependencies.
2. Run uv tree --outdated --depth=1 will show what package versions are installed and what are the latest versions.
3. Run uv run pre-commit autoupdate

Also, Dependabot will help you to keep your dependencies up-to-date, see dependabot.yaml.

How to dump the database

1. Dump:

   docker compose exec db sh -c 'mongodump "mongodb://$MONGO_INITDB_ROOT_USERNAME:[email protected]:27017/db?authSource=admin" --db=db --out=dump/'

2. Restore:

   docker compose exec db sh -c 'mongorestore "mongodb://$MONGO_INITDB_ROOT_USERNAME:[email protected]:27017/db?authSource=admin" --drop /dump/db'

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.