Every subject is a cosmos. Enter it.

EverNodes is an interactive, AI-powered knowledge mapping tool. Enter any topic and it instantly generates a beautifully visualized, hierarchical graph of concepts — powered by Groq (Llama 4 Scout) on the backend and vis.js on the frontend. Explore concepts node by node, dive deeper into any subject, mark what you've learned, and save your progress.

git clone https://github.com/your-username/EverNodes.git
cd EverNodes

pip install -r requirements.txt

requirements.txt includes:

flask
groq
python-dotenv

Sign up at console.groq.com — the free tier is generous for personal use.

Create a .env file in the project root:

GROQ_API_KEY=gsk_your_key_here

python app.py

Open http://127.0.0.1:5000 in your browser.

1. Type any learnable topic in the text area (e.g. "Quantum Mechanics", "Jazz Theory", "Ancient Rome")
2. Optionally describe what you already know
3. Select Beginner, Intermediate, or Expert
4. Click Generate Map

• Click a node → preview in the bottom info panel
• Double-click a node → open the Portal (full detail view with child cards)
• Drag nodes → rearrange the layout (auto-saved)
• Scroll / pinch → zoom in and out
• ⊹ Reset View → fit all nodes back into viewport
• ↺ Reset Structure → snap nodes back to original AI-generated positions

• Click ⊞ Map in the top-right to toggle the sidebar
• The sidebar shows a live top-down flowchart of the entire current graph
• Root node at the top; concept, detail, and deep nodes spread downward
• Color-coded by node type (gold = root, cyan = concept, green = detail, purple = deep, white = learned)
• Click any node in the sidebar to focus it in the main graph and open its panel
• The flowchart scrolls both vertically and horizontally for large maps

Click ⬢ Dive Deeper on any non-root node (panel or portal) to generate an AI sub-tree for that specific concept. The breadcrumb trail in the top bar shows your dive path and lets you navigate back to any level.

• Toggle Auto-save in the top bar (on by default — saves 5 seconds after any change)
• Click ✦ Save Map to save immediately
• Open the hamburger menu (☰) on the home screen to browse, search, and load saved maps

EverNodes/
├── app.py                  # Flask backend — Groq API, caching, JSON validation
├── requirements.txt
├── .env                    # Your GROQ_API_KEY (not committed)
├── .gitignore
├── README.md
├── static/
│   ├── script.js           # All frontend logic — graph, portal, structure map, dives
│   └── style.css           # Full UI design system (dark cosmic theme)
└── templates/
    └── index.html          # Single-page app shell

{
  "goal":  "Machine Learning",
  "prior": "Basic Python, some statistics",
  "level": "intermediate"
}

{
  "topic":  "Gradient Descent",
  "parent": "Optimization",
  "level":  "intermediate",
  "detail": "Existing node detail text for context…"
}

EverNodes uses a two-layer caching system to minimize Groq API usage:

• Exact match: same topic + level returns instantly
• Fuzzy match (new): checks substring containment, word-set overlap (≥ 75%), and sequence similarity (≥ 82%) — so "ML", "machine learning", and "Machine Learning basics" all resolve to the same cached map
• Response includes matched_topic so the UI can inform you which cached entry was used

• Stores up to 20 topic/level pairs in the browser session
• Bypasses the server entirely for repeated lookups within the same browser tab

The backend validates all inputs before sending to Groq:

• Rejects topics shorter than 3 characters
• Rejects pure numeric or symbol input
• Rejects repeated-character sequences ("aaaaaaa")
• Detects and rejects consonant-only gibberish
• All JSON from the LLM is sanitized, repaired (trailing commas, unclosed brackets, unescaped quotes, smart quotes), and validated before returning to the client

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Commit your changes: git commit -m 'Add some feature'
4. Push to the branch: git push origin feature/your-feature
5. Open a Pull Request

Bug reports and suggestions are welcome via GitHub Issues.

This project is licensed under the terms in the LICENSE file.

• Groq — blazing-fast LLM inference
• Meta Llama 4 — the model powering all AI generation
• vis.js — network graph rendering
• Google Fonts — Syne, DM Sans, JetBrains Mono

Built with ✦ and curiosity.