🤔 My Brainstorming Buddy

Chain-of-Thought Reasoning Engine — A multi-framework analytical system that processes questions through structured reasoning chains using an OpenAI-compatible API (sumopod).

🧠 How It Works

You ask a question — e.g., "Why are customers churning in our SaaS product?"
Auto-detect best framework — The LLM classifies your question and selects the most suitable analytical framework
Chain-of-Thought execution — The framework runs step-by-step, with each LLM call building on previous outputs
Structured result — You get a complete reasoning chain showing how the answer was derived

📋 Available Frameworks

Framework	Steps	Best For
Fishbone Diagram	4	Root cause analysis, manufacturing, business processes
Fault Tree Analysis	4	System failures, safety incidents, reliability engineering
Iceberg Model	4	Systemic issues, organizational challenges, deep patterns
Apollo RCA	5	Thorough incident investigation, causal relationships
STAMP	5	Complex socio-technical systems, safety-critical domains
Swiss Cheese Model	4	Layered defense systems, healthcare, aviation safety
Cynefin Framework	4	Problem classification, strategy, decision-making
DMAIC	5	Process improvement, Six Sigma, quality control
Jobs-to-be-Done (JTBD)	5	Customer needs, product innovation, market positioning
Value Proposition Canvas	5	Value proposition design, product-market fit
Beachhead Market Strategy	4	Market entry, startup strategy, adjacent expansion
Technology Adoption Life Cycle	4	Tech marketing, crossing the chasm, product launches
Blue Ocean Strategy	5	Market creation, differentiation, innovation strategy
Ideal Customer Profile	4	Sales targeting, lead scoring, marketing focus
STP (Segmentation, Targeting, Positioning)	4	Go-to-market planning, brand strategy, campaigns
Three Horizons of Growth	5	Corporate strategy, innovation management, long-term growth

🚀 Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Configure API Key

Copy .env.example to .env and fill in your sumopod API credentials:

cp .env.example .env

Edit .env:

SUMODOP_API_KEY=your_api_key_here
SUMODOP_BASE_URL=https://api.sumopod.com/v1
SUMODOP_MODEL=gpt-4o-mini

3. Run the Web UI (Streamlit)

streamlit run app.py

Open your browser to http://localhost:8501

4. Or Use the CLI

# Auto-detect framework
python main.py analyze "Why did the production line stop?" --api-key YOUR_KEY

# Specify a framework
python main.py analyze "What caused the system failure?" --fault_tree --api-key YOUR_KEY

# JSON output
python main.py analyze "How to improve customer retention?" --json --api-key YOUR_KEY

# List available frameworks
python main.py frameworks

🖥️ Web UI Features

Auto-detect or manually select a framework
Step-by-step display of the reasoning chain
Progress tracking showing completion status
Export results as Markdown or JSON
Configurable API endpoint, model, and key

📁 Project Structure

my-brainstorming-buddy/
├── app.py                    # Streamlit web UI
├── main.py                   # CLI entry point
├── Dockerfile                # 🐳 Docker build recipe (new)
├── docker-compose.yml        # 🐳 Docker run config (new)
├── docker-compose-with-n8n.yml # 🐳 n8n side-by-side example (new)
├── .dockerignore             # 🐳 Files to exclude from image (new)
├── requirements.txt
├── .env.example              # Copy to .env and add your API key
├── README.md
├── nginx/
│   └── default.conf          # 🌐 Sample Nginx config for domain (new)
├── src/
│   ├── __init__.py
│   ├── llm_adapter.py        # OpenAI-compatible API wrapper
│   ├── framework_selector.py # Auto-detect + manual override
│   ├── orchestrator.py       # Chain execution engine
│   ├── formatter.py          # Output formatting
│   └── frameworks/
│       ├── __init__.py
│       ├── base.py           # Abstract base class
│       ├── fishbone.py                 # Fishbone Diagram
│       ├── fault_tree.py               # Fault Tree Analysis
│       ├── iceberg.py                  # Iceberg Model
│       ├── apollo_rca.py               # Apollo Root Cause Analysis
│       ├── stamp.py                    # STAMP
│       ├── swiss_cheese.py             # Swiss Cheese Model
│       ├── cynefin.py                  # Cynefin Framework
│       ├── dmaic.py                    # DMAIC
│       ├── jtbd.py                     # Jobs-to-be-Done (JTBD)
│       ├── value_proposition_canvas.py # Value Proposition Canvas
│       ├── beachhead_market.py         # Beachhead Market Strategy
│       ├── tech_adoption_lifecycle.py  # Technology Adoption Life Cycle
│       ├── blue_ocean.py               # Blue Ocean Strategy
│       ├── ideal_customer_profile.py   # Ideal Customer Profile
│       ├── stp.py                      # STP (Segmentation, Targeting, Positioning)
│       └── three_horizons.py           # Three Horizons of Growth
└── tests/
    ├── __init__.py
    └── test_frameworks.py    # 41 tests for all 16 frameworks

