| title | K-ZERO Council of 8 |
|---|---|
| emoji | 🎯 |
| colorFrom | red |
| colorTo | purple |
| sdk | docker |
| app_port | 7860 |
| pinned | true |
| license | mit |
| short_description | 8 minds. 1 question. Infinite consequences. |
██████╗ ██████╗ ██╗ ██╗███╗ ██╗ ██████╗██╗██╗ ██████╗ ███████╗ █████╗
██╔════╝██╔═══██╗██║ ██║████╗ ██║██╔════╝██║██║ ██╔═══██╗██╔════╝ ██╔══██╗
██║ ██║ ██║██║ ██║██╔██╗ ██║██║ ██║██║ ██║ ██║█████╗ ╚█████╔╝
██║ ██║ ██║██║ ██║██║╚██╗██║██║ ██║██║ ██║ ██║██╔══╝ ██╔══██╗
╚██████╗╚██████╔╝╚██████╔╝██║ ╚████║╚██████╗██║███████╗ ╚██████╔╝██║ ╚█████╔╝
╚═════╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═════╝╚═╝╚══════╝ ╚═════╝ ╚═╝ ╚════╝
Drop 8 of history's greatest minds into a room. Ask a question. Watch them collide. Then turn their collision into a book, a podcast, a probability distribution, and a Twitter thread.
Python License Cost PyPI Stars Hugging Face
https://kyeongsun-kzero.hf.space — no install, no API key, just go.
| Method | Link | What You Get |
|---|---|---|
| Windows .exe | Download kzero.exe | Double-click to run. Auto-installs Ollama + model. No setup needed. |
| Live Demo | kyeongsun-kzero.hf.space | Chat with the Council in your browser. Zero install. |
| Local (pip) | See Quick Start below | Full K-ZERO Console + Hegelian dialectic + overnight batch runs |
| Kaggle | Open in Kaggle | Run simulations in Kaggle notebook |
# Option A: Install from PyPI pip install the-council # Option B: Clone for full access (characters, scenarios, everything) git clone https://github.com/ksk5429/kzero.git && cd kzero pip install -r requirements.txt
Get a free API key from console.groq.com or ai.google.dev (no credit card), then:
# Create .env with your free key echo 'LLM_API_KEY=your_key_here' > .env echo 'LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/' >> .env echo 'COUNCIL_MODEL=gemini-2.5-flash' >> .env
Three ways to run:
# 1. Council Runner — automated multi-agent deliberation python -m runner.council_runner --rounds 5 # 2. K-ZERO Console — YOU are God, the council obeys python -m runner.demiurge # 3. Dialectic Evolution — Hegelian thesis/antithesis/synthesis python -m runner.dialectic "Should humanity pursue immortality?" --rounds 5
One question in. Seven artifacts out.
QUESTION
|
v
+-----------+ +-----------+ +----------+ +----------+ +------------+
| Simulate | -> | Analyze | -> | Report | -> | Artifacts| -> | Distribute |
| 8 agents | | LLM parse | | Quarto | | NbookLM | | X thread |
| N rounds | | positions | | HTML/PDF | | podcast | | 280 chars |
+-----------+ +-----------+ +----------+ +----------+ +------------+
| | | | |
transcript.json analysis.json report.pdf flashcards thread.md
study guide
quiz, slides
mind map
briefing doc
# Full pipeline, start to finish python -m runner.council_runner --rounds 5 # Simulate python -m runner.analyze transcripts/session_*.json # Analyze python -m runner.predict "Is AI the next stage of evolution?" --runs 10 # Predict python -m runner.report predictions/session_*.json --format all # Report python -m runner.artifacts reports/session_*.pdf --all # Artifacts python -m runner.thread transcripts/session_*.json # Twitter thread python -m runner.visualize transcripts/session_*_analysis.json # Dashboard
Three engines, three philosophies.
Natural multi-agent conversation with god-mode injection. Set a scenario, choose a discussion mode, and let 8 agents argue while you inject plot twists mid-session.
python -m runner.council_runner --scenario scenarios/scenario_01_meaning_of_life.json --rounds 5
Interactive REPL. You are the demiurge. Type anything and the council reacts. Whisper to one agent. Inject breaking news. Force a vote. Pull one thread and watch the whole tapestry shift.
python -m runner.demiurge --scenario scenarios/scenario_02_ai_alignment.json
Hegelian algorithm. No free-form conversation — each round follows a strict protocol:
THESIS Agent states their position
|
ANTITHESIS Agent reviews ALL other positions, identifies challenges
|
SYNTHESIS Agent integrates what challenged them most
|
REVISION Agent produces a revised position (may shift, may hold)
Over N rounds, positions genuinely evolve. The output is not a transcript but a thought evolution map — showing how each mind changed and why.
python -m runner.dialectic "What is consciousness?" --rounds 5 --agents 4Every simulation can run in any of 8 modes. Switch mid-session with /mode <name>.
| Mode | Emoji | What Happens |
|---|---|---|
philosophical_seminar |
📚 | Open exploration, Socratic depth, no winners |
oxford_debate |
⚔️ | Formal adversarial debate, proposition vs opposition |
yes_no_vote |
:ballot_box_with_ballot: | Council votes YES or NO, majority wins |
multiple_choice |
📊 | Council picks from options, ranked results |
brainstorm |
💡 | No criticism allowed, pure ideation, wild ideas welcomed |
war_room |
🪖 | Crisis scenario, time pressure, decisive action required |
socratic_dialogue |
🤔 | Question-driven inquiry, no assertions, only questions |
delphi_method |
🔮 | Anonymous rounds, convergence tracking, expert consensus |
| Name | Role | MBTI | One-liner | |
|---|---|---|---|---|
| 🔴 | Elon Musk | The Builder | INTJ | "Consciousness must become multi-planetary or it dies." |
| 🔵 | Richard Feynman | The Curious One | ENTP | "I'd rather have questions that can't be answered than answers that can't be questioned." |
| 🟡 | Kobe Bryant | Mamba Mentality | ENTJ | "Rest at the end, not in the middle." |
| ⚪ | Steve Jobs | The Curator | ENTJ | "Real artists ship." |
| 🟣 | Jean-Paul Sartre | The Existentialist | INFJ | "Man is condemned to be free." |
| 🟢 | George Carlin | The Satirist | INTP | "Think of how stupid the average person is. Half of them are stupider than that." |
| 💠 | Bryan Johnson | The Extreme Optimizer | INTJ | "Don't die." |
| ⬜ | Kevin Kim | The Moderator | INTJ | "The question behind the question is the real question." |
MUSK ←——0.7——→ JOBS Feynman ←—0.65—→ Carlin
↕ ↕
(0.6) (0.7) tension
↕ ↕
KOBE SARTRE ←——0.65——→ KOBE
↕
(0.5) CARLIN ←—0.75—→ JOHNSON
↕
JOHNSON MUSK ←——0.8——→ JOHNSON
Each persona is built from ~3,500 tokens of researched personality data — speech patterns, core axioms, clash dynamics, and formative memories sourced from primary texts. The LLM doesn't improvise a personality. It inhabits one.
You are the demiurge. The council exists because you willed it.
K-ZERO > What if humans could upload their consciousness to the cloud?
(type anything — the council reacts)
K-ZERO > /ask feynman Does Bryan's immortality quest make any sense?
(whisper to one agent)
K-ZERO > /inject BREAKING: A message from the future confirms no one
will remember any of you in 200 years.
(watch the shockwave)
K-ZERO > /mode war_room
(switch to crisis mode)
K-ZERO > /vote Should humanity pursue immortality?
(force YES/NO vote)
K-ZERO > /end
(save transcript, get synthesis, exit)
| Command | What it does |
|---|---|
(any text) |
Pose a question — all 8 agents respond |
/all <question> |
Same as above, explicit |
/ask <name> <text> |
Whisper to one agent directly |
/inject <text> |
God-mode variable injection — mid-debate plot twist |
/next |
Let the next round play out naturally |
/next <N> |
Run N rounds without intervention |
/mode <name> |
Switch discussion mode (see 8 modes above) |
/vote <question> |
Force YES/NO vote |
/who |
Show all members and their current stance |
/history |
Show recent transcript |
/synthesis |
Kevin synthesizes the discussion so far |
/end |
End session and save transcript |
The Hegelian engine doesn't produce conversations. It produces evolution maps.
python -m runner.dialectic "Is free will an illusion?" --rounds 5Each agent goes through 4 phases per round. Over 5 rounds, that's 20 introspective steps per agent. Positions genuinely shift. Alliances form and break. The output tracks:
- Position trajectory — Where each agent started vs where they ended
- Key shifts — The exact moment an argument changed someone's mind
- Convergence score — Did the council find common ground, or split further apart?
- Strongest argument — Which thesis survived the most scrutiny?
Run the same question N times. If answers converge, it has an answer. If they diverge, it's genuinely open.
python -m runner.predict "Should humanity pursue immortality?" --runs 10 --rounds 3Outputs:
- Probability distribution — What percentage of runs reached each conclusion
- Convergence metric — How stable is the answer across runs?
- Minority reports — The strongest dissenting positions
- Confidence interval — How much to trust the majority
The distribution reveals what no single run can: whether the question has a center of gravity or is fundamentally contested.
Turn simulation results into polished Quarto reports — the translation layer between swarm intelligence and human understanding.
python -m runner.report predictions/immortality_20260402.json --format html
python -m runner.report predictions/immortality_20260402.json --format pdf
python -m runner.report predictions/immortality_20260402.json --format all # HTML + PDF + DOCXReports include:
- Executive summary (LLM-generated)
- Position evolution charts (Plotly)
- Agreement/conflict maps
- Prediction distributions
- K-ZERO's divine recommendation
The report is the seed. NotebookLM is the multiplier. One question becomes seven learning materials.
python -m runner.artifacts reports/immortality_20260402.pdf --all
| Artifact | What You Get |
|---|---|
--podcast |
Audio Overview — two hosts discussing the council's deliberation |
--study-guide |
Structured study guide with key concepts and takeaways |
--quiz |
Multiple-choice quiz to test comprehension |
--flashcards |
Spaced-repetition flashcards for key arguments |
--slides |
Slide deck summarizing the deliberation |
--mind-map |
Visual mind map of connected ideas |
--briefing |
Executive briefing document |
--all |
Generate everything |
Interactive Plotly Dash dashboard showing everything that happened.
python -m runner.analyze transcripts/session_20260402.json
python -m runner.visualize transcripts/session_20260402_analysis.json
# Opens at http://localhost:8050The dashboard shows:
- Network graph — Who agrees with whom, weighted by interaction strength
- Conflict heatmap — Pairwise agreement/disagreement intensity
- Position timeline — How each agent's stance evolves across rounds
- Key quotes — Most impactful moments, auto-extracted
- Emergent insights — Ideas no individual proposed, but the group produced
- Chat log panel — Full transcript with agent colors and round markers
14 Python modules. ~6,000 lines. Zero fluff.
the_council/
├── runner/
│ ├── agent.py # Agent class, OpenAI-compatible, 4-key rotation
│ ├── council_runner.py # Mode-aware automated simulation engine
│ ├── demiurge.py # K-ZERO Console (interactive god-mode REPL)
│ ├── dialectic.py # Hegelian dialectic evolution engine
│ ├── modes.py # 8 discussion modes + voting engine
│ ├── evolution.py # Opinion tracking + convergence/divergence detection
│ ├── predict.py # Multi-run aggregation + probability distribution
│ ├── analyze.py # LLM transcript analysis + JSON repair
│ ├── visualize.py # Plotly Dash dashboard with chat log panel
│ ├── report.py # Quarto report generator (HTML, PDF, DOCX)
│ ├── artifacts.py # NotebookLM artifact pipeline
│ ├── thread.py # Twitter/X thread generator
│ ├── validate.py # Data integrity checker
│ └── __init__.py
├── characters/
│ ├── musk/ # ~3,500 tokens of personality data each
│ │ ├── personality_matrix.json
│ │ ├── voice.md # Speech patterns
│ │ ├── axioms.md # 10 core beliefs
│ │ ├── clash_points.md # Dynamics with every other member
│ │ └── memory_seeds.md # Key life experiences
│ ├── feynman/
│ ├── kobe/
│ ├── jobs/
│ ├── sartre/
│ ├── carlin/
│ ├── johnson/
│ └── kevin/
├── scenarios/
│ ├── scenario_01_meaning_of_life.json
│ ├── scenario_02_ai_alignment.json
│ └── scenario_03_death_and_legacy.json
├── config/
│ └── discussion_modes.json # 8 mode definitions
├── transcripts/ # Auto-saved session transcripts (JSON)
├── predictions/ # Multi-run prediction results
├── reports/ # Generated Quarto reports
├── visualizations/ # Exported dashboard assets
├── dialectics/ # Dialectic evolution outputs
├── profiles/
│ └── council_profiles.json
├── requirements.txt
├── pyproject.toml
├── Dockerfile # HF Spaces deployment
├── app.py # Gradio app for HF Spaces
└── .env # Your API key (not committed)
No credit card needed. Seriously.
| Provider | Free Tier | Best Model | Signup |
|---|---|---|---|
| Ollama | Unlimited, local, free forever | llama3.3:70b, qwen2.5:32b |
ollama.com |
| Google AI Studio | Generous free tier | gemini-2.5-flash |
aistudio.google.com |
| Groq | Very generous free tier | llama-3.3-70b-versatile |
console.groq.com |
| OpenRouter | Free models available | meta-llama/llama-3.3-70b-instruct:free |
openrouter.ai |
# Ollama (local, unlimited, recommended for heavy use) LLM_API_KEY=ollama LLM_BASE_URL=http://localhost:11434/v1 COUNCIL_MODEL=llama3.3:70b # Google AI Studio LLM_API_KEY=your_google_key LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/ COUNCIL_MODEL=gemini-2.5-flash # Groq (fastest inference) LLM_API_KEY=gsk_your_groq_key LLM_BASE_URL=https://api.groq.com/openai/v1 COUNCIL_MODEL=llama-3.3-70b-versatile # OpenRouter (most model variety) LLM_API_KEY=sk-or-your_key LLM_BASE_URL=https://openrouter.ai/api/v1 COUNCIL_MODEL=meta-llama/llama-3.3-70b-instruct:free
Each character is a folder under characters/ with 5 files:
| File | Purpose |
|---|---|
personality_matrix.json |
Cognitive biases, knowledge domains, interaction weights |
voice.md |
How they talk — sentence structure, vocabulary, verbal tics |
axioms.md |
10 non-negotiable beliefs |
clash_points.md |
How they react to every other member |
memory_seeds.md |
Formative experiences the LLM can reference |
Use primary sources. Biographies, interviews, their own writing. The richer the data, the more the agent sounds like them instead of a chatbot cosplaying.
mkdir characters/nietzsche # Create the 5 files above # The system auto-discovers new character folders
"The book is the translation layer between swarm intelligence and individual human understanding."
K-ZERO doesn't answer questions. It generates thought landscapes — showing where 8 brilliant minds agree, where they clash, and where none of them have been yet.
The pipeline turns that landscape into something you can read, listen to, quiz yourself on, and share. One question becomes a book, a podcast, a probability distribution, and a Twitter thread.
The question was never "What is the answer?"
The question was always "What does the answer look like from 8 directions at once?"
- Fork the repo
- Create a branch (
git checkout -b feat/nietzsche-agent) - Add your character, scenario, mode, or feature
- Test it runs with at least one free API
- Open a PR
Character contributions are especially welcome. The world needs a council with Nietzsche, Ada Lovelace, Marcus Aurelius, or Frida Kahlo in it.
MIT. Do whatever you want. Build your own council. Ask your own questions. Break reality.
"The unexamined life is not worth living." — Socrates
"Examine it with 8 agents, a Hegelian dialectic, and a free API." — K-ZERO