norbok 0.1.0__tar.gz

norbok-0.1.0/.gitignore

@@ -0,0 +1 @@
+.aider*

norbok-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: norbok
+Version: 0.1.0
+Summary: A terminal-based AI Python tutor that teaches coding through local AI projects
+Requires-Python: >=3.10
+Requires-Dist: ollama
+Requires-Dist: psutil
+Requires-Dist: rich

norbok-0.1.0/SPEC.md

@@ -0,0 +1,92 @@
+# Norbok — AI Python Tutor
+
+## What it is
+A terminal-based interactive Python tutor that teaches coding through 
+AI-focused projects. Runs entirely locally, no cloud, no browser, 
+just a terminal. The student learns Python by building real AI projects 
+from day one using Ollama and local models.
+
+## How it works
+User runs `python norbok.py` (eventually `norbok` after pip install).
+App starts, checks Ollama is running, launches a menu.
+User picks a project, works through milestones one at a time,
+and can ask Norbok for help at any point during any milestone.
+
+## Teaching philosophy
+Project-first and AI-first. Every project uses AI in some way even 
+the beginner ones. Concepts are introduced exactly when the student 
+needs them, not as prerequisites. A total beginner builds a working 
+AI chatbot on day one and feels like a genius immediately.
+
+## Models
+- qwen2.5-coder:7b — Norbok's brain, handles all teaching, 
+  explanations and coaching throughout the app
+- dolphin-llama3 — used by the student in their projects, 
+  not installed by Norbok. Students pull it themselves as 
+  part of the first project milestone. Recommended for all 
+  creative and personality-driven projects.
+- Qwen — also taught to students for technical projects 
+  like the AI code reviewer
+
+## Tech stack
+- Python
+- Rich (terminal UI and output)
+- Ollama (local AI runner)
+- qwen2.5-coder:7b (Norbok's brain)
+
+## File structure
+- norbok.py          — entry point, launches the app
+- ollama_manager.py  — Ollama connection and model management
+- chat.py            — chat loop and Norbok message handling
+- ui.py              — all Rich terminal display and menus
+- projects.py        — all project and milestone content
+- hardware.py        — hardware detection, model recommendation
+- SPEC.md            — this file
+
+## Core features
+- Checks Ollama is running on launch, guides user if not
+- Project selection menu organized by difficulty level
+- Milestone walkthrough with Norbok coaching at every step
+- Free chat mode to ask Norbok anything
+- Student asks questions mid-milestone and gets instant help
+- Project-first AI curriculum, beginner to advanced
+
+## Curriculum structure
+Three difficulty levels, all projects are AI focused.
+Placeholder projects will be filled out over time.
+
+BEGINNER:
+1. AI Chatbot with Custom Personality (fully built, first project)
+   - teaches: Ollama, Dolphin, system prompts, while loops, Rich
+2. AI Magic 8 Ball (placeholder)
+3. AI Joke Generator (placeholder)
+4. AI Story Starter (placeholder)
+5. AI Word Game (placeholder)
+
+INTERMEDIATE:
+6. AI Quiz Generator (placeholder)
+7. AI Dungeon Game (placeholder)
+8. AI Movie Recommender (placeholder)
+9. AI Code Reviewer with Qwen (placeholder)
+
+ADVANCED:
+10. AI Web Scraper with Summaries (placeholder)
+11. AI Flask Chatbot (placeholder)
+12. AI Discord Bot (placeholder)
+13. AI Flask Dashboard (placeholder)
+
+## First project detail
+Name: AI Chatbot with Custom Personality
+The student installs Dolphin, writes a script that talks to it,
+adds a while loop, gives it a personality via system prompt,
+lets the user pick from a personality list, then styles it with Rich.
+By milestone 2 they have a working AI chatbot in 8 lines of Python.
+
+## Distribution (planned)
+pip install norbok
+
+## What Norbok is NOT
+- Not a web app
+- Not a cloud service  
+- Not a censored corporate tutor
+- Not a drill-first boring curriculum

norbok-0.1.0/norbok/__main__.py

@@ -0,0 +1,7 @@
+from . import ui
+
+def main():
+    ui.main()
+
+if __name__ == "__main__":
+    main()

norbok-0.1.0/norbok/chat.py

@@ -0,0 +1,84 @@
+import ollama
+from rich.console import Console
+from rich.prompt import Prompt
+from rich.panel import Panel
+
+console = Console()
+
+
+def stream_teacher_response(user_input):
+    """Stream the model reply token‑by‑token to eliminate perceived delay."""
+    messages = [
+        {
+            "role": "system",
+            "content": (
+                "you are a friendly, considerate web development teacher. "
+                "you do simple analogies and then explain it technically. "
+                "talk like you are teaching a total beginner, step by step guides. "
+                "start with making a flask app webpage."
+            )
+        },
+        {
+            "role": "user",
+            "content": user_input,
+        },
+    ]
+    options = {
+        "num_predict": 256,
+        "temperature": 0.7,
+    }
+
+    def _stream():
+        return ollama.chat(
+            model='qwen2.5-coder:7b',
+            messages=messages,
+            options=options,
+            stream=True,
+        )
+
+    try:
+        stream = _stream()
+    except Exception as e:
+        if 'model' in str(e).lower() and 'not found' in str(e).lower():
+            console.print("[yellow]Model 'qwen2.5-coder:7b' not found. Pulling...[/]")
+            try:
+                ollama.pull('qwen2.5-coder:7b')
+                console.print("[green]Pull complete. Retrying request...[/]")
+                stream = _stream()
+            except Exception as pull_err:
+                raise RuntimeError(f"Pull failed: {pull_err}")
+        else:
+            raise
+
+    console.print("[bold green]Teacher:[/bold green]")
+    for chunk in stream:
+        token = chunk['message']['content']
+        console.print(token, end='', style="green", highlight=False)
+    console.print()   # newline after the stream finishes
+
+
+def run_free_chat():
+    """Enter the free‑chat loop. Returns when the user types 'exit'/'quit'."""
+    console.rule("[bold cyan]Free Chat with Norbok[/bold cyan]")
+    console.print("Type your message ('exit' or 'quit' to return to main menu)")
+    while True:
+        try:
+            user_input = Prompt.ask("[bold blue]You[/bold blue]")
+            if user_input.strip().lower() in ("exit", "quit"):
+                console.print("[yellow]Returning to main menu...[/yellow]")
+                break
+
+            # display user message
+            user_panel = Panel.fit(user_input, title="You", border_style="blue")
+            console.print(user_panel)
+
+            stream_teacher_response(user_input)
+
+        except KeyboardInterrupt:
+            console.print("\n[yellow]Interrupted. Returning to menu.[/yellow]")
+            break
+
+        except Exception as e:
+            error_msg = f"Error: {e}. Ensure Ollama is running and model is pulled."
+            console.print(Panel.fit(error_msg, title="Error", border_style="red"))
+            # loop continues so the user can type 'exit' or try another message

norbok-0.1.0/norbok/hardware.py

@@ -0,0 +1,15 @@
+def get_recommended_model():
+    try:
+        import psutil
+        mem = psutil.virtual_memory()
+        ram_gb = mem.total / (1024 ** 3)
+    except ImportError:
+        # If psutil isn't available, assume enough RAM for the default model
+        ram_gb = 32
+
+    if ram_gb >= 16:
+        return "qwen2.5-coder:7b"
+    elif ram_gb >= 8:
+        return "qwen2.5-coder:1.5b"
+    else:
+        return "qwen2.5-coder:0.5b"

norbok-0.1.0/norbok/norbok.py

@@ -0,0 +1,4 @@
+from . import ui
+
+if __name__ == '__main__':
+    ui.main()

norbok-0.1.0/norbok/ollama_manager.py

@@ -0,0 +1,162 @@
+import subprocess
+import time
+import sys
+import shutil
+import ollama
+from rich.console import Console
+
+console = Console()
+
+# Will be set to True once the Ollama API becomes reachable
+ollama_available = False
+
+
+def start_ollama():
+    global ollama_available
+
+    # 1) Check if server is already running
+    try:
+        ollama.list()
+        ollama_available = True
+        console.print("[green]Ollama server already running.[/]")
+        # Preload model to avoid first-query lag
+        preload_model()
+        return
+    except Exception:
+        # Server not reachable – try to start it
+        console.print("[yellow]Ollama server not running, trying to start...[/]")
+
+    # 2) Make sure the ollama command is available
+    if shutil.which("ollama") is None:
+        console.print("[red]Could not find 'ollama' command. Is Ollama installed and in your PATH?[/]")
+        return
+
+    # 3) Launch the server in the background, capturing stderr
+    proc = subprocess.Popen(
+        ["ollama", "serve"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,   # capture errors so we can show them
+    )
+    # Give it a moment to start, then check if it terminated immediately
+    time.sleep(1)
+    if proc.poll() is not None:
+        # The process ended very quickly – probably an error
+        try:
+            # Read remaining output so we can show the reason
+            _, stderr = proc.communicate(timeout=2)
+            err_msg = stderr.decode().strip()
+        except Exception:
+            err_msg = "(could not capture stderr)"
+
+        # "address already in use" means Ollama is already running – treat as success
+        if "address already in use" in err_msg.lower():
+            console.print("[yellow]Port 11434 is already in use – Ollama may already be running.[/]")
+            try:
+                ollama.list()
+            except Exception:
+                console.print("[red]Could not connect to running Ollama server. Please check manually.[/]")
+                return
+            # Connection succeeded – Ollama is definitely running
+            ollama_available = True
+            console.print("[green]Ollama server is already running (port in use).[/]")
+            preload_model()
+            return
+        else:
+            console.print(f"[red]Ollama server exited immediately. Output: {err_msg}[/]")
+            console.print("[yellow]Try running 'ollama serve' manually in another terminal and then restart Norbok.[/]")
+            return
+
+    # 4) Wait up to 30 seconds for the server to become ready
+    ready = False
+    for attempt in range(60):          # 60 * 0.5 s = 30 s
+        time.sleep(0.5)
+        try:
+            ollama.list()
+            ready = True
+            break
+        except Exception:
+            if attempt == 0:
+                console.print("[cyan]Waiting for Ollama server to start...[/]")
+
+    if ready:
+        ollama_available = True
+        console.print("[green]Ollama server started.[/]")
+        preload_model()
+    else:
+        console.print("[red]Warning: Ollama server could not be started within timeout.[/]")
+        # Attempt to clean up the background process
+        try:
+            proc.terminate()
+        except Exception:
+            pass
+        return
+
+
+def preload_model():
+    """Try to load the model into memory now to speed up the first question."""
+    try:
+        # Check if model exists locally; if not, skip preload to avoid pull delay
+        ollama.show('qwen2.5-coder:7b')
+    except Exception:
+        console.print("[yellow]Model 'qwen2.5-coder:7b' not found locally, first question will trigger pull/load.[/]")
+        return
+
+    console.print("[cyan]Warming up the AI model (this may take a few seconds)...[/]")
+    try:
+        ollama.chat(
+            model='qwen2.5-coder:7b',
+            messages=[{"role": "system", "content": "You are an AI assistant."}],
+            options={"num_predict": 1, "temperature": 0.0},
+            keep_alive=-1,          # keep model loaded indefinitely
+            stream=False,
+        )
+        console.print("[green]Model ready.[/]")
+    except Exception as e:
+        console.print(f"[yellow]Warm-up request failed, first query will load the model: {e}[/]")
+
+
+def chat_with_model(user_input):
+    messages = [
+        {
+            "role": "system",
+            "content": (
+                "you are a friendly, considerate web development teacher. "
+                "you do simple analogies and then explain it technically. "
+                "talk like you are teaching a total beginner, step by step guides. "
+                "start with making a flask app webpage."
+            )
+        },
+        {
+            "role": "user",
+            "content": user_input,
+        },
+    ]
+    options = {
+        "num_predict": 256,
+        "temperature": 0.7,
+    }
+
+    try:
+        response = ollama.chat(
+            model='qwen2.5-coder:7b',
+            messages=messages,
+            options=options,
+        )
+        return response['message']['content']
+    except Exception as e:
+        # If the model is missing, pull it and retry once
+        if 'model' in str(e).lower() and 'not found' in str(e).lower():
+            console.print("[yellow]Model 'qwen2.5-coder:7b' not found. Pulling...[/]")
+            try:
+                ollama.pull('qwen2.5-coder:7b')
+                console.print("[green]Pull complete. Retrying request...[/]")
+                response = ollama.chat(
+                    model='qwen2.5-coder:7b',
+                    messages=messages,
+                    options=options,
+                )
+                return response['message']['content']
+            except Exception as pull_err:
+                raise RuntimeError(f"Pull failed: {pull_err}")
+        else:
+            raise

norbok-0.1.0/norbok/projects.py

@@ -0,0 +1,112 @@
+from rich.console import Console
+from rich.prompt import Prompt
+from rich.panel import Panel
+from . import chat
+
+console = Console()
+
+
+BEGINNER_PROJECTS = [
+    {
+        "name": "Hello World Flask App",
+        "description": "Create your first Flask web application.",
+        "milestones": [
+            "Install Flask using pip (pip install flask).",
+            "Create a new Python file (app.py) and write a route that returns 'Hello, World!'.",
+            "Run the app and visit http://127.0.0.1:5000 in your browser.",
+            "Add a second route that displays your name.",
+        ]
+    },
+    {
+        "name": "Personal Blog",
+        "description": "Build a simple blog where you can create and view posts.",
+        "milestones": [
+            "Set up Flask project structure: create app.py, /templates and /static folders.",
+            "Create an index page template that lists blog posts (hardcoded).",
+            "Add a page with a form for creating new posts.",
+            "Store new posts in a global list and display them on the index page.",
+            "Add the ability to delete a post.",
+        ]
+    },
+    {
+        "name": "To-Do List App",
+        "description": "A classic to-do web app to learn CRUD operations.",
+        "milestones": [
+            "Create a Flask app with a route that renders an HTML list of tasks.",
+            "Use a Python list to keep tasks in memory.",
+            "Add a form on the page to add new tasks.",
+            "Add a delete link to remove tasks.",
+            "Bonus: mark tasks as completed.",
+        ]
+    },
+]
+
+
+def walkthrough_milestones(project):
+    """Step through each milestone of a selected project."""
+    name = project["name"]
+    description = project["description"]
+    milestones = project["milestones"]
+
+    console.rule(f"[bold cyan]{name}[/bold cyan]")
+    console.print(description)
+
+    for idx, milestone in enumerate(milestones, 1):
+        console.rule(f"[bold yellow]Milestone {idx}/{len(milestones)}[/bold yellow]")
+        console.print(f"[bold]{milestone}[/bold]")
+        while True:
+            user_input = Prompt.ask(
+                "[bold]You[/bold] (press Enter to mark as done, ask a question, or 'quit' to return)"
+            ).strip()
+            if user_input.lower() == 'quit':
+                return   # stop walking through milestones
+            if user_input == '':
+                break   # move to next milestone
+            # treat the input as a question about this milestone
+            combined = f"Current milestone: {milestone}\nUser question: {user_input}"
+            try:
+                chat.stream_teacher_response(combined)
+            except KeyboardInterrupt:
+                console.print("\n[yellow]Interrupted.[/yellow]")
+                break   # go to the next milestone after an interrupt
+            except Exception as e:
+                console.print(Panel.fit(str(e), title="Error", border_style="red"))
+
+    console.print("[green]All milestones completed! Returning to project selection.[/green]")
+
+
+def start_project():
+    """Let user choose a beginner project and walk through its milestones."""
+    while True:
+        console.rule("[bold cyan]Start a Project[/bold cyan]")
+        for idx, proj in enumerate(BEGINNER_PROJECTS, 1):
+            console.print(f"{idx}. [bold]{proj['name']}[/bold] - {proj['description']}")
+        console.print("Type [bold]0[/bold] or [bold]back[/bold] to return to the main menu.")
+
+        choice = Prompt.ask("[bold]Select a project[/bold]").strip().lower()
+        if choice in ("0", "back"):
+            return
+
+        # try matching by number
+        try:
+            idx = int(choice)
+            if 1 <= idx <= len(BEGINNER_PROJECTS):
+                selected = BEGINNER_PROJECTS[idx - 1]
+            else:
+                console.print("[red]Invalid project number.[/red]")
+                continue
+        except ValueError:
+            # match by name (case insensitive)
+            matched = None
+            for proj in BEGINNER_PROJECTS:
+                if proj["name"].lower() == choice:
+                    matched = proj
+                    break
+            if matched:
+                selected = matched
+            else:
+                console.print("[red]Project not found. Please try again.[/red]")
+                continue
+
+        walkthrough_milestones(selected)
+        # after finishing milestones (or returning) the outer loop shows the project list again

norbok-0.1.0/norbok/ui.py

@@ -0,0 +1,52 @@
+import sys
+import time
+from rich.console import Console
+from rich.prompt import Prompt
+from rich.panel import Panel
+from . import ollama_manager
+from . import chat
+from . import projects
+
+console = Console()
+
+
+def main():
+    # Show Norbok ASCII logo on startup
+    logo = (
+        "███╗   ██╗ ██████╗ ██████╗ ██████╗  ██████╗ ██╗  ██╗\n"
+        "████╗  ██║██╔═══██╗██╔══██╗██╔══██╗██╔═══██╗██║ ██╔╝\n"
+        "██╔██╗ ██║██║   ██║██████╔╝██████╔╝██║   ██║█████╔╝ \n"
+        "██║╚██╗██║██║   ██║██╔══██╗██╔══██╗██║   ██║██╔═██╗ \n"
+        "██║ ╚████║╚██████╔╝██║  ██║██████╔╝╚██████╔╝██║  ██╗\n"
+        "╚═╝  ╚═══╝ ╚═════╝ ╚═╝  ╚═╝╚═════╝  ╚═════╝ ╚═╝  ╚═╝\n"
+        "             AI WebDev Tutor"
+    )
+    logo_panel = Panel(logo, title="Welcome to Norbok", border_style="bold cyan")
+    console.print(logo_panel)
+
+    console.print("[bold cyan]AI WebDev Tutor (terminal)[/bold cyan]")
+    console.print("Ask me anything about starting your Flask app... (type 'exit' to quit)")
+    ollama_manager.start_ollama()
+
+    if not ollama_manager.ollama_available:
+        console.print("[red]Ollama server is not available. Exiting.[/red]")
+        sys.exit(1)
+
+    # Main menu loop
+    while True:
+        console.rule("[bold cyan]Main Menu[/bold cyan]")
+        console.print("1. Start a project")
+        console.print("2. Free chat with Norbok")
+        console.print("3. Quit")
+        choice = Prompt.ask("[bold]Choose an option[/bold]").strip().lower()
+
+        if choice in ("1", "start a project"):
+            projects.start_project()
+        elif choice in ("2", "free chat with norbok", "chat"):
+            chat.run_free_chat()
+        elif choice in ("3", "quit", "exit"):
+            console.print("[bold yellow]Goodbye![/bold yellow]")
+            sys.exit(0)
+        else:
+            console.print("[red]Invalid option, please try again.[/red]")
+            time.sleep(1)

norbok-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "norbok"
+version = "0.1.0"
+description = "A terminal-based AI Python tutor that teaches coding through local AI projects"
+requires-python = ">=3.10"
+dependencies = [
+    "ollama",
+    "rich",
+    "psutil",
+]
+
+[project.scripts]
+norbok = "norbok.__main__:main"
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "venv/",
+    "venv/**",
+    "**/__pycache__/",
+]
+
+# Author information placeholder – fill in when ready
+# [project.authors]
+# name = "Your Name"
+# email = "you@example.com"