Powerer Pointerer Silice Instructor

Your Codebase, Narrated by AI.

---

Instructor is not just a code reviewer; it's a storytelling engine for software. It takes any source file, dissects it using advanced Abstract Syntax Trees (AST), feeds it to a local AI Senior Engineer, and produces a stunning, interactive presentation that walks you through the logic, intent, and brilliance of your code.

Whether you're onboarding new devs, reviewing complex legacy code, or just documenting your masterpiece, Instructor turns static text into a dynamic masterclass.

🚀 Why Powerer Pointerer Silice Instructor?

• 🧠 Senior Engineer/Teacher Persona: The AI doesn't just explain what the code does; it explains why it matters, using high-level analogies and professional insights.
• 🔒 100% Local & Private: Powered by Ollama, your code never leaves your machine. No API keys, no data leaks.
• ⚡ Precision Parsing: Uses ast-grep to structurally understand your code (functions, classes, methods) rather than dumb regex splitting.
• ✨ Beautiful Output: Generates a Quarto (Reveal.js) presentation with side-by-side code and explanation views, auto-advancing slides, and syntax highlighting.

🛠️ How It Works

1. Scan: ast-grep parses your source file to identify logical blocks (functions, classes) based on the language grammar.
2. Analyze: Each block is sent to a local LLM (via Ollama) with a "Senior Engineer" system prompt to generate a pedagogical explanation.
3. Render: The results are woven into a Quarto markdown file (.qmd).
4. Present: Quarto compiles this into a standalone HTML5 presentation.

⚡ Support

Made with ❤️ and ☕ by the Plantacerium

⭐ Star us on GitHub if the script is useful to You! ⭐

📦 Requirements

• Python 3.9+
• Ollama (Running locally with a model like qwen2.5-coder or llama3)
• ast-grep (sg command line tool)
• Jupyter (Jupyter Notebooks)
• Quarto (CLI for rendering presentations)

🏁 Quick Start

1. Clone the Repository

   git clone https://github.com/plantacerium/PowererPointererSilice.git
   cd PowererPointererSilice

2. Install Python Dependencies

   pip install requests

3. Ensure External Tools are Ready

   • Start Ollama: ollama serve (and make sure you've pulled your model, e.g., ollama pull qwen3:8b)
   • Check sg and quarto are in your PATH.

4. Run Instructor

   # Analyze a Python file
   python instructor.py path/to/your/code.py

5. View the Magic Instructor generates a .qmd file. Render it using Quarto:

   quarto render ai_ast_grep_review.qmd --to revealjs

   Open the generated HTML file in your browser and enjoy the show! 🍿

🌍 Supported Languages

Instructor uses ast-grep's powerful pattern matching. Out of the box, it supports:

• 🐍 Python (.py)
• 📜 JavaScript (.js)
• 📘 TypeScript (.ts)
• 🐹 Go (.go)
• 🦀 Rust (.rs)
• ☕ Java (.java)
• 🇨 C (.c)

Adding more languages is as easy as adding a single line to the LANGUAGE_MAP in instructor.py!

🎨 Customization

Open instructor.py to tweak:

• OLLAMA_MODEL: Change the AI brain (e.g., mistral, codellama, deepseek-coder).
• presentation settings: Adjust slide timing, themes, or transition speeds in the generate_qmd function.

🤝 Contributing

We want to make code literacy universal. If you have ideas for better prompts, cooler Quarto themes, or more language support:

1. Fork it.
2. Branch it.
3. Pull Request it.

⚡ Support

Made with ❤️ and ☕ by the Plantacerium

⭐ Star us on GitHub if the script is useful to You! ⭐

📄 License

MIT. Let's build something awesome.