🧪 Running Tests

python -m pytest tests/ -v

🐳 Deploy to Your Own Server (Docker)

Don't want to deal with servers? You can also run the app locally on your computer with streamlit run app.py (see Quick Start above).

This guide walks you through deploying My Brainstorming Buddy on a shared VPS — a single server that runs multiple apps (like n8n, websites, or this tool) side-by-side.

Who is this for?

📊 Data analysts who want a team-accessible reasoning tool
🎯 Marketing strategists who need it available 24/7
💻 Developers who want a clean, containerized deployment

What you'll learn:

How to package the app so it runs the same on any server
How to run it alongside other apps (like n8n) without conflicts
How to access it from anywhere using just a web browser

🧰 What is Docker? (Plain English)

Imagine you're packing a lunchbox. You put your sandwich, drink, and snack inside. No matter where you go — the office, a park, a friend's house — your lunch is the same.

Docker is like a lunchbox for your app. It packs the app + everything it needs (Python, libraries, settings) into a single box called a container. This means:

✅ It runs the same way on any computer or server
✅ You can run many apps side-by-side without them interfering
✅ If something breaks, you just restart the container — no re-installing

📋 What You'll Need

Before starting, make sure you have:

Item	Where to get it
☁️ A VPS (server)	Any provider: DigitalOcean, Linode, AWS, Azure, or your own computer
🐳 Docker	Install Docker (free)
🔑 API key	From your sumopod account (or any OpenAI-compatible provider)
🌐 A domain (optional)	For using `brainstorming-buddy.yourdomain.com` instead of `IP:8501`

💡 Tip: If you're on Windows, install Docker Desktop. If you're on Ubuntu/Linux, we'll install it in the next step.

Step 1: Install Docker

🐧 For Ubuntu / Linux VPS

Copy and paste these commands one by one into your server's terminal:

# Update your package list
sudo apt update

# Install Docker
sudo apt install docker.io -y

# Install Docker Compose (for running multi-app setups)
sudo apt install docker-compose-v2 -y

# Start Docker automatically on boot
sudo systemctl enable --now docker

# 👇 IMPORTANT: Add your user to the 'docker' group so you can run
#    Docker commands without 'sudo' (otherwise you'll get "permission denied")
sudo usermod -aG docker $USER

# Apply the group change (log out and back in, or run:)
newgrp docker

# Verify it's working
docker --version

What you should see: A version number like Docker version 24.0.7.

🪟 For Windows VPS

Download and install Docker Desktop for Windows
Open Docker Desktop (it will start automatically)
Open Command Prompt or PowerShell and type:
```
docker --version
```
You should see a version number — that means Docker is ready.

Step 2: Get the Project Files

You have two options:

Option A: Download as ZIP (easier for non-developers)

Go to the My Brainstorming Buddy GitHub page
Click the green "Code" button → "Download ZIP"
Upload the ZIP to your server, or unzip it on your computer and upload the folder

Option B: Clone with Git (for developers)

git clone https://github.com/khafidhteer/my-brainstorming-buddy.git
cd my-brainstorming-buddy

Step 3: Configure Your API Key

The app needs an API key to work. Here's how to set it up:

