🧠 Evolving Ideas CLI

Turn chaos into clarity. Evolving Ideas helps developers and creators capture, structure, and evolve their thoughts into real, buildable systems.

🚀 Features

• Classic brainstorming method with structured prompts
• YAML versioning for ideas
• Stores context, questions, answers, and summaries
• OpenAI integration
• CLI-first interface

📦 Coming Soon

• improve: refine and push your ideas further
• evolve: branch and explore new directions
• Visual idea trees, idea templates, and more

📂 Project Structure

evolving-ideas/
│
├── .env-example # Example .env file
├── manage.py # Dev entry point
├── requirements.txt # Dependencies
├── .store/ # Ideas and cache
│ ├── cache.yaml # Cache store
│ └── ideas/ # Idea folders
├── evolving_ideas/ # Main app
│ ├── app.py # Main entry logic
│ ├── cli.py # CLI interface
│ ├── common/ # Cache & logging
│ ├── domain/ # Models, services, repos
│ ├── infra/ # OpenAI & transport
│ ├── prompts/ # Prompt templates & builder
│ ├── interface/ # Chat logs & presenters
│ ├── sessions/ # Session state
│ └── strategies/ # Brainstorming methods

🛠 Setup

Evolving Ideas provides a streamlined setup for Windows environments using a Makefile.

• Requires python>=3.9<=3.11
• OpenAI API Key in .env
• Windows only support for now

✅ Automated Setup (Windows only)

If you're on Windows and have Python 3.9–3.11 installed:

make setup

This will:

• Check your Python version (must be between 3.9 and 3.11)
• Create a virtual environment at .venv
• Install all dev and docs dependencies
• Set up pre-commit hooks for linting and formatting

After that, activate your environment with:

.venv\Scripts\activate

🛠 Manual Setup (Linux/Mac or fallback)

If you're not on Windows or prefer manual steps:

# Create and activate the virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt
pip install -r requirements-docs.txt

# (Optional but recommended) Set up pre-commit
pre-commit install

✨ Pre-commit

We use pre-commit to ensure consistent formatting and linting across the codebase. Hooks include:

• **isort** (with black profile)
• black
• pylint (with several warnings disabled)
• pytest

To run them manually on all files:

pre-commit run --all-files

If you skip pre-commit installation, you'll need to run the formatters and linters manually before committing.

🧪 Usage

python manage.py add

📚 Documentation

To build the docs locally:

# Create virtualenv and install docs dependencies
python -m venv .venv
source .venv\Scripts\activate
pip install -r requirements-docs.txt

# Build docs
cd docs
make.bat html

Then open: docs/build/html/index.html in your browser.

📜 License

MIT – see LICENSE

---

🤝 Contributing

We welcome contributions! Please read the contributing guide and code of conduct before getting started.