README.md

# Medicode

## Getting started

### Prerequisites

1. ffmpeg for audio processing in Bumblebee's speech-to-text serving: `brew install ffmpeg`.
2. Postgres and pgvector for storing data and vector embeddings: `brew install pgvector`.

### Running the server

To start your Phoenix server:

- Run `mix setup` to install and setup dependencies
- Run `mix build_code_vectors` to download the ICD-9 codelist, precompute vectors, and store the results in the database.
- Start Phoenix endpoint with `mix phx.server` or inside IEx with `iex -S mix phx.server`

Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.

Ready to run in production? Please [check our deployment guides](https://hexdocs.pm/phoenix/deployment.html).

## Deployment

The app is configured to deploy to Fly.io via a `fly.toml` file. To deploy, run `fly deploy` within the app's directory.

### Precomputing code vectors

To build the code vectors for the ICD-9 codelist for the deployed environment:

1. Connect to the server with `fly ssh console`.
2. Run `/app/bin/medical_transcription eval Medicode.Release.precompute_code_vectors`. This will prepare the vectors in the database if they are not present.

### Livebook

In addition to connecting to the deployed application via `iex`, Livebook supports connecting to the running application. Connecting a Livebook instance to the deployed application involves the following:

1. Install and setup Wireguard with a peer connection for Fly.io: [Step by Step](https://fly.io/docs/networking/private-networking/#install-your-wireguard-app)
2. Install and start Livebook: [Livebook.dev](https://livebook.dev/)
3. [Connecting Livebook to a Production App](https://fly.io/docs/elixir/advanced-guides/connect-livebook-to-your-app/) requires a node name and cookie value:

- Node name: `medical-transcription-cpu@myipfromfly` ("myipfromfly" can be retrieved with `fly ips private --app medical-transcription-cpu`)
- Cookie value: `0gfxcPtwryKxI2O1N0eFAg9p4MJGC-oUGShgj_wgvNEGiba5EDEJFA==` (this value is set in `fly.toml`)

## Run in Docker

1. Create a local volume: `docker volume create ml-data`
2. Ensure the volume is writeable: `docker run --rm -v ml-data:/data busybox /bin/sh -c 'touch /data/.initialized && chmod 1777 /data'`. More background:

- What the initial `1` for `chmod` means: <https://www.linuxnix.com/sticky-bit-set-linux/>
- How to update the permissions of a mounted volume: <https://serverfault.com/a/984599>

3. Build the image with: `docker build . -t headwayio/medical_transcription`
4. Run a container with: `docker run --env-file ./.env -p 4000:4000 headwayio/medical_transcription`

### Caveats

You may need to make a few changes to get the app running in Docker at the moment:

- In `lib/medical_transcription/application.ex`, comment out the `DNSCluster` child spec.
- In `rel/env.sh.eex`, comment out the `ERL_AFLAGS`, `RELEASE_DISTRIBUTION`, and `RELEASE_NODE` environment variables.

## Learn more

- Official website: <https://www.phoenixframework.org/>
- Guides: <https://hexdocs.pm/phoenix/overview.html>
- Docs: <https://hexdocs.pm/phoenix>
- Forum: <https://elixirforum.com/c/phoenix-forum>
- Source: <https://github.com/phoenixframework/phoenix>