{"id":35885897,"url":"https://github.com/sillsdev/serval","last_synced_at":"2026-04-24T07:03:37.197Z","repository":{"id":88313607,"uuid":"607026958","full_name":"sillsdev/serval","owner":"sillsdev","description":"A REST API for natural language processing services","archived":false,"fork":false,"pushed_at":"2026-02-19T14:37:01.000Z","size":23766,"stargazers_count":4,"open_issues_count":44,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-02-19T18:13:37.121Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sillsdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-02-27T06:42:14.000Z","updated_at":"2026-02-18T20:11:21.000Z","dependencies_parsed_at":"2025-12-04T03:01:02.728Z","dependency_job_id":null,"html_url":"https://github.com/sillsdev/serval","commit_stats":{"total_commits":16,"total_committers":1,"mean_commits":16.0,"dds":0.0,"last_synced_commit":"cf70bb7d47b5fec0995ca858ba9ae80c14aa614c"},"previous_names":[],"tags_count":163,"template":false,"template_full_name":null,"purl":"pkg:github/sillsdev/serval","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sillsdev%2Fserval","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sillsdev%2Fserval/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sillsdev%2Fserval/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sillsdev%2Fserval/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sillsdev","download_url":"https://codeload.github.com/sillsdev/serval/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sillsdev%2Fserval/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29876375,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T22:37:10.609Z","status":"ssl_error","status_checked_at":"2026-02-26T22:37:09.019Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-08T20:15:27.789Z","updated_at":"2026-04-24T07:03:37.192Z","avatar_url":"https://github.com/sillsdev.png","language":"C#","readme":"[![Integration \u0026 Unit Tests](https://github.com/sillsdev/serval/actions/workflows/ci.yml/badge.svg)](https://github.com/sillsdev/serval/actions/workflows/ci.yml)\n[![End-To-End Tests](https://github.com/sillsdev/serval/actions/workflows/ci-e2e.yml/badge.svg)](https://github.com/sillsdev/serval/actions/workflows/ci-e2e.yml)\n[![codecov](https://codecov.io/gh/sillsdev/serval/graph/badge.svg?token=0PEQ9LXPK9)](https://codecov.io/gh/sillsdev/serval)\n\n# Serval - an API supporting Computer Aided Translation for all the languages of the world!\n\nServal is a REST API for natural language processing services for **all languages**.\nFor the REST documentation use the Swagger site [here](https://prod.serval-api.org/swagger/index.html).\n\n# Serval Architecture\n\nServal is designed as a modular monolith with a single deployable unit:\n\n- Serval.ApiServer\n  - The sole deployment — all REST calls are made through this layer.\n  - Hosts all domain modules in-process; modules communicate via interfaces rather than over the network.\n  - Domain modules under `./src/Serval/src`:\n    - `Serval.Translation` — translation engine management and pretranslation assembly\n    - `Serval.WordAlignment` — word alignment engine management\n    - `Serval.DataFiles` — file and corpus management\n    - `Serval.Webhooks` — webhook delivery\n    - `Serval.Shared` — common models, configuration, and services shared across modules\n  - Engine implementations (also hosted in-process):\n    - `Serval.Machine.Shared` — NMT, SMT Transfer, and Statistical engine implementations; also runs Hangfire background build jobs and queues ClearML GPU training jobs\n    - `EchoEngine` — echo engine for testing (translation and word alignment stubs)\n  - External runtime dependencies: MongoDB (persistence), Hangfire (job scheduling), ClearML (GPU training jobs), S3 (shared file storage for training data and models)\n- SIL.DataAccess\n  - Abstracts all MongoDB operations\n  - Enables in-memory database for testing purposes\n  - Replicates the functionality of [EF Core](https://learn.microsoft.com/en-us/ef/core/)\n\n# Development\n\n## Setting up Your Environment\n\n- Use VS Code with all the recommended extensions\n- Development is supported in Ubuntu and Windows WSL2\n  - For Ubuntu, use [microsoft's distribution of .net](https://learn.microsoft.com/en-us/dotnet/core/install/linux-ubuntu)\n  - Ubuntu 22.04 and 24.04 are currently supported\n- Install the repositories:\n  - To develop Serval, you will also likely need to make changes to the [Machine repo](https://github.com/sillsdev/machine) as well - they are intricately tied.\n  - To enable Serval to use your current edits in Machine (rather than the nuget package) you need to install Machine in an adjacent folder to Serval\n    - i.e., if your serval repo is cloned into /home/username/repos/serval, machine should be in /home/username/repos/machine\n  - Make sure that you build Machine using before you build Serval\n\n## Option 1: Docker Compose local testing deployment\n\nThese instructions are for developing/testing using docker-compose (rather than locally/bare metal)\nWith both the serval and machine repos installed, in the serval root folder, run `./docker_deploy.sh`\nTo debug in VSCode, launch \"ServalApi Docker\" after to containers come up (about 5 -10 seconds). This will allow you to debug all 4 serval containers.\n\n## Option 2: Bare metal local testing deployment\n\nAlternatively, you can develop without containerizing Serval.\n\nInstall MongoDB 8.0 as a replica set run it on localhost:27017. (You can run `docker compose -f docker-compose.mongo.yml up` from the root of the serval repo to do so).\n\nMake sure that the environment variable ASPNETCORE_ENVIRONMENT is set to \"Development\" by running `export ASPNETCORE_ENVIRONMENT=Development` or adding it to your `.bashrc`.\n\nOpen \"Serval.sln\" and debug the ApiServer.\n\n## Coding guidelines\n\nCoding guidelines are documented [on the wiki](https://github.com/sillsdev/serval/wiki/Development-Guide)\n\n## (Optional) Get your machine.py images setup\n\nWhen jobs are run, they are queued up on ClearML. If you want to have your own agents for integration testing (and you have a GPU with 24GB RAM), you can do the following:\n\n- clone the [machine.py repo](https://github.com/sillsdev/machine.py)\n- Build the docker image with `docker build . -t local.mpy` for a GPU image or `docker build . -f dockerfile.cpu_only -t local.mpy.cpu_only` for a CPU only image.\n- Register your machine as a ClearML agent (see dev team for details)\n  - Make sure you do NOT \"always pull the image\"! The images you are building are stored locally.\n- Set the following environment variables:\n\n```\nexport MACHINE_PY_IMAGE=local.mpy\nexport MACHINE_PY_CPU_IMAGE=local.mpy.cpu_only\n```\n\n### Running the API E2E Tests\n\nIn order to run the E2E tests, you will need to have the appropriate credentials\n\n- Get Client ID and Client Secret from auth0.com\n  - Login, go to Applications-\u003e Applications -\u003e \"Machine API (Test Application)\" or similar\n  - Copy `Client ID` into Environment variable `SERVAL_CLIENT_ID`\n  - Copy `Client Secret` into Environment variable `SERVAL_CLIENT_SECRET`\n  - Copy the auth0 url into Environment variable `SERVAL_AUTH_URL` (e.g. `SERVAL_AUTH_URL=https://sil-appbuilder.auth0.com`)\n  - Set `SERVAL_HOST_URL` to the api's URL (e.g. `SERVAL_HOST_URL=http://localhost`)\n    Now, when you run the tests from `Serval.E2ETests`, the token will automatically be retrieved from Auth0.\n\n## Special thanks to\n\nBugSnag for error reporting:\n\n\u003ca href=\"https://www.bugsnag.com/\"\u003e\n   \u003cimg src=\"https://www.bugsnag.com/wp-content/uploads/2023/06/63bc40cd9d502eda8ea74ce7_Bugsnag-Full-Color-1.svg\" alt=\"bugsnag\" width=\"200\"/\u003e\n\u003c/a\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsillsdev%2Fserval","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsillsdev%2Fserval","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsillsdev%2Fserval/lists"}