{"id":42334279,"url":"https://github.com/mountain/quantum-pen","last_synced_at":"2026-01-27T14:11:54.305Z","repository":{"id":313652563,"uuid":"1052163089","full_name":"mountain/quantum-pen","owner":"mountain","description":"Stories are not written, but discovered.","archived":false,"fork":false,"pushed_at":"2025-09-07T16:28:52.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-07T16:34:03.887Z","etag":null,"topics":[],"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/mountain.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":"2025-09-07T14:36:44.000Z","updated_at":"2025-09-07T16:28:55.000Z","dependencies_parsed_at":"2025-09-07T16:44:32.661Z","dependency_job_id":null,"html_url":"https://github.com/mountain/quantum-pen","commit_stats":null,"previous_names":["mountain/quantum-pen"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mountain/quantum-pen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountain%2Fquantum-pen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountain%2Fquantum-pen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountain%2Fquantum-pen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountain%2Fquantum-pen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mountain","download_url":"https://codeload.github.com/mountain/quantum-pen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mountain%2Fquantum-pen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28814493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T12:25:15.069Z","status":"ssl_error","status_checked_at":"2026-01-27T12:25:05.297Z","response_time":168,"last_error":"SSL_read: 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-27T14:11:51.760Z","updated_at":"2026-01-27T14:11:54.290Z","avatar_url":"https://github.com/mountain.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Quantum Pen\n\n**Stories are not written, but discovered.**\n\n`Quantum Pen` is an experimental AI narrative co-creation engine. It transforms the solitary, linear path of writing into a thrilling expedition into the narrative multiverse. Here, every authorial \"intent\" is cast into a quantum field, instantly branching into dozens of parallel story realities.\n\nYou, the author, are the sole **Observer** in this narrative universe. Your choice is the act of measurement that **collapses the wave function** of fiction, turning one of countless possibilities into the one true canon.\n\nThis isn't just writing. It's navigating the narrative wave function.\n\n## Core Concepts\n\nThe workflow of `Quantum Pen` is a fusion of several key concepts:\n\n1.  **Evolutionary Algorithm:** The story itself is treated as a population. In each cycle, the fittest narrative paths survive and propagate through a process of \"reproduction\" (generating new chapters), \"mutation\" (diverse creative briefs), and \"selection\" (evaluation and filtering).\n2.  **AI Agent Ensemble:** The system employs three specialized AI agents working in concert:\n      * **The Director:** The strategist. Based on the author's intent and the current story, it generates multiple forward-looking creative briefs.\n      * **The Writer:** The novelist. It translates the Director's briefs into well-crafted, prose-rich chapters.\n      * **The Evaluator:** The critic. It quantitatively scores the Writers' outputs across multiple literary dimensions, providing the basis for natural selection.\n3.  **Divergence \u0026 Convergence:** Each creative cycle is a breath of creative expansion and contraction:\n      * **Divergence:** `3` parent texts → `9` director's briefs → `27` candidate chapters, maximizing the exploration of creative possibilities.\n      * **Convergence:** From `27` candidates, a `2+1` elite selection strategy filters the pool down to `3`, ensuring the story evolves towards a high-quality, coherent path.\n\n## How It Works\n\nThe system operates in iterative \"cycles.\" Here’s a breakdown of a single cycle:\n\n```\n[ Author's Intent ] -\u003e [ 3 Parent Texts ] -\u003e (Director) -\u003e [ 9 Briefs ] -\u003e (Writer) -\u003e [ 27 Candidates ] -\u003e (Evaluator) -\u003e [ 27 Scored Candidates ] -\u003e (Selection) -\u003e [ 3 New Parent Texts ] -\u003e (Loop)\n```\n\n1.  **Input:** The author defines the creative goal for the cycle in `intention.md`.\n2.  **Director Phase:** The Director reads the `3` texts from the current \"text pool\" and generates `9` unique creative briefs.\n3.  **Writer Phase:** The Writer AI takes the `9` briefs and generates `27` new candidate chapters.\n4.  **Evaluator Phase:** The Evaluator AI scores all `27` candidates based on predefined literary dimensions.\n5.  **Selection Phase:** A `2+1` algorithm selects the next generation:\n      * **Exploitation:** The top `2` highest-scoring candidates are chosen to preserve the strongest narrative threads.\n      * **Exploration:** `1` \"promising\" candidate—one that may not have the highest average score but excels in a key dimension (like creativity)—is also selected to prevent creative stagnation.\n6.  **Update Phase:** These `3` chosen candidates form the new text pool for the next cycle. Their full text is saved to the `story_progress/` directory.\n\n## Getting Started\n\nFollow these steps to begin your first co-creation session.\n\n### 1\\. Prerequisites\n\n*   Python 3.12+\n*   A running Redis instance (e.g., `redis-server` on your local machine).\n\n### 2\\. Create Your Writing Project\n\nFirst, create a dedicated folder for your story. This will keep your narrative files organized and separate from the tool's installation.\n\n```bash\nmkdir my-awesome-story\ncd my-awesome-story\n```\n\n### 3\\. Install Quantum Pen\n\nInstall the engine using pip. It's recommended to use a virtual environment for your project.\n\n```bash\npip install quantum-pen\n```\n\n### 4\\. Initialize Your Story\n\nInside your project folder (`my-awesome-story`), create three essential files:\n\n**1\\. `.env`**\n\nThis file holds your API key. `Quantum Pen` uses OpenRouter to access various language models.\n\n```\nOPENROUTER_API_KEY=\"sk-or-your-key-here\"\n```\n\n**2\\. `starter.md`**\n\nThis is the seed of your story—the opening paragraph or chapter.\n\n```markdown\n# The Chronos Key\n\nThe antique shop smelled of dust and forgotten time, a scent Elias knew better than his own name. He was an appraiser of histories, a man who could read the soul of an object from the scratches on its surface. But the device that lay on the velvet cloth before him was silent. It was a pocket watch crafted from a metal that shimmered like captured starlight, its face a complex astrolabe of unknown constellations. It had no hands to tell the time, only a single, keyhole-shaped aperture at its center.\n```\n\n**3\\. `intention.md`**\n\nThis file directs the AI for the next creative cycle. State your goal for the upcoming chapter.\n\n```markdown\nDeepen the mystery of the watch. Introduce a character who is also interested in it, creating a sense of competition or threat. The atmosphere should be tense and filled with suspicion.\n```\n\n### 5\\. Run the Engine\n\nWith your Redis server running, you're ready to start. From inside your project folder, run the command:\n\n```bash\nqp\n```\n\nThe engine will start its first cycle. A new `story_progress/` directory will be created to store the generated chapters. To continue the story, simply update `intention.md` with your new goal and run `qp` again.\n\n## Your Writing Project Structure\n\nAfter running the engine, your project folder will look like this:\n\n```\nmy-awesome-story/\n├── .env                # Your API key\n├── starter.md          # The story's starting point\n├── intention.md        # Your creative goal for the next cycle\n└── story_progress/     # (Auto-generated) Stores the output of each cycle\n    ├── cycle_01_cand_01.md\n    ├── cycle_01_cand_02.md\n    └── ...\n```\n\n## Customization\n\nYou can easily customize the engine by editing the `CONFIGURATION` section in `quantum_pen.py`:\n\n  * **Change Models:** Swap out `DIRECTOR_MODEL`, `WRITER_MODEL`, and `EVALUATOR_MODEL` with any supported model on OpenRouter.\n  * **Adjust Parameters:** Modify `TEXT_POOL_SIZE` or `WRITER_BRANCH_FACTOR` to change the scale of the evolutionary process.\n  * **Refine Evaluation:** Add or change dimensions in `EVALUATION_DIMENSIONS` and update the `EVALUATOR_PROMPT_TEMPLATE` to match, fine-tuning the selection criteria.\n\n## License\n\nThis project is licensed under the MIT License.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmountain%2Fquantum-pen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmountain%2Fquantum-pen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmountain%2Fquantum-pen/lists"}