Copy the example config file:
```
cp .env.example .env
```
Open the .env file in any text editor (Notepad, VS Code, nano, vim).

Fill in your details:

SUMODOP_API_KEY=sk-your-actual-api-key-here
SUMODOP_BASE_URL=https://api.sumopod.com/v1
SUMODOP_MODEL=gpt-4o-mini

Setting	What to put
`SUMODOP_API_KEY`	Your actual API key from sumopod (starts with `sk-...`)
`SUMODOP_BASE_URL`	The API endpoint (usually leave as default)
`SUMODOP_MODEL`	Which AI model to use (e.g., `gpt-4o-mini`, `gpt-4o`)

🔒 Security note: The .env file contains your secret API key. Never share it or commit it to GitHub. The .gitignore and .dockerignore files already exclude it automatically.

Step 4: Build and Start the App 🚀

Now for the exciting part — let's get your app running!

What this command does:

Downloads all the necessary packages
Packs everything into a container (remember the lunchbox analogy?)
Starts the app so you can use it

docker compose up -d

What you should see: Text will scroll by as Docker downloads and builds everything. When it's done, you'll get your cursor back.

Check if it's running:

docker compose ps

You should see my-brainstorming-buddy listed with a status of "Up" (meaning running).

💡 Tip: The first time you run this, it may take 1-3 minutes to download everything. After that, it starts instantly.

Step 5: Open the App

Open your web browser and go to:

http://YOUR_SERVER_IP:8501

Replace YOUR_SERVER_IP with your server's actual IP address (e.g., http://123.456.78.90:8501).

You should see: The My Brainstorming Buddy web interface! 🎉

💡 Tip: If you're running this on your local computer (not a VPS), use http://localhost:8501 instead.

Step 6: Keep It Running

Auto-start on boot

Docker is configured to restart the app automatically if:

The server reboots
The app crashes unexpectedly

You don't need to do anything extra — it's already set up in the docker-compose.yml file.

Useful commands

