{"id":49107376,"url":"https://github.com/a692570/hookscore","last_synced_at":"2026-04-21T02:17:43.230Z","repository":{"id":350149424,"uuid":"1205537369","full_name":"a692570/hookscore","owner":"a692570","description":"Score your hook - predict if people will read your content using LLM surprise as a brain engagement proxy","archived":false,"fork":false,"pushed_at":"2026-04-09T03:50:28.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-09T05:31:57.207Z","etag":null,"topics":["brain","content","engagement","llm","neuroscience","nlp","openai-compatible","predictive","surprise","text-analysis","willtheyread"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/a692570.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":"2026-04-09T03:47:38.000Z","updated_at":"2026-04-09T03:50:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/a692570/hookscore","commit_stats":null,"previous_names":["a692570/hookscore"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/a692570/hookscore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a692570%2Fhookscore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a692570%2Fhookscore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a692570%2Fhookscore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a692570%2Fhookscore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/a692570","download_url":"https://codeload.github.com/a692570/hookscore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a692570%2Fhookscore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32073516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T01:35:38.224Z","status":"online","status_checked_at":"2026-04-21T02:00:06.111Z","response_time":128,"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":["brain","content","engagement","llm","neuroscience","nlp","openai-compatible","predictive","surprise","text-analysis","willtheyread"],"created_at":"2026-04-21T02:17:42.453Z","updated_at":"2026-04-21T02:17:43.223Z","avatar_url":"https://github.com/a692570.png","language":"Python","readme":"# hookscore\n\n![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)\n![License: MIT](https://img.shields.io/badge/license-MIT-green)\n\n**Score your hook - predict if people will read your content using LLM surprise as a brain engagement proxy.**\n\nHookScore splits your text into chunks, asks an LLM how surprising each chunk is given what came before, and turns those scores into an engagement report: per-chunk bars, avg/peak/trough/variance, drop-off detection, and an overall verdict.\n\nBased on research from UChicago showing that LLM prediction error (\"surprise\") correlates with human brain engagement ([Zhang \u0026 Rosenberg, Nature Human Behaviour, 2025](https://doi.org/10.1038/s41562-024-02017-0) | [code](https://github.com/ZiweiZhang0304/Surprise_EFPM)).\n\n## Install\n\n```bash\npip install hookscore\n```\n\nOr from source:\n\n```bash\npip install git+https://github.com/a692570/hookscore.git\n```\n\n## Quick Start\n\n```bash\n# Set your API key\nexport HOOKSCORE_API_KEY=\"sk-...\"\n\n# Score a post\nhookscore \"We spent three years building what everyone said was impossible. Then we launched on a Tuesday.\"\n\n# Score from a file\nhookscore --file draft.txt\n\n# Compare two variants\nhookscore --compare version_a.txt version_b.txt\n\n# Use a different model or API endpoint\nhookscore --api-base https://my-llm.example.com/v1 --model llama3 \"Your text here\"\n\n# Adjust chunk size\nhookscore --chunk-size 20 \"Your text here\"\n```\n\n## How It Works\n\n1. **Chunk** your text into overlapping segments (default: 15 words, 3-word overlap)\n2. **Score** each chunk by asking the LLM: \"On a scale of 1-10, how engaging/surprising is this next part for the reader?\" given the context so far\n3. **Extract** the last number from the response (models often reason before concluding)\n4. **Normalize** to a 0.1-1.0 scale\n5. **Report** per-chunk bars, statistics, drop-offs, and an overall verdict\n\n### Verdicts\n\n| Avg Surprise | Variance | Verdict |\n|---|---|---|\n| \u003e0.65 | \u003e0.02 | HIGH ENGAGEMENT |\n| \u003e0.55 | - | GOOD |\n| \u003e0.45 | - | AVERAGE |\n| \u003c0.35 | - | LOW |\n| - | \u003c0.005 | FLAT |\n| otherwise | - | MIXED |\n\n### The Science\n\nZhang \u0026 Rosenberg found that when an LLM's prediction error spikes (i.e., text is \"surprising\" to the model), the same regions of the human brain that track engagement also spike. HookScore uses this insight as a heuristic: if the LLM finds your text surprising, your readers probably will too.\n\n\u003e Zhang, M., \u0026 Rosenberg, M. D. (2025). Brain network dynamics predict engagement during naturalistic listening. *Nature Human Behaviour*. https://doi.org/10.1038/s41562-024-02017-0\n\u003e\n\u003e Research code: [ZiweiZhang0304/Surprise_EFPM](https://github.com/ZiweiZhang0304/Surprise_EFPM)\n\n## Configuration\n\n| Env Variable | Default | Description |\n|---|---|---|\n| `HOOKSCORE_API_KEY` | *(none)* | Your API key. **Required.** |\n| `HOOKSCORE_API_BASE` | `https://api.openai.com/v1` | OpenAI-compatible API base URL |\n| `HOOKSCORE_MODEL` | `gpt-4o-mini` | Model name |\n\nAll config can also be passed via CLI flags (`--api-base`, `--model`).\n\n**Security note:** HookScore only reads `HOOKSCORE_API_KEY` from environment variables. It never reads from config files, dotfiles, or credential stores.\n\n## Example Output\n\n```\n============================================================\nHOOKSCORE - ENGAGEMENT PREDICTION REPORT\n  (LLM Surprise -\u003e Brain Engagement Proxy)\n============================================================\n\n  [   0-15]       HIGH ################ 0.80\n       \"We spent three years building what everyone said...\"\n\n  [  12-27]   MED-HIGH #############---- 0.65\n       \"was impossible. Then we launched on a Tuesday...\"\n\n  [  24-39]       HIGH ################ 0.85\n       \"a Tuesday. By Friday, we had 10,000 users. The...\"\n\n------------------------------------------------------------\n  Avg surprise:   0.733\n  Peak surprise:  0.850 (chunk 2)\n  Trough:         0.650 (chunk 1)\n  Variance:       0.0067 (higher = more dynamic)\n\n============================================================\n  VERDICT: GOOD - keeps reader engaged\n============================================================\n```\n\n## A/B Comparison\n\n```bash\nhookscore --compare draft_v1.txt draft_v2.txt\n```\n\n```\n==================================================\nA/B ENGAGEMENT COMPARISON\n==================================================\nMetric                            A          B     Winner\n--------------------------------------------------\nAvg surprise                   0.620      0.710          B\nVariance                       0.0080     0.0150          B\nPeak surprise                  0.800      0.900          B\n--------------------------------------------------\nOVERALL                        0.452      0.576          B\n==================================================\n```\n\n## Python API\n\n```python\nfrom hookscore import score_text, analyze, format_report\n\nresults = score_text(\"Your text here\", api_key=\"sk-...\")\nreport = analyze(results)\nprint(format_report(report))\n```\n\n## Limitations\n\n- **Heuristic, not fMRI.** This uses LLM judgment as a proxy for human brain engagement. It correlates with the neuroscience, but it's not the same thing.\n- **Model-dependent.** Different LLMs will produce different surprise scores. A model that finds everything surprising isn't useful.\n- **Short texts are unreliable.** With fewer chunks, there's less signal. Posts under ~30 words get a baseline score, not a real analysis.\n- **No ground truth.** This predicts engagement potential, not actual engagement. Real engagement depends on audience, context, timing, and distribution.\n- **Temperature 0.** Scores are deterministic for a given model, but different providers may implement temperature 0 differently.\n\n## Citation\n\nIf you use HookScore in research:\n\n```bibtex\n@software{hookscore2025,\n  title = {HookScore: Predict Text Engagement Using LLM Surprise},\n  author = {Abhishek},\n  url = {https://github.com/a692570/hookscore},\n  year = {2025}\n}\n```\n\nAnd please cite the underlying research:\n\n```bibtex\n@article{zhang2025brain,\n  title = {Brain network dynamics predict engagement during naturalistic listening},\n  author = {Zhang, M. and Rosenberg, M. D.},\n  journal = {Nature Human Behaviour},\n  year = {2025},\n  doi = {10.1038/s41562-024-02017-0}\n}\n```\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa692570%2Fhookscore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fa692570%2Fhookscore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa692570%2Fhookscore/lists"}