{"id":50455923,"url":"https://github.com/lhzn-io/kanoa","last_synced_at":"2026-06-01T02:31:33.017Z","repository":{"id":325512976,"uuid":"1101378919","full_name":"lhzn-io/kanoa","owner":"lhzn-io","description":"AI-powered interpretation of data science outputs with multi-backend support (Molmo, Gemini, Claude, OpenAI)","archived":false,"fork":false,"pushed_at":"2026-01-18T22:25:05.000Z","size":1077,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T04:24:27.394Z","etag":null,"topics":["ai","claude","data-science","data-visualization","gemini","interpretability","jupyter","llm","machine-learning","matplotlib","molmo","multimodal","openai","python","vision-language-model","vlm"],"latest_commit_sha":null,"homepage":"http://kanoa.docs.lhzn.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lhzn-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"agents.md","dco":null,"cla":null}},"created_at":"2025-11-21T15:35:15.000Z","updated_at":"2026-01-18T22:14:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lhzn-io/kanoa","commit_stats":null,"previous_names":["lhzn-io/kanoa"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/lhzn-io/kanoa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lhzn-io%2Fkanoa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lhzn-io%2Fkanoa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lhzn-io%2Fkanoa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lhzn-io%2Fkanoa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lhzn-io","download_url":"https://codeload.github.com/lhzn-io/kanoa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lhzn-io%2Fkanoa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33757790,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","data-science","data-visualization","gemini","interpretability","jupyter","llm","machine-learning","matplotlib","molmo","multimodal","openai","python","vision-language-model","vlm"],"created_at":"2026-06-01T02:31:32.104Z","updated_at":"2026-06-01T02:31:33.013Z","avatar_url":"https://github.com/lhzn-io.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kanoa\n\n\u003e **In-notebook AI interpretation of data science outputs, grounded in your project's knowledge base.**\n\n[![Tests](https://github.com/lhzn-io/kanoa/actions/workflows/tests.yml/badge.svg)](https://github.com/lhzn-io/kanoa/actions/workflows/tests.yml)\n[![Docs](https://img.shields.io/badge/docs-kanoa.docs.lhzn.io-blue)](https://kanoa.docs.lhzn.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![Companion: kanoa-mlops](https://img.shields.io/badge/companion-kanoa--mlops-purple)](https://github.com/lhzn-io/kanoa-mlops)\n\n`kanoa` brings the power of a dedicated AI research assistant directly into your Python workflows — whether in Jupyter notebooks, Streamlit apps, or automated scripts. It programmatically interprets visualizations, tables, and results using multimodal LLMs (Molmo, Gemini, Claude, OpenAI), grounded in your project's documentation and literature.\n\n## Supported Backends\n\n| Backend | Best For | Getting Started |\n| :--- | :--- | :--- |\n| `vllm` | Local inference with [Molmo](https://molmo.allenai.org/), Gemma 3, Olmo 3 | [Guide](./docs/source/user_guide/getting_started_local.md) |\n| `gemini` | Free tier, native PDF support, Vertex AI RAG Engine | [Guide](./docs/source/user_guide/getting_started_gemini.md) |\n| `gemini-deep-research` | Multi-step web research, GDrive integration | [Guide](./docs/source/user_guide/deep_research.md) |\n| `claude` | Strong reasoning, vision support | [Guide](./docs/source/user_guide/getting_started_claude.md) |\n| `github-copilot` | GitHub Copilot SDK integration, GPT-5 models | [Guide](./docs/source/user_guide/backends.md#github-copilot-sdk-github-copilot) |\n| `openai` | GPT models, Azure OpenAI | [Guide](./docs/source/user_guide/backends.md#openai) |\n\nFor detailed backend comparison, see [Backends Overview](./docs/source/user_guide/backends.md).\n\n## Features\n\n- **Multi-Backend Support**: Seamlessly switch between vLLM (local), Gemini, Claude, GitHub Copilot, and OpenAI.\n- **Deep Research**: Perform multi-step web research and synthesis using Gemini's Deep Research agent.\n- **Real-time Streaming**: Get immediate feedback with streaming responses.\n- **Enterprise Grounding**: Native integration with **Vertex AI RAG Engine** for scalable, secure knowledge retrieval from thousands of documents.\n- **Native Vision**: Uses multimodal capabilities to \"see\" complex plots and diagrams.\n- **Cost Optimized**: Intelligent context caching and token usage tracking.\n- **Knowledge Base**: Support for text (Markdown), PDF, and managed RAG knowledge bases.\n- **Notebook-Native Logging**: see the [Logging Guide](./docs/source/user_guide/logging.md).\n\n## Quick Start\n\nCheck out [2 Minutes to kanoa](./examples/2_minutes_to_kanoa.ipynb) for a hands-on introduction.\n\nFor a comprehensive feature overview, see the [detailed quickstart](./examples/quickstart_10min.ipynb).\n\n### Basic Usage: AI-assisted Debugging with Visual Interpretation\n\nIn this example, we use `kanoa` to identify a bug in a physics simulation.\n\n```python\nimport numpy as np\nimport matplotlib.pyplot as plt\nfrom kanoa import AnalyticsInterpreter\n\n# 1. Simulate a projectile (with a bug!)\nt = np.linspace(0, 10, 100)\nv0 = 50\ng = 9.8\n# BUG: Missing t**2 in the gravity term (should be 0.5 * g * t**2)\ny = v0 * t - 0.5 * g * t\n\nplt.figure(figsize=(10, 6))\nplt.plot(t, y)\nplt.title(\"Projectile Trajectory\")\n\n# 2. Ask kanoa to debug\ninterpreter = AnalyticsInterpreter(backend=\"gemini\")\n# Returns a stream by default\niterator = interpreter.interpret(\n    fig=plt.gcf(),\n    context=\"Simulating a projectile launch. Something looks wrong.\",\n    focus=\"Identify the physics error in the trajectory.\",\n)\n\n# Consume the stream\nfor chunk in iterator:\n    if chunk.type == \"text\":\n        print(chunk.content, end=\"\")\n```\n\n`kanoa`'s response:\n\u003e \"The plot shows a linear relationship between height and time...\"\n\n### Using Claude\n\n```python\n# Ensure ANTHROPIC_API_KEY is set\ninterpreter = AnalyticsInterpreter(backend='claude')\n\n# Use stream=False for blocking behavior (returns legacy result object)\nresult = interpreter.interpret(\n    fig=plt.gcf(),\n    context=\"Analyzing environmental data for climate trends\",\n    focus=\"Explain any regime changes in the data.\",\n    stream=False\n)\nprint(result.text)\n```\n\n### Using a Knowledge Base\n\n```python\n# Point to a directory of Markdown or PDF files\ninterpreter = AnalyticsInterpreter(\n    backend='gemini',\n    kb_path='./docs/literature',\n    kb_type='auto'  # Detects if PDFs are present\n)\n\n# The interpreter will now use the knowledge base to ground its analysis\nresult = interpreter.interpret(\n    fig=plt.gcf(),\n    context=\"Analyzing marine biologger data from a whale shark deployment\",\n    focus=\"Compare diving behavior with Braun et al. 2025 findings.\"\n)\nprint(result.text)\n```\n\n### Local Inference with vLLM\n\nConnect to any model hosted via vLLM's OpenAI-compatible API. We've tested with\n[Molmo](https://molmo.allenai.org/) from AI2 and Google's Gemma 3 12B — fully-open multimodal models.\nSee `kanoa-mlops` for our local hosting setup.\n\n```python\n# Molmo 7B (recommended for vision - 31 tok/s avg, 3x faster than Gemma)\ninterpreter = AnalyticsInterpreter(\n    backend='openai',\n    api_base='http://localhost:8000/v1',\n    model='allenai/Molmo-7B-D-0924'\n)\n\n# Gemma 3 12B (recommended for text reasoning - 10.3 tok/s avg)\ninterpreter = AnalyticsInterpreter(\n    backend='openai',\n    api_base='http://localhost:8000/v1',\n    model='google/gemma-3-12b-it'\n)\n\nresult = interpreter.interpret(\n    fig=plt.gcf(),\n    context=\"Analyzing aquaculture sensor data\",\n    focus=\"Identify drivers of dissolved oxygen levels\"\n)\n```\n\n## Local \u0026 Edge Deployment\n\nRun state-of-the-art open weights models locally using our companion library, [`kanoa-mlops`](https://github.com/lhzn-io/kanoa-mlops).\n\n- **Privacy First**: Your data never leaves your machine.\n- **Models**: Support for **Gemma 3**, **Molmo**, and **Olmo 3**.\n- **Performance**: Optimized for consumer hardware (RTX 4090/5080) and edge devices (NVIDIA Jetson Thor).\n\n### Benchmarks (NVIDIA RTX 5080)\n\n| Model | Task | Speed |\n| :--- | :--- | :--- |\n| **Molmo-7B** | Complex Plot Interpretation | **92.8 tokens/sec** |\n| **Molmo-7B** | Data Interpretation | **59.5 tokens/sec** |\n\n### Benchmarks (NVIDIA Jetson Thor)\n\n| Model | Task | Speed |\n| :--- | :--- | :--- |\n| **Molmo-7B** | Complex Plot Interpretation | **9.6 tokens/sec** |\n| **Molmo-7B** | Data Interpretation | **9.5 tokens/sec** |\n| **Gemma 3 12B** | Vision (Chart Analysis) | **4.3 tokens/sec** |\n| **Gemma 3 12B** | Code Generation | **4.4 tokens/sec** |\n\n## Installation\n\n`kanoa` is modular — install only the backends you need:\n\n```bash\n# Local inference (vLLM — Molmo, Gemma 3)\npip install kanoa[local]\n\n# Google Gemini (free tier available)\npip install kanoa[gemini]\n\n# Anthropic Claude\npip install kanoa[claude]\n\n# GitHub Copilot SDK\npip install kanoa[github-copilot]\n\n# OpenAI API (GPT models, Azure OpenAI)\npip install kanoa[openai]\n\n# Everything\npip install kanoa[all]\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eDevelopment installation\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/lhzn-io/kanoa.git\ncd kanoa\npip install -e \".[dev]\"\n```\n\n\u003c/details\u003e\n\n## Pricing Configuration\n\n`kanoa` includes up-to-date pricing for all supported models. You can override these values locally without waiting for a package update:\n\n1. Create `~/.config/kanoa/pricing.json`\n2. Add your custom pricing (merges with defaults):\n\n```json\n{\n  \"gemini\": {\n    \"gemini-3-pro-preview\": {\n      \"input_price\": 2.00,\n      \"output_price\": 12.00\n    }\n  },\n  \"claude\": {\n    \"claude-opus-4-5-20251101\": {\n      \"input_price\": 5.00,\n      \"output_price\": 25.00\n    }\n  }\n}\n```\n\nPricing sources:\n\n- **Gemini**: [ai.google.dev/pricing](https://ai.google.dev/pricing)\n- **Claude**: [anthropic.com/pricing](https://www.anthropic.com/pricing)\n- **OpenAI**: [openai.com/api/pricing](https://openai.com/api/pricing)\n\n## Documentation\n\n📖 **[Full documentation](https://kanoa.docs.lhzn.io)** — User guides, API reference, and examples.\n\n\u003cdetails\u003e\n\u003csummary\u003eBuilding docs locally\u003c/summary\u003e\n\n```bash\ncd docs\npip install -r requirements-docs.txt\nmake html\n```\n\nThen open `docs/build/html/index.html` in your browser.\n\n\u003c/details\u003e\n\n## License\n\nCopyright 2025 Long Horizon Observatory\n\nThis project is licensed under the MIT License — see the [LICENSE](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flhzn-io%2Fkanoa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flhzn-io%2Fkanoa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flhzn-io%2Fkanoa/lists"}