{"id":50713671,"url":"https://github.com/zaydiscold/hooke-preview","last_synced_at":"2026-06-09T17:03:53.190Z","repository":{"id":344733164,"uuid":"1182743434","full_name":"zaydiscold/hooke-preview","owner":"zaydiscold","description":"FastAPI research app for hard-science questions with literature retrieval, genomic follow-up, and streaming briefs.","archived":false,"fork":false,"pushed_at":"2026-03-16T03:47:33.000Z","size":62,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-16T14:43:58.709Z","etag":null,"topics":["fastapi","genomics","research","science","sse"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zaydiscold.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2026-03-15T22:56:06.000Z","updated_at":"2026-03-16T03:47:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zaydiscold/hooke-preview","commit_stats":null,"previous_names":["zaydiscold/hooke-preview"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/zaydiscold/hooke-preview","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydiscold%2Fhooke-preview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydiscold%2Fhooke-preview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydiscold%2Fhooke-preview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydiscold%2Fhooke-preview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zaydiscold","download_url":"https://codeload.github.com/zaydiscold/hooke-preview/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydiscold%2Fhooke-preview/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34116461,"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-09T02:00:06.510Z","response_time":63,"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":["fastapi","genomics","research","science","sse"],"created_at":"2026-06-09T17:03:52.303Z","updated_at":"2026-06-09T17:03:53.182Z","avatar_url":"https://github.com/zaydiscold.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/banner.svg\" alt=\"hooke banner\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ehooke\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003eagent-orchestrated research assistant for hard-science questions.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/last-commit/zaydiscold/hooke-preview?style=flat-square\u0026labelColor=1a1a2e\u0026color=B4A7D6\" alt=\"last commit\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/zaydiscold/hooke-preview?style=flat-square\u0026labelColor=1a1a2e\u0026color=5F9EA0\" alt=\"stars\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/status-preview-D4AF37?style=flat-square\u0026labelColor=1a1a2e\" alt=\"status\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.11%2B-B4A7D6?style=flat-square\u0026labelColor=1a1a2e\" alt=\"python\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/streaming-sse-5F9EA0?style=flat-square\u0026labelColor=1a1a2e\" alt=\"streaming\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#overview\"\u003eoverview\u003c/a\u003e ·\n  \u003ca href=\"#what-the-app-does\"\u003ewhat the app does\u003c/a\u003e ·\n  \u003ca href=\"#run-locally\"\u003erun locally\u003c/a\u003e ·\n  \u003ca href=\"#example-questions\"\u003eexample questions\u003c/a\u003e\n\u003c/p\u003e\n\nHooke is an agent-orchestrated research assistant for hard-science questions.\nIt retrieves evidence from scientific and web sources, optionally adds genomic\nfollow-up, and returns a citation-grounded research brief in a streaming\ninterface.\n\nThe repository contains a local research workflow for questions that need\nsource collection, synthesis, and explicit next-step reasoning.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"./video/out/hooke-promo.mp4\"\u003e\n    \u003cimg src=\"./assets/hooke-demo.gif\" width=\"900\" alt=\"hooke demo\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003eclick the gif for the full demo video.\u003c/sub\u003e\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/stars1.svg\" alt=\"·\" /\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n## Overview\n\nA user submits a question, Hooke classifies the request into one of three\ninvestigation modes, runs the relevant agents, and streams both intermediate\nlogs and the final brief to the browser.\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/stars2.svg\" alt=\"·\" /\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n## What the app does\n\nHooke provides these capabilities:\n\n- Retrieves literature from PubMed, Semantic Scholar, Tavily, OpenAlex, and\n  arXiv through the literature pipeline.\n- Selects among three investigation modes: literature-only, parallel genomic\n  follow-up, or literature-first gene discovery followed by genomic analysis.\n- Streams agent progress and final output to the frontend through server-sent\n  events.\n- Uses AlphaGenome when available and falls back to Ensembl-based genomic\n  interpretation when needed.\n- Produces a structured research brief with findings, research gaps, proposed\n  experiments, and citations.\n- Generates compact lucky-mode starter queries for exploratory research.\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/stars3.svg\" alt=\"·\" /\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n## Architecture\n\nThe application is split into a small number of focused components:\n\n- `main.py`: FastAPI entrypoint, static file serving, lucky-query handling, and\n  SSE endpoints.\n- `orchestrator.py`: query classification, mode routing, and pipeline control.\n- `agents/literature.py`: source retrieval, filtering, and paper analysis.\n- `agents/genomic.py`: AlphaGenome and Ensembl-backed genomic analysis.\n- `agents/synthesis.py`: brief generation and JSON normalization.\n- `static/index.html`: single-page interface for queries, logs, and research\n  briefs.\n- `health_check.py`: provider and API connectivity checks.\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/stars4.svg\" alt=\"·\" /\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n## Requirements\n\nSet up the app from the project root:\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\ncp .env.example .env\n```\n\nThe environment file must define these variables:\n\n- `NEBIUS_API_KEY`\n- `OPENROUTER_API_KEY`\n- `TAVILY_API_KEY`\n- `GOOGLE_API_KEY`\n- `SEMANTIC_SCHOLAR_API_KEY` for higher Semantic Scholar rate limits\n- `PUBMED_EMAIL`\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/stars5.svg\" alt=\"·\" /\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n## Run locally\n\nStart the development server with Uvicorn:\n\n```bash\nuvicorn main:app --reload --port 8000\n```\n\nThen open [http://127.0.0.1:8000](http://127.0.0.1:8000).\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/stars6.svg\" alt=\"·\" /\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n## Health check\n\nRun the connectivity check before a demo or local test session:\n\n```bash\npython3 health_check.py\n```\n\nThis script verifies whether the configured providers are reachable.\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/stars7.svg\" alt=\"·\" /\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n## Example questions\n\nThese prompts match the current demo flow:\n\n1. How does Ozempic actually work at the molecular level, and why does it cause\n   muscle loss?\n2. What tissues is the `LCT` gene most active in, and why can some adults\n   digest milk while others cannot?\n3. Why do some people get severe kidney disease, and what genes are involved?\n4. What makes some cancer tumors resistant to PD-1 or PD-L1 immunotherapy?\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/stars8.svg\" alt=\"·\" /\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n## Operational notes\n\nKeep these constraints in mind when you run the app:\n\n- Semantic Scholar can rate-limit unauthenticated requests.\n- AlphaGenome is optional; Hooke falls back to Ensembl-based interpretation if\n  AlphaGenome is unavailable.\n- Prompt-injection evaluation is not implemented yet. Promptfoo is a planned\n  addition for future prompt-injection testing and security review.\n- Generated cache files remain local and are excluded from git.\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://star-history.com/#zaydiscold/hooke-preview\u0026Date\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=zaydiscold/hooke-preview\u0026type=Date\u0026theme=dark\" /\u003e\n      \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=zaydiscold/hooke-preview\u0026type=Date\" /\u003e\n      \u003cimg src=\"https://api.star-history.com/svg?repos=zaydiscold/hooke-preview\u0026type=Date\u0026theme=dark\" width=\"320\" alt=\"star history chart\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/stars9.svg\" alt=\"·\" /\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"left\"\u003e\u003cstrong\u003ezayd / cold\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://zayd.wtf\"\u003ezayd.wtf\u003c/a\u003e · \u003ca href=\"https://x.com/coldcooks\"\u003etwitter\u003c/a\u003e · \u003ca href=\"https://github.com/zaydiscold\"\u003egithub\u003c/a\u003e\n  \u003cbr\u003e\n  \u003cem\u003eicarus only fell because he flew\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"right\"\u003e\n  \u003cstrong\u003eto do\u003c/strong\u003e\u003cbr\u003e\n  \u003csub\u003e\n  ☑ streaming brief and pipeline logs\u003cbr\u003e\n  ☐ prompt-injection eval coverage (promptfoo)\n  \u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\u003cbr\u003e\n\u003cbr\u003e\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/wisps.svg\" alt=\"\" /\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaydiscold%2Fhooke-preview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzaydiscold%2Fhooke-preview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaydiscold%2Fhooke-preview/lists"}