{"id":25950240,"url":"https://github.com/raestrada/storycraftr","last_synced_at":"2025-10-05T20:12:12.032Z","repository":{"id":257864948,"uuid":"872127015","full_name":"raestrada/storycraftr","owner":"raestrada","description":"StoryCraftr is an open-source AI-powered tool that helps writers craft stories, generate worldbuilding details, and create book outlines and chapters seamlessly through a simple CLI. Empower your creativity with AI!","archived":false,"fork":false,"pushed_at":"2025-04-24T17:52:59.000Z","size":1272,"stargazers_count":38,"open_issues_count":1,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-25T16:15:10.047Z","etag":null,"topics":["ai","llms","natural-language-processing","novel-writing","openai","python"],"latest_commit_sha":null,"homepage":"","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/raestrada.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-10-13T21:00:29.000Z","updated_at":"2025-05-25T15:06:10.000Z","dependencies_parsed_at":"2024-10-27T23:07:45.902Z","dependency_job_id":"ecc95474-9860-449d-8c2e-2218e13a9480","html_url":"https://github.com/raestrada/storycraftr","commit_stats":null,"previous_names":["raestrada/storycraftr"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/raestrada/storycraftr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raestrada%2Fstorycraftr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raestrada%2Fstorycraftr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raestrada%2Fstorycraftr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raestrada%2Fstorycraftr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raestrada","download_url":"https://codeload.github.com/raestrada/storycraftr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raestrada%2Fstorycraftr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278510931,"owners_count":25999005,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"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":["ai","llms","natural-language-processing","novel-writing","openai","python"],"created_at":"2025-03-04T12:53:24.546Z","updated_at":"2025-10-05T20:12:12.025Z","avatar_url":"https://github.com/raestrada.png","language":"Python","funding_links":[],"categories":["\u003ca name=\"writing\"\u003e\u003c/a\u003eWriting"],"sub_categories":[],"readme":"[![GitHub Actions Status](https://github.com/raestrada/storycraftr/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/raestrada/storycraftr/actions)  \n[![GitHub Actions Status](https://github.com/raestrada/storycraftr/actions/workflows/pytest.yml/badge.svg)](https://github.com/raestrada/storycraftr/actions)\n\n# \u003cimg src=\"https://res.cloudinary.com/dyknhuvxt/image/upload/f_auto,q_auto/ofhhkf6f7bryfgvbxxwc\" alt=\"StoryCraftr Logo\" width=\"100\" height=\"100\"\u003e StoryCraftr - Your AI-powered Book Creation Assistant 📚🤖\n\nWelcome to [**StoryCraftr**](https://storycraftr.app), the open-source project designed to revolutionize how books are written. With the power of AI and a streamlined command-line interface (CLI), StoryCraftr helps you craft your story, manage worldbuilding, structure your book, and generate chapters — all while keeping you in full control.\n\n---\n\n## What's New? Discover AI Craftr 🌐\n\n**[AI Craftr](https://aicraftr.app)** is now available as a powerful suite for AI-assisted writing, featuring specialized tools like **StoryCraftr** for novelists and **[PaperCraftr](https://papercraftr.app)** for researchers. Each tool is designed to simplify your writing process with unique features catered to different types of content. Explore **PaperCraftr** for structuring academic papers, or stay tuned as we add more tools to the AI Craftr suite, such as **LegalCraftr** for legal documents and **EduCraftr** for educational materials.\n\n---\n\n## Release Notes v0.10.1-beta4\n\nYou can find the release notes for version `v0.10.1-beta4` [here](https://github.com/raestrada/storycraftr/releases/tag/v0.10.1-beta4).\n\n## Step 1: Install StoryCraftr\n\nFirst, install **StoryCraftr** using [pipx](https://pypa.github.io/pipx/), a tool to help you install and run Python applications in isolated environments. It works on most platforms, including macOS, Linux, and Windows. Using `pipx` ensures that **StoryCraftr** runs in its own virtual environment, keeping your system's Python installation clean.\n\nTo install **StoryCraftr**, run the following command:\n\n```bash\npipx install git+https://github.com/raestrada/storycraftr.git@v0.10.1-beta4\n```\n\nAlternatively, if you have `uv` and `uvx` installed on your system, you can run storycraftr without installing it first:\n\n```bash\nuvx --from git+https://github.com/raestrada/storycraftr.git@v0.10.1-beta4 storycraftr\n```\n\n### Important: Before using StoryCraftr, make sure to set your OpenAI API key:\n\nStore the key in a text file located at `~/.storycraftr/openai_api_key.txt` for convenience.\n\n```bash\nmkdir -p ~/.storycraftr/\necho \"your-openai-api-key\" \u003e ~/.storycraftr/openai_api_key.txt\n```\n\n### New: Specify OpenAI Model and URL\n\nStoryCraftr now allows you to specify the OpenAI model and URL, which can be any service that supports the OpenAI API with file search capabilities, such as DeepSeek or others. This is essential as StoryCraftr relies on file search for its functionality.\n\nTo configure the model and URL, add the following lines to your configuration file located at `~/.storycraftr/config.json`:\n\n```json\n{\n  \"openai_model\": \"your-preferred-model\",\n  \"openai_url\": \"https://api.your-preferred-service.com\"\n}\n```\n\nMake sure to replace `\"your-preferred-model\"` with the model you want to use and `\"https://api.your-preferred-service.com\"` with the URL of the service that supports the OpenAI API with file search.\n\n### Supported LLMs\n\nHere are some examples of LLMs that are compatible with the OpenAI API:\n\n1. **OpenAI GPT Series**:\n    - Models: `gpt-3.5-turbo`, `gpt-4`\n    - URL Base: `https://api.openai.com/v1/`\n    - Documentation: [OpenAI API Models](https://beta.openai.com/docs/models)\n\n2. **Azure OpenAI Service**:\n    - Models: `gpt-3.5-turbo`, `gpt-4`\n    - URL Base: Depends on the region and configuration.\n    - Documentation: [Azure OpenAI Service](https://azure.microsoft.com/en-us/services/cognitive-services/openai-service/)\n\n3. **DeepSeek**:\n    - Model: `DeepSeek-R1`\n    - URL Base: `https://api.deepseek.com/v1/`\n    - Documentation: [DeepSeek API Documentation](https://deepseek.com/docs)\n\n4. **Qwen (Alibaba Cloud)**:\n    - Models: `qwen-7b`, `qwen-13b`\n    - URL Base: `https://dashscope.aliyuncs.com/`\n    - Documentation: [DashScope API](https://dashscope.aliyuncs.com/docs)\n\n5. **Gemini (Google AI)**:\n    - Models: `gemini-1`, `gemini-1.5`\n    - URL Base: `https://api.gemini.google.com/v1/`\n    - Documentation: [Gemini API](https://gemini.google.com/docs)\n\n6. **Together AI**:\n    - Model: `together-gpt-neoxt-chat-20b`\n    - URL Base: `https://api.together.ai/v1/`\n    - Documentation: [Together AI API](https://together.ai/docs)\n\n7. **DeepInfra**:\n    - Model: `Qwen2.5-Coder-32B-Instruct`\n    - URL Base: `https://api.deepinfra.com/v1/`\n    - Documentation: [DeepInfra API](https://deepinfra.com/docs)\n\n## Quick Examples\n\nHere are a few ways to get started with **StoryCraftr**:\n\n### Initialize a new book project:\n\n```bash\nstorycraftr init \"La purga de los dioses\" --primary-language \"es\" --alternate-languages \"en\" --author \"Rodrigo Estrada\" --genre \"science fiction\" --behavior \"behavior.txt\" --openai-model \"gpt-4\" --openai-url \"https://api.openai.com/v1/\"\n```\n\n### Generate a general outline:\n\n```bash\nstorycraftr outline general-outline \"Summarize the overall plot of a dystopian science fiction where advanced technology, resembling magic, has led to the fall of humanity’s elite and the rise of a manipulative villain who seeks to destroy both the ruling class and the workers.\"\n```\n\n## 💬 Introducing Chat!!! – A Simple Yet Powerful Tool to Supercharge Your Conversations! 💥\n\nWhether you're brainstorming ideas, refining your story, or just need a little creative spark, Chat!!! is here to help. It's a straightforward, easy-to-use feature that lets you dive deep into meaningful discussions, unlock new insights, and get your thoughts flowing effortlessly.\n\n🚀 Sometimes, all you need is a little chat to get the gears turning! Try it out and watch your creativity soar!\n\n![chat](https://res.cloudinary.com/dyknhuvxt/image/upload/v1729551304/chat-example_hdo9yu.png)\n\n## Full Guide\n\nFor a complete guide, including more examples and instructions on how to fully leverage StoryCraftr, visit our **Getting Started** page:\n\n👉 [**Getting Started with StoryCraftr**](https://storycraftr.app/getting_started.html) 👈\n\n## Why StoryCraftr?\n\nWriting a book is a journey that involves not only creativity but also structure, consistency, and planning. **StoryCraftr** is here to assist you with:\n\n- **Worldbuilding**: Define the geography, history, cultures, and more.\n- **Outline**: Generate a cohesive story outline, from character summaries to chapter synopses.\n- **Chapters**: Automatically generate chapters, cover pages, and epilogues based on your ideas.\n\nWith StoryCraftr, you'll never feel stuck again. Let AI guide your creative process, generate ideas, and help you bring your world and characters to life.\n\n## StoryCraftr Chat Feature 💬\n\nThe **StoryCraftr Chat** feature allows users to engage directly with an AI assistant, helping to brainstorm, refine, and improve your book in real time. The chat supports various commands for outlining, iterating, and world-building, making it a powerful tool for writers to create and enhance their stories interactively.\n\n### Key Commands:\n\n- **Iterate**: Refine character names, motivations, and even insert new chapters mid-book.  \n  Example:\n\n  ```bash\n  !iterate insert-chapter 3 \"Add a flashback between chapters 2 and 3.\"\n  ```\n\n- **Outline**: Generate the general plot, chapter summaries, or key plot points.  \n  Example:\n\n  ```bash\n  !outline general-outline \"Summarize the overall plot of a dystopian sci-fi novel.\"\n  ```\n\n- **Worldbuilding**: Build the world’s history, geography, and technology, or develop the magic system.  \n  Example:\n\n  ```bash\n  !worldbuilding magic-system \"Describe the 'magic' system based on advanced technology.\"\n  ```\n\n- **Chapters**: Write new chapters or adjust existing ones and generate cover text.  \n  Example:\n\n  ```bash\n  !chapters chapter 1 \"Write chapter 1 based on the synopsis.\"\n  ```\n\nYou can start a chat session with the assistant using:\n\n```bash\nstorycraftr chat --book-path /path/to/your/book\n```\n\nFor help with available commands during the session, simply type:\n\n```bash\nhelp()\n```\n\n## VSCode Extension\n\nWe are excited to introduce the **StoryCraftr** VSCode extension, designed to seamlessly integrate the StoryCraftr CLI into your development environment. This extension allows you to interact with StoryCraftr directly from VSCode, offering powerful tools for novel writing and AI-assisted creativity.\n\n### Key Features:\n\n- **Auto-detection**: Automatically detects if `storycraftr.json` is present in the project root, ensuring the project is ready to use.\n- **Integrated Chat**: Start interactive AI-powered chat sessions for brainstorming and refining your novel without leaving VSCode.\n- **Simplified Setup**: If StoryCraftr or its dependencies (Python, pipx) are not installed, the extension assists you in setting them up.\n\n### Installation:\n\nYou can install the StoryCraftr VSCode extension directly from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=StoryCraftr.storycraftr).\n\n### Usage:\n\nOnce installed, the extension will:\n\n1. Check if `storycraftr.json` exists in the root of your project.\n2. If it exists, you can start interacting with StoryCraftr by launching a terminal with the `chat` command using:\n   - **Command Palette**: Run `Start StoryCraftr Chat`.\n3. If not installed, it will guide you through installing Python, pipx, and StoryCraftr to get started.\n\nExplore more about the [StoryCraftr CLI](https://github.com/raestrada/storycraftr) and see how it can boost your storytelling workflow.\n\nLet your creativity flow with the power of AI! ✨\n\n## Contributing\n\nWe welcome contributions of all kinds! Whether you’re a developer, writer, or simply interested in improving the tool, you can help. Here’s how you can contribute:\n\n1. **Fork the repository** and create your branch:\n\n```bash\ngit checkout -b feature/YourFeature\n```\n\n2. **Make your changes**, ensuring all tests pass.\n\n3. **Submit a pull request** detailing your changes.\n\nJoin us on this journey to create an amazing open-source tool for writers everywhere. Together, we can make StoryCraftr the go-to AI writing assistant! 💡\n\n## Powered by AI Craftr\n\n**StoryCraftr** is part of the **AI Craftr** suite, an open-source set of tools designed to assist with creative and academic writing. AI Craftr enhances the productivity of writers, researchers, and educators, providing advanced tools for content creation.\n\n![AI Craftr Logo](https://res.cloudinary.com/dyknhuvxt/image/upload/v1730059761/aicraftr_qzknf4.png)\n\nYou can learn more about **AI Craftr** and discover other tools like **PaperCraftr** for academic writing at [https://aicraftr.app](https://aicraftr.app).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraestrada%2Fstorycraftr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraestrada%2Fstorycraftr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraestrada%2Fstorycraftr/lists"}