[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80946":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":11,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":13,"stars7d":13,"stars30d":13,"stars90d":13,"forks30d":13,"starsTrendScore":13,"compositeScore":14,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":15,"fork":15,"defaultBranch":16,"hasWiki":17,"hasPages":15,"topics":18,"createdAt":9,"pushedAt":9,"updatedAt":19,"readmeContent":20,"aiSummary":21,"trendingCount":13,"starSnapshotCount":13,"syncStatus":22,"lastSyncTime":23,"discoverSource":24},80946,"MICode-Tutor","Sqqlcyy\u002FMICode-Tutor","Sqqlcyy","The official codebase of Google Gemma4 Good Hackathon Project——MICode Tutor",null,"Python",32,1,0,0.9,false,"main",true,[],"2026-06-12 02:04:08","# MICode Tutor\n\n**Offline Codebase Memory for Gemma 4**\n\nMICode Tutor compiles a repository into a portable `.mic` Machine-Interpretable Code memory file, then lets local Gemma 4 read that memory for repo Q&A, learning, test generation, and safe patch planning.\n\n> AI coding tutors should work without the cloud.\n\n---\n\n## Why MICode Tutor?\n\nModern AI coding assistants are powerful, but they often assume:\n\n- reliable cloud access,\n- paid API keys,\n- and permission to upload private code.\n\nThat leaves many students, independent builders, open-source maintainers, and privacy-sensitive teams behind.\n\nMICode Tutor takes a local-first approach:\n\n```text\nrepo\n→ .mic memory artifact\n→ symbol-aware retrieval\n→ auditable context pack\n→ local Gemma 4 via Ollama or llama.cpp\n```\n\nGemma does **not** blindly inspect the entire repository. MICSDK prepares a compact evidence pack first. Gemma reasons over that evidence.\n\n---\n\n## What MICode Tutor Does\n\nMICode Tutor is not a prompt wrapper that dumps source code into an LLM.\n\nWhen you run:\n\n```bash\nmic compile examples\u002Fedu_auth_service --out edu_auth_service.mic\n```\n\nMICSDK builds a `.mic` memory file containing:\n\n- file cards,\n- symbol cards,\n- classes, functions, and methods,\n- imports and exports,\n- line ranges,\n- test references,\n- call relations,\n- evidence snippets,\n- lightweight state tokens,\n- repo capabilities,\n- and agent recipes for Q&A, testing, and patch planning.\n\nYou can inspect it locally:\n\n```bash\nmic inspect edu_auth_service.mic\n```\n\nYou can search it without calling any model:\n\n```bash\nmic search \"where is JWT authentication verified?\" --memory edu_auth_service.mic\n```\n\nYou can see exactly what Gemma will receive:\n\n```bash\nmic pack \"where is JWT verified?\" \\\n  --memory edu_auth_service.mic \\\n  --budget 500 \\\n  --top-k 3 \\\n  --out context_jwt.md\n```\n\nThen you can ask local Gemma:\n\n```bash\nmic ask \"where is JWT verified?\" \\\n  --memory edu_auth_service.mic \\\n  --backend ollama \\\n  --model gemma4:latest\n```\n\n---\n\n## Demo Scenario\n\nThe included demo repository is an educational Python authentication service:\n\n```text\nexamples\u002Fedu_auth_service\u002F\n  app\u002F\n    main.py\n    config.py\n    auth\u002F\n      token.py\n      password.py\n      routes.py\n    middleware\u002F\n      auth_required.py\n    security\u002F\n      rate_limit.py\n    db\u002F\n      users.py\n  tests\u002F\n    test_auth.py\n    test_config.py\n```\n\nThe demo supports questions such as:\n\n```bash\nmic ask \"where is JWT verified?\" --memory edu_auth_service.mic --backend ollama --model gemma4:latest\n\nmic ask \"explain this repo to a beginner. Give a 5-step learning path.\" \\\n  --memory edu_auth_service.mic \\\n  --backend ollama \\\n  --model gemma4:latest\n\nmic test \"write a pytest for expired refresh tokens.\" \\\n  --memory edu_auth_service.mic \\\n  --backend ollama \\\n  --model gemma4:latest\n\nmic plan \"add Redis-based rate limiting to login. What files change and what tests are needed?\" \\\n  --memory edu_auth_service.mic \\\n  --backend ollama \\\n  --model gemma4:latest\n```\n\n---\n\n## Quickstart\n\n### 1. Install\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002F\u003Cyour-org>\u002Fmicode-tutor.git\ncd micode-tutor\npip install -e .\n```\n\n### 2. Run the built-in demo\n\n```bash\nmic demo\n```\n\n### 3. Compile the demo repo\n\n```bash\nmic compile examples\u002Fedu_auth_service --out edu_auth_service.mic\n```\n\n### 4. Inspect the `.mic` memory\n\n```bash\nmic inspect edu_auth_service.mic\n```\n\nExpected output includes repository metadata such as:\n\n```text\nFiles: 17\nSymbols: 355\nRelations: 46\nState tokens: 372\n```\n\n### 5. Search locally without an LLM\n\n```bash\nmic search \"where is JWT authentication verified?\" --memory edu_auth_service.mic\n```\n\n### 6. Ask local Gemma 4\n\n```bash\nmic ask \"where is JWT verified?\" \\\n  --memory edu_auth_service.mic \\\n  --backend ollama \\\n  --model gemma4:latest\n```\n\n---\n\n## Local Model Backends\n\nMICode Tutor supports multiple local Gemma runtimes.\n\n### Ollama\n\nOllama is the easiest way to run Gemma locally.\n\n```bash\nmic ask \"where is JWT verified?\" \\\n  --memory edu_auth_service.mic \\\n  --backend ollama \\\n  --model gemma4:latest\n```\n\nIf you already have a local GGUF model, MICode Tutor can create an Ollama model from it:\n\n```bash\nmic backend ollama-start\n\nmic backend ollama-create \\\n  --gguf \u002Fpath\u002Fto\u002Fgemma4-e4b-q4_k_m.gguf \\\n  --name gemma4:latest\n\nmic backend ollama-test --model gemma4:latest\n```\n(Certainly,we support llama.cpp backend)\n\nThis supports offline or USB-delivered model artifacts.\n\n### llama.cpp\n\nllama.cpp is a lower-level GGUF inference runtime suitable for resource-constrained environments.\n\n\n### Guided Runtime Setup\n\nMICode Tutor includes a guided backend setup layer:\n\n```bash\nmic backend install llamacpp\nmic backend llamacpp-start --gguf \u002Fpath\u002Fto\u002Fmodel.gguf\nmic backend llamacpp-test\n\nThen:\n\n```bash\nmic ask \"where is JWT verified?\" \\\n  --memory edu_auth_service.mic \\\n  --backend llamacpp \\\n  --model gemma4\n```\n\n### Backend Doctor\n\nCheck local runtime status:\n\n```bash\nmic backend doctor\n```\n\nThis reports GPU availability, Ollama status, llama.cpp build status, and local GGUF model files.\n\n---\n\n## Why Both Ollama and llama.cpp?\n\nThey serve different deployment needs.\n\n| Backend | Best for | Why |\n|---|---|---|\n| Ollama | teachers, students, developers | easiest local deployment and model management |\n| llama.cpp | low-resource machines, CPU\u002FGPU edge deployment | direct GGUF runtime with low-level control |\n| GGUF | offline model distribution | can be delivered by USB\u002Flocal disk\u002Fclassroom server |\n\nMICode Tutor uses the same `.mic` memory and context pack with either backend.\n\n---\n\n## Safety and Trust\n\nMICode Tutor is designed as a **human-in-the-loop** coding tutor.\n\nIt does not automatically mutate your repository.\n\nSafety features:\n\n- local `.mic` memory file,\n- no cloud API required,\n- no code upload,\n- inspectable memory,\n- auditable context packs,\n- evidence citations with file paths and line ranges,\n- patch planning instead of automatic edits,\n- test generation for human review.\n\nExample:\n\n```bash\nmic pack \"where is JWT verified?\" \\\n  --memory edu_auth_service.mic \\\n  --out context_jwt.md\n```\n\nThis shows exactly what context Gemma receives.\n\n---\n\n## Commands\n\n```bash\n# Compile repo into .mic memory\nmic compile examples\u002Fedu_auth_service --out edu_auth_service.mic\n\n# Inspect memory\nmic inspect edu_auth_service.mic\n\n# Local search without LLM\nmic search \"where is JWT authentication verified?\" --memory edu_auth_service.mic\n\n# Build an auditable context pack\nmic pack \"write tests for expired refresh tokens\" --memory edu_auth_service.mic\n\n# Ask local Gemma 4\nmic ask \"explain the auth flow\" --memory edu_auth_service.mic --backend ollama --model gemma4:latest\n\n# Generate tests\nmic test \"write tests for expired refresh tokens\" --memory edu_auth_service.mic --backend ollama --model gemma4:latest\n\n# Generate a safe patch plan\nmic plan \"add Redis-based rate limiting to login\" --memory edu_auth_service.mic --backend ollama --model gemma4:latest\n\n# Backend setup\nmic backend doctor\nmic backend ollama-start\nmic backend ollama-create --gguf \u002Fpath\u002Fto\u002Fmodel.gguf --name gemma4:latest\nmic backend llamacpp-build\nmic backend llamacpp-start --gguf \u002Fpath\u002Fto\u002Fmodel.gguf\n```\n\n---\n\n## Architecture\n\n```text\n┌────────────────────┐\n│ Source Repository  │\n└─────────┬──────────┘\n          │\n          ▼\n┌────────────────────┐\n│ MIC Compiler       │\n│ files, symbols,    │\n│ relations, tests   │\n└─────────┬──────────┘\n          │\n          ▼\n┌────────────────────┐\n│ .mic Memory File   │\n│ portable, local,   │\n│ inspectable        │\n└─────────┬──────────┘\n          │\n          ▼\n┌────────────────────┐\n│ Symbol-Aware       │\n│ Retrieval          │\n└─────────┬──────────┘\n          │\n          ▼\n┌────────────────────┐\n│ Context Pack       │\n│ evidence + lines   │\n└─────────┬──────────┘\n          │\n          ▼\n┌────────────────────┐\n│ Local Gemma 4      │\n│ Ollama \u002F llama.cpp │\n└────────────────────┘\n```\n\n---\n\n## Digital Equity Use Case\n\nMICode Tutor is designed for low-connectivity and privacy-sensitive environments.\n\nA realistic deployment is:\n\n```text\none local classroom server\n+ quantized Gemma 4 model\n+ Ollama or llama.cpp\n+ shared .mic course repositories\n+ many students using lightweight terminals\n```\n\nStudents do not need cloud API keys.  \nPrivate code does not leave the machine.  \nTeachers can distribute `.mic` memory files with course repositories.\n\n---\n\n## Current Scope\n\nMICode Tutor v0.1 is a research alpha.\n\nIt is not a replacement for Cursor, Claude Code, or full autonomous coding agents.\n\nIt demonstrates a focused capability:\n\n> Compile a repository into portable machine memory so local Gemma 4 can explain, teach, test, and plan safely offline.\n\n---\n\n## Limitations\n\n- Python-focused parser in v0.1.\n- Retrieval is lightweight and symbolic-textual, not learned neural retrieval.\n- Patch generation is proposal-only and does not apply edits.\n- Local inference speed depends on model size, quantization, runtime, and hardware.\n- Offline model setup still requires a local GGUF or preinstalled runtime.\n\n---\n\n## Roadmap\n\n- richer multi-language parsers,\n- MCP server integration,\n- LangChain \u002F LlamaIndex retriever adapters,\n- GitHub Action to generate `.mic` on pull requests,\n- offline classroom bundle,\n- improved benchmark suite,\n- learned neural MIC compiler research,\n- GUI \u002F lightweight web UI,\n- safer patch application with sandboxed test execution.\n\n---\n\n## Project Philosophy\n\nCodebases should be compiled into machine-interpretable memory before agents reason over them.\n\nMICode Tutor is the first small step toward that idea.\n\n---\n\n## License\n\nMIT License.\n\n---\n\n## Citation\n\nIf you use MICode Tutor, please cite:\n\n```text\nMICode Tutor: Offline Codebase Memory for Gemma 4.\nBuilt for the Google DeepMind Gemma 4 Good Hackathon, 2026.\n```# MICode-Tutor\n\n## Research Lineage: Machine-Interpretable Information\n\nMICode Tutor is an applied engineering step toward a broader research idea: **Machine-Interpretable Information (MII)**.\n\nThe core hypothesis is that documents and codebases should not be treated as disposable prompt text. They should be compiled into persistent, machine-interpretable memory artifacts before AI agents reason over them.\n\nFor this hackathon prototype, `.mic` is an inspectable symbolic-textual code memory artifact. It does not require hidden `.mii` neural states. Future versions may explore richer neural protocol states, but v0.1 is intentionally transparent, local, and auditable.\n\nSee [docs\u002FMII_RELATION.md](docs\u002FMII_RELATION.md) for more.\n","MICode Tutor 是一个将代码库编译为可移植的`.mic`文件的工具，使本地Gemma 4能够进行代码问答、学习、测试生成和安全补丁规划。其核心功能包括符号感知检索、紧凑证据包准备以及无需云访问即可工作的本地优先设计。技术特点上，通过MICSDK构建的`.mic`内存文件包含了文件卡片、符号卡片、类与方法、导入导出信息等丰富内容，并支持不调用模型直接搜索。适合于学生、独立开发者、开源维护者及注重隐私的团队使用，在没有稳定云服务接入或需要保护私有代码不外泄的情况下尤为适用。",2,"2026-06-11 04:02:58","CREATED_QUERY"]