What you want to do	Command
See live logs (what's happening right now)	`docker compose logs -f`
Stop the app	`docker compose down`
Restart the app	`docker compose restart`
Check if it's running	`docker compose ps`
Update to the latest version	See "Updating" below

Press Ctrl+C to stop viewing logs and return to the command prompt.

Updating to a new version

When there's an update to My Brainstorming Buddy:

# 1. Pull the latest code
git pull

# 2. Rebuild and restart
docker compose up -d --build

That's it! The app will be updated with zero downtime.

🧩 Running Multiple Apps (n8n + Brainstorming Buddy)

This is where Docker really shines. You can run My Brainstorming Buddy alongside n8n (or any other app) on the same server.

Option A: Use the included example file

We've included a ready-made file that runs both apps:

docker compose -f docker-compose-with-n8n.yml up -d

This starts:

My Brainstorming Buddy on port 8501
n8n on port 5678

Option B: Add n8n to your existing setup

Edit your docker-compose.yml file and add the n8n service:

services:
  brainstorming-buddy:
    # ... (existing config, don't change this)

  n8n:
    image: n8nio/n8n
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

Then run:

docker compose up -d

Option C: Add any other app

Follow the same pattern for any Docker app:

services:
  brainstorming-buddy:
    # ... existing config

  your-other-app:
    image: some-image-name
    container_name: my-other-app
    restart: unless-stopped
    ports:
      - "PORT_ON_SERVER:PORT_IN_CONTAINER"

💡 Tip: Make sure each app uses a different port on the left side of the colon. For example: 8501:8501, 5678:5678, 3000:3000.

Resource limits (important for shared VPS)

On a shared VPS, you want to make sure one app doesn't hog all the CPU or memory. Uncomment these lines in docker-compose.yml to limit resources:

deploy:
  resources:
    limits:
      cpus: '0.5'      # Max 50% of one CPU core
      memory: 512M     # Max 512 MB of RAM

This ensures Brainstorming Buddy and n8n play nicely together.

🌐 Going Further: Use a Domain Name (Optional)

🔧 For advanced users. If you just want the app working, you can skip this section and use http://YOUR_SERVER_IP:8501.

If you have a domain name, you can access your app at http://brainstorming-buddy.yourdomain.com instead of remembering an IP address and port number.

Step 1: Point your domain to your server

In your domain registrar's DNS settings, add an A record:

Name: brainstorming-buddy (or whatever subdomain you want)
Value: Your server's IP address

Step 2: Install Nginx

sudo apt install nginx -y

Step 3: Use the included Nginx config

We've included a sample config file at nginx/default.conf. Copy and adapt it:

sudo cp nginx/default.conf /etc/nginx/sites-available/brainstorming-buddy

Edit the file and replace brainstorming-buddy.yourdomain.com with your actual domain.

sudo nano /etc/nginx/sites-available/brainstorming-buddy

Enable the site and reload:

sudo ln -s /etc/nginx/sites-available/brainstorming-buddy /etc/nginx/sites-enabled/
sudo nginx -t          # Test the config
sudo nginx -s reload   # Apply changes

Step 4: Add HTTPS (free SSL certificate)

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d brainstorming-buddy.yourdomain.com

Follow the prompts. Certbot will automatically set up HTTPS for you.

🔧 Troubleshooting

"Permission denied while trying to connect to the Docker daemon socket"

This happens on Linux when your user doesn't have permission to run Docker commands. Fix it:

# Add your user to the 'docker' group
sudo usermod -aG docker $USER

# Log out and back in, or run this to apply immediately:
newgrp docker

# Test that it worked:
docker ps

You should see no errors. If you're using sudo to run Docker commands, you can also use sudo docker compose up -d as a temporary workaround.

"Port 8501 is already in use"

This means another app is already using port 8501. Change the port in docker-compose.yml:

ports:
  - "8502:8501"   # Use port 8502 on your server instead

Then access the app at http://YOUR_SERVER_IP:8502.

"Container keeps restarting"

Check the logs to see what's wrong:

docker compose logs -f

Common causes:

Missing or incorrect API key in .env
The .env file doesn't exist (copy from .env.example)

"I can't access the app from my browser"

Make sure the container is running: docker compose ps
Check your server's firewall allows port 8501:
```
# For Ubuntu with UFW
sudo ufw allow 8501
```
If using a cloud provider (AWS, Azure, DigitalOcean), check the security group / firewall settings in their dashboard — you may need to add a rule allowing port 8501.

"The app is slow"

On a shared VPS, other apps may be using resources. Enable resource limits (see "Resource limits" section above) to give each app its fair share.

📁 Files in This Folder (Docker-related)

File	What it does
`Dockerfile`	The recipe for building the app container
`docker-compose.yml`	How to run the app (single app)
`docker-compose-with-n8n.yml`	How to run alongside n8n (reference)
`.dockerignore`	Files to exclude from the container (keeps it small)
`nginx/default.conf`	Sample Nginx config for domain names (optional)

🔧 Configuration

All configuration is via .env file or environment variables:

Variable	Default	Description
`SUMODOP_API_KEY`	—	Your API key (required)
`SUMODOP_BASE_URL`	`https://api.sumopod.com/v1`	API endpoint
`SUMODOP_MODEL`	`gpt-4o-mini`	Model name

📝 Example

Question: "Why a retail company purchase insurance and how to identify the one will renew"

The system will:

Auto-detect the best framework (likely Fishbone or Apollo RCA)
Execute each step, building context progressively
Return a complete reasoning chain with actionable insights

🏗️ Architecture

User Question → Framework Selector (LLM) → Best Framework
                                              ↓
    Step 1 → LLM → output ──┐
                              ↓
    Step 2 → LLM → output ──┤ (context from previous steps)
                              ↓
    Step 3 → LLM → output ──┤
                              ↓
    ... → Final Result → Formatted Output

📄 License

MIT

Name		Name	Last commit message	Last commit date
.clinerules-memory-bank		.clinerules-memory-bank
nginx		nginx
src		src
tests		tests
.clinerules		.clinerules
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
app.py		app.py
docker-compose-with-n8n.yml		docker-compose-with-n8n.yml
docker-compose.yml		docker-compose.yml
main.py		main.py
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation