<commit_before>
# Jormungandr
Web service around the c++ core(s). This is the navitia api front end, based on flask.

:snake: **python module**

## Norse mythology
In the Norse mythology, Jörmungandr is a sea serpent that grew so large that it can surround the earth, hence his name: <NAME>. He will be killed by Thor during Ragnarok.

# Setup
## VirtualEnv

```sh
cd navitia/source/jormungandr
mkvirtualenv jormungandr
pip install -r requirements.txt -r requirements_dev.txt -U
```

# Configure

Jormungandr uses 2 different levels of config:
* `jormungandr.json` : that describes Kraken's instances and coverages
* Jormungandr's core config via :
	* Environment variables [the prefered option]  
	* A custom setting file `custom_settings.py` [for advanced usage] - that overwrites default settings

## jormungandr.json

Create a file `jormungandr.json` in a custom directory like:

```json
{
    "key": "some_region",
    "socket": "ipc:///tmp/default_kraken"
}
```

You can copy the one from [documentation/examples/config/Jormungandr.json](https://github.com/CanalTP/navitia/blob/dev/documentation/examples/config/Jormungandr.json)

Make sure `key` and `socket` respectively match `instance_name` and `zmq_socket` from your Kraken config file ([kraken.ini](https://github.com/CanalTP/navitia/blob/dev/documentation/examples/config/kraken.ini)).

As an alternative, you can also give the json through an environment variable like:
```sh
JORMUNGANDR_INSTANCE_FR_IDF='{"key": "fr-idf","zmq_socket": "tcp://localhost:3000"}'
```

## Environment Variables

Environment variables can be set when the service is started. Referer to [default_settings.py](https://github.com/CanalTP/navitia/blob/dev/source/jormungandr/jormungandr/default_settings.py)

example for a devlopment environment: 

```sh
PYTHONPATH=..:../../navitiacommon/ JORMUNGANDR_INSTANCES_DIR=~/jormung_conf/ JORMUNGANDR_START_MONITORING_THREAD=False  JORMUNGANDR_DISABLE_DATABASE=True JORMUNGANDR_IS_PUBLIC=True python manage.py runserver
```

## custom_settings.py

This helps you overwrite the default settings from a file. Prevent from mixing both custom file settings and environment variables. 

Use `JORMUNGANDR_CONFIG_FILE` to tell where your file is located like:  

```sh
PYTHONPATH=..:../../navitiacommon/ JORMUNGANDR_INSTANCES_DIR=~/jormung_conf/ JORMUNGANDR_CONFIG_FILE=~/jormung_conf/jormung_settings.py  python manage.py runserver
```

# Run 

To run the web service, you'll need to:

* set `JORMUNGANDR_INSTANCES_DIR` to point at the directory that contains your `jormungandr.json`.
* add `navitia/source/jormungandr` and `navitia/navitiacommon` to your python path via `PYTHONPATH`.
* [optionaly] set `JORMUNGANDR_CONFIG_FILE` to point at your `custom_settings.py`.  

## Example

From `navitia/source/jormungandr/jormungandr` run :

```sh
PYTHONPATH=..:../../navitiacommon/ JORMUNGANDR_INSTANCES_DIR=~/jormung_conf/ python manage.py runserver
```

# Troubleshooting

### Python error : `No module named jormungandr`
> from jormungandr import app
>
> ImportError: No module named jormungandr

Make sure you have `navitia/source/jormungandr` in your `PYTHONPATH`

### Python error : `No module named navitiacommon`
> from navitiacommon import response_pb2, type_pb2
>
> ImportError: No module named navitiacommon

Make sure you have `navitia/source/navitiacommon` in your `PYTHONPATH`

### Jormungandr returns a `No region nor coordinates given`
> http://localhost:5000/v1/coverage/
>
> {"message":"No region nor coordinates given","id":"unknown_object"}}

You file `jormungandr.json` is not found or your `key` and `socket` don't match your `kraken.ini`

### Python error : `No module named flask`
> from flask import Flask, got_request_exception
> 
> ImportError: No module named flask

Make sure you use your `jormungandr` VirtualEnv with :
<commit_msg>Document autocomplition setup for Bragi & Jormung<commit_after>
# Jormungandr
Web service around the c++ core(s). This is the navitia api front end, based on flask.

:snake: **python module**

## Norse mythology
In the Norse mythology, Jörmungandr is a sea serpent that grew so large that it can surround the earth, hence his name: Midgard Serpent. He will be killed by Thor during Ragnarok.

# Setup
## VirtualEnv

```sh
cd navitia/source/jormungandr
mkvirtualenv jormungandr
pip install -r requirements.txt -r requirements_dev.txt -U
```

# Configure

Jormungandr uses 2 different levels of config:
* `jormungandr.json` : that describes Kraken's instances and coverages
* Jormungandr's core config via :
	* Environment variables [the prefered option]  
	* A custom setting file `custom_settings.py` [for advanced usage] - that overwrites default settings

## jormungandr.json

Create a file `jormungandr.json` in a custom directory like:

```json
{
    "key": "some_region",
    "socket": "ipc:///tmp/default_kraken"
}
```

You can copy the one from [documentation/examples/config/Jormungandr.json](https://github.com/CanalTP/navitia/blob/dev/documentation/examples/config/Jormungandr.json)

Make sure `key` and `socket` respectively match `instance_name` and `zmq_socket` from your Kraken config file ([kraken.ini](https://github.com/CanalTP/navitia/blob/dev/documentation/examples/config/kraken.ini)).

As an alternative, you can also give the json through an environment variable like:
```sh
JORMUNGANDR_INSTANCE_FR_IDF='{"key": "fr-idf","zmq_socket": "tcp://localhost:3000"}'
```

## Environment Variables

Environment variables can be set when the service is started. Referer to [default_settings.py](https://github.com/CanalTP/navitia/blob/dev/source/jormungandr/jormungandr/default_settings.py)

example for a devlopment environment: 

```sh
PYTHONPATH=..:../../navitiacommon/ JORMUNGANDR_INSTANCES_DIR=~/jormung_conf/ JORMUNGANDR_START_MONITORING_THREAD=False  JORMUNGANDR_DISABLE_DATABASE=True JORMUNGANDR_IS_PUBLIC=True python manage.py runserver
```

## custom_settings.py

This helps you overwrite the default settings from a file. Prevent from mixing both custom file settings and environment variables. 

Use `JORMUNGANDR_CONFIG_FILE` to tell where your file is located like:  

```sh
PYTHONPATH=..:../../navitiacommon/ JORMUNGANDR_INSTANCES_DIR=~/jormung_conf/ JORMUNGANDR_CONFIG_FILE=~/jormung_conf/jormung_settings.py  python manage.py runserver
```

# Run 

To run the web service, you'll need to:

* set `JORMUNGANDR_INSTANCES_DIR` to point at the directory that contains your `jormungandr.json`.
* add `navitia/source/jormungandr` and `navitia/navitiacommon` to your python path via `PYTHONPATH`.
* [optionaly] set `JORMUNGANDR_CONFIG_FILE` to point at your `custom_settings.py`.  

## Example

From `navitia/source/jormungandr/jormungandr` run :

```sh
PYTHONPATH=..:../../navitiacommon/ JORMUNGANDR_INSTANCES_DIR=~/jormung_conf/ python manage.py runserver
```

# Option
## Autocomplete

Setup Jormung for using either `Bragi` or `Kraken` for autocompletion

```sh
JORMUNGANDR_AUTOCOMPLETE_SYSTEMS='{"kraken": { "class": "jormungandr.autocomplete.kraken.Kraken" }, "bragi": {"class": "jormungandr.autocomplete.geocodejson.GeocodeJson", "args": {"host": "http://1172.16.17.32:4000", "timeout": 2}}}'
```

You can select your autocomplete engine based on the `_autocomplete` parameter when querying Jormung:

```sh
http://localhost:5000/v1/coverage/default/places?q=rennes&_autocomplete='<kraken|bragi>'
```

# Troubleshooting

### Python error : `No module named jormungandr`
> from jormungandr import app
>
> ImportError: No module named jormungandr

Make sure you have `navitia/source/jormungandr` in your `PYTHONPATH`

### Python error : `No module named navitiacommon`
> from navitiacommon import response_pb2, type_pb2
>
> ImportError: No module named navitiacommon

Make sure you have `navitia/source/navitiacommon` in your `PYTHONPATH`

### Jormungandr returns a `No region nor coordinates given`
> http://localhost:5000/v1/coverage/
>
> {"message":"No region nor coordinates given","id":"unknown_object"}}

You file `jormungandr.json` is not found or your `key` and `socket` don't match your `kraken.ini`

### Python error : `No module named flask`
> from flask import Flask, got_request_exception
> 
> ImportError: No module named flask

Make sure you use your `jormungandr` VirtualEnv with :

{'fraction_non_alphanumeric': 0.10898522644708161, 'fraction_numerical': 0.005328166626301768, 'mean_word_length': 5.333588957055214, 'pattern_counts': {'":': 19, '<': 5, '<?xml version=': 0, '>': 29, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 1, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '748474', 'n_tokens_mistral': 2896, 'n_tokens_neox': 2771, 'n_words': 798}