{"id":25969028,"url":"https://github.com/oaklight/protein-score-server","last_synced_at":"2026-06-07T11:31:44.388Z","repository":{"id":279771292,"uuid":"852495586","full_name":"Oaklight/protein-score-server","owner":"Oaklight","description":"a score inference server using protein folding models and FastAPI","archived":false,"fork":false,"pushed_at":"2025-05-15T20:42:05.000Z","size":78330,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-09-18T14:13:28.453Z","etag":null,"topics":["alphafold3","async","computational-biology","esmfold","protein-structure","server"],"latest_commit_sha":null,"homepage":"https://oaklight.github.io/protein-score-server/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Oaklight.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}},"created_at":"2024-09-04T22:54:21.000Z","updated_at":"2025-02-28T07:53:33.000Z","dependencies_parsed_at":"2025-02-27T13:57:59.574Z","dependency_job_id":"eec2345b-b4d9-4618-8054-e443aa9203dc","html_url":"https://github.com/Oaklight/protein-score-server","commit_stats":null,"previous_names":["oaklight/protein-score-server"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/Oaklight/protein-score-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Oaklight%2Fprotein-score-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Oaklight%2Fprotein-score-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Oaklight%2Fprotein-score-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Oaklight%2Fprotein-score-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Oaklight","download_url":"https://codeload.github.com/Oaklight/protein-score-server/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Oaklight%2Fprotein-score-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34020187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["alphafold3","async","computational-biology","esmfold","protein-structure","server"],"created_at":"2025-03-04T22:36:55.079Z","updated_at":"2026-06-07T11:31:44.364Z","avatar_url":"https://github.com/Oaklight.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Protein Structure Score Server\n\n## 1. Introduction\n\nThis server is a protein structure prediction tool that processes prediction requests from users and capable of returning various scores for protein sequences.\n\n## 2. Installation\n\nTo install the environment, follow these steps:\n\n```bash\ngit clone https://github.com/Oaklight/protein-score-server.git\ncd protein-score-server\nconda env create -f environment.yaml\nconda activate esm\npip install -r requirements.txt\n```\n\n## 3. Server Configuration\n\n**Configuration File**: \n   - Copy `server.yaml.sample` to `server.yaml` :\n\n     \n\n```bash\ncp server.yaml.sample server.yaml\n```\n\n   - Edit `server.yaml` with your settings.\n\nThe server uses the `server.yaml` file for configuration. Currently configurable items include:\n\n* `api_key`: API key for Hugging Face Hub login.\n* `history_path`: History result storage path.\n* `intermediate_pdb_path`: Intermediate PDB file storage path.\n* `model`: Model configuration\n    - `name`: model name, `esmfold` or `protenix (bytedances' alphafold3 implementation)`\n    - `replica`: GPU device and replications mapping, should be in `\u003cdevice\u003e: \u003cnum_replica\u003e` format. For `esmfold` case, use `_: \u003cnum_replica\u003e` instead.\n* `task_queue_size`: Task queue size, default to 50.\n* `timeout`: Timeout for async prediction result retrieval, default to 15 seconds.\n* `backbone_pdb`:\n    - `reversed_index`: path for reverse index from pdb id to pdb file path\n    - `parquet_prefix`: path prefix for parquet files\n    - `pdb_prefix`: path prefix for pdb files\n\nFor example, see [ `server.yaml` ](./server.yaml)\n\nAfter the config are set, run these commands inside the project folder:\n\n```bash\nconda activate esm\nuvicorn main:app --host 0.0.0.0 --port 8000\n```\n\n## 4. Usage\n\n### 4.1. Request Prediction\n\nUsers can send `POST` requests to `http://your-host:8000/predict/` to get predictions. The request body comprises of these fields: `seq` , `name` , `type` , `seq2` .\n\n* `seq`: String, representing the protein sequence.\n* `name`: String, representing the name of the reference protein.\n* `type`: String, representing the task type, currently supports **\"plddt\", \"tmscore\", \"sc-tmscore\", \"pdb\"**.\n* `seq2`: String, representing the sequence of the reference protein. **Used only for `sc-tmscore` task. You may choose to provide either `seq2` or `name`**\n\n1. **pLDDT**\n\n```json\n{\n    \"seq\": \"MKRESHKHAEQARRNRLAVALHELASLIPAEWKQQNVSAAPSKATTVEAACRYIRHLQQNGST\",\n    \"type\": \"plddt\"\n}\n```\n\n2. **TMscore**\n\n```json\n{\n    \"seq\": \"MKRESHKHAEQARRNRLAVALHELASLIPAEWKQQNVSAAPSKATTVEAACRYIRHLQQNGST\",\n    \"name\": \"1a0a.A\", # must provide for tasks that require a reference structure\n    \"type\": \"tmscore\"\n}\n```\n\n3. **sc-TMscore**\n\n```json\n{\n    \"seq\": \"MKRESHKHAEQARRNRLAVALHELASLIPAEWKQQNVSAAPSKATTVEAACRYIRHLQQNGST\",\n    \"seq2\": \"MKRESHKHAEQARRNRLAVALHELASLIPAEWKQQNVSAAPSKATTVEAACRYIRHLQQNGST\", # choose to provide either seq2 or name\n    \"type\": \"sc-tmscore\"\n}\n```\n\nor\n\n```json\n{\n    \"seq\": \"MKRESHKHAEQARRNRLAVALHELASLIPAEWKQQNVSAAPSKATTVEAACRYIRHLQQNGST\",\n    \"name\": \"1a0a.A\", # choose to provide either seq2 or name\n    \"type\": \"sc-tmscore\"\n}\n```\n\n4. **pdb**\n\n```json\n{\n    \"seq\": \"MKRESHKHAEQARRNRLAVALHELASLIPAEWKQQNVSAAPSKATTVEAACRYIRHLQQNGST\",\n    \"type\": \"pdb\"\n}\n```\n\nThe server will return a JSON response containing two fields: `job_id` and `prediction` .\n\n* `job_id`: String, representing the task ID.\n* `prediction`: String, currently only indicating the prediction is in processing.\n\n```json\n{\n    \"job_id\": \"0a98a981748c4b7eacfd5e0957905ced\", # this is a uuid4 hex string\n    \"prediction\": ... # not very useful at this moment\n}\n```\n\n### 4.2. Result Retrieval\n\nUsers can send `GET` requests to `http://your-host:8000/result/{job_id}` to get prediction results. The header of the request should contain `Content-Type: application/json` .\n\nThe server will return a JSON response containing two fields: `job_id` and `prediction` .\n\n```json\n{\n    \"job_id\": \"0a98a981748c4b7eacfd5e0957905ced\", # this is a uuid4 hex string\n    \"prediction\": 0.983124\n}\n```\n\n### 4.3. Error Handling\n\nWhen querying for results, use the following guidelines based on the status code:\n- **102 Processing**: The task is queued. Wait a few seconds before checking again.\n- **202 Accepted**: The task is being processed. Wait a few seconds before checking again.\n- **200 OK**: The task is complete. The result is available in the response.\n- **404 Not Found**: The task ID is invalid. Check the ID or resubmit the task.\n- **429 Too Many Requests**: The server is busy. Wait and try again later.\n\n### 4.4. Retry Strategy\n\n* Recommend to use an exponential backoff strategy with a base of 3 when querying for results.\n* Example of querying is available in [`test.py`](test.py).\n\n## 5. Server Shutdown\n\nTo stop the server, use `Ctrl+C` in the terminal where the server is running.\n\n## 6. License\n\nThis server is licensed under the Apache License 2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foaklight%2Fprotein-score-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foaklight%2Fprotein-score-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foaklight%2Fprotein-score-server/lists"}