jvmind-ce 0.1.6__tar.gz

jvmind_ce-0.1.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JVMind Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jvmind_ce-0.1.6/MANIFEST.in

@@ -0,0 +1,34 @@
+# Source distribution manifest for jvmind-ce.
+
+# Frontend build artifacts — required by app/frontend.py to serve /,
+# /assets, /lib, /image. Ship pre-built dist/ when releasing.
+include frontend/dist/*
+include frontend/dist/**/*
+recursive-include frontend/dist *
+
+# i18n JSON files referenced by frontend at runtime
+include frontend/i18n/*.json
+
+# Frontend source — only needed for development (npm run dev), but
+# ship it so the source paths in index.html can still be served as a
+# fallback when no build is present.
+include frontend/index.html
+include frontend/report.html
+include frontend/src/*.js
+include frontend/src/*.css
+include frontend/src/css/*.css
+include frontend/src/test/*.js
+include frontend/src/gc-analysis/*
+include frontend/src/heapdump-analysis/*
+recursive-include frontend/src *
+
+# Bundled MAT query-service plugin (used by heapdump_worker)
+include vendor/mat/*.jar
+
+# Repository root files
+include LICENSE
+include README.md
+include README.zh-CN.md
+
+# Build tool scripts
+include scripts/install_mat.sh

jvmind_ce-0.1.6/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: jvmind-ce
+Version: 0.1.6
+Summary: JVMind Community Edition — JVM diagnostics AI agent (GC logs, jstack, heapdump analysis)
+Author: JVMind Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/jvmind/jvmind-ce
+Project-URL: Repository, https://github.com/jvmind/jvmind-ce
+Project-URL: Issues, https://github.com/jvmind/jvmind-ce/issues
+Keywords: jvm,gc,jstack,heapdump,diagnostics,ai,react-agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.30.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Requires-Dist: sse-starlette>=2.0.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: psycopg[binary]>=3.3.4
+Requires-Dist: pydantic>=2.0
+Requires-Dist: starlette>=0.27.0
+Requires-Dist: markdown>=3.0
+Requires-Dist: langgraph<1.0,>=0.2
+Requires-Dist: langchain-core<0.4,>=0.3
+Requires-Dist: langchain-openai<1.0,>=0.3
+Requires-Dist: tiktoken<1.0,>=0.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: anyio>=4.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: fonttools>=4.0; extra == "dev"
+Requires-Dist: brotli>=1.1; extra == "dev"
+Dynamic: license-file
+
+# JVMind Community Edition
+
+> An AI-powered JVM diagnostics agent. **Single-user · local-first · open source.**
+>
+> [中文文档 (Chinese)](./README.zh-CN.md) · [Report a bug](https://github.com/jvmind/jvmind-ce/issues/new?template=bug.md) · [Request a feature](https://github.com/jvmind/jvmind-ce/issues/new?template=feature.md)
+
+JVMind CE is a JVM performance diagnostics assistant built on OpenAI-compatible LLMs. It runs the agent as a local web service, accepts uploaded logs/dumps, and streams diagnostic conclusions back over SSE.
+
+- 🧠 **LangGraph agent** — Tool orchestration via LangGraph state machines (native OpenAI function-calling).
+- 🪵 **GC log analysis** — JDK 8 / 11 / 17 / 21 / 25 collectors (G1, Parallel, ZGC, Shenandoah, Serial, CMS). Pure regex parsers, no external runtime deps.
+- 🧵 **jstack thread analysis** — Deadlock detection, lock-contention hotspots, thread-pool distribution, flame graph, per-thread drill-down.
+- 💾 **Heapdump analysis (optional)** — Parses GB-sized hprof files via Eclipse MAT (requires JDK 21). Ships with the bundled query-service plugin.
+- 🔌 **OpenAI-compatible LLM** — DeepSeek, OpenAI, Qwen, Kimi, Ollama (local), and any compatible endpoint. Hot-reloadable UI config.
+- 🏠 **Ollama local inference** — Run entirely offline with no data leaving your machine. Zero-cost, no API key required.
+
+The community edition ships **without** billing, team management, or rate limits. For those, use a commercial offering.
+
+![JVMind CE Screenshot](frontend/public/image/chat_window.png)
+
+---
+
+## Quick Start
+
+### Install from PyPI
+
+```bash
+pip install jvmind-ce
+jvmind
+# open http://127.0.0.1:8000
+```
+
+### Install from source (developer mode)
+
+```bash
+git clone https://github.com/jvmind/jvmind-ce.git
+cd jvmind-ce
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+jvmind
+```
+
+### Configure the LLM
+
+The UI prompts for an API key on first launch. Two options:
+
+**Option A — Remote LLM provider (DeepSeek, OpenAI, etc.):**
+
+```bash
+cp .env.example .env
+# Edit .env:
+OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
+OPENAI_BASE_URL=https://api.deepseek.com/v1
+OPENAI_MODEL=deepseek-chat
+```
+
+**Option B — Local Ollama (no API key, zero-cost, fully offline):**
+
+```bash
+# 1. Install & start Ollama: https://ollama.com
+# 2. Pull a model:
+ollama pull qwen2.5
+# 3. In the JVMind UI, click "Ollama · Local" preset in Settings (⚙️)
+#    or set in .env:
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen2.5
+#    Leave OPENAI_API_KEY empty — Ollama doesn't need one.
+```
+
+The agent uses native OpenAI function-calling, so any model supporting `tools` works. DeepSeek's `deepseek-chat` is a sensible default for remote inference; `qwen2.5` or `llama3.1` are good choices for local Ollama.
+
+> **Privacy**: When using Ollama with a local model, no data ever leaves your machine — all GC logs, thread dumps, heap dumps, and conversation content stay local.
+
+---
+
+## Features
+
+### GC log analysis
+
+Open the **📊 GC Logs** tab, upload a log file. The pipeline:
+
+1. Stream-upload → store raw text in DB
+2. Parser (pure regex) extracts events, computes statistics, builds overview
+3. Render: 8 status cards + per-collector table + heap chart + pause histogram + top-10 slowest
+4. Trigger a streamed LLM diagnosis with the structured template (overall health, key issues, parameter tuning, follow-up metrics)
+
+Supported collectors: **G1** · **Parallel** · **Serial** · **ZGC** · **Shenandoah** · **CMS**. JDK 9+ unified log format and JDK 8 PrintGCDetails are both supported.
+
+### jstack thread analysis
+
+Open the **🧵 Thread Dumps** tab, upload a `jstack -l` dump. Features:
+
+- Thread state histogram (RUNNABLE / BLOCKED / WAITING / TIMED_WAITING)
+- Deadlock detection with lock chain visualization
+- Lock contention hotspots (holder + waiters list, click-to-drill)
+- Thread pool distribution, flame graph, single-thread drill-down
+- Streamed LLM diagnosis (whole dump or single thread)
+
+### Heapdump analysis (optional — requires Eclipse MAT + JDK 21)
+
+The **🔍 Heap Dumps** tab uploads GB-sized `.hprof` files. The architecture:
+
+```
+  Browser ─▶ FastAPI (upload routes) ─▶ local disk: <dump_dir>/<report_id>/
+                                              │
+                                              ▼
+                            worker_loop ─▶ ParseHeapDump.sh
+                                              │
+                                              ▼
+                          ┌───── query-service (HTTP) ◀─────┐
+                          │   bundled in vendor/mat/         │
+                          └──────────────────────────────────┘
+                                              │
+                                              ▼
+  Browser ◀────── SSE progress / JSON query results ◀───── FastAPI proxy
+```
+
+**Install MAT and the query-service in one step:**
+
+```bash
+./scripts/install_mat.sh /opt/mat
+# or: MAT_HOME=/opt/mat ./scripts/install_mat.sh
+```
+
+This downloads Eclipse MAT, extracts it, and copies the bundled `com.jvmind.mat.query-0.1.0.jar` into the MAT plugins directory. **Note: MAT requires JDK 21.** Configure and run:
+
+```bash
+# .env
+MAT_HOME=/opt/mat
+MAT_QUERY_SERVICE_URL=http://127.0.0.1:8090
+```
+
+```bash
+# Terminal 1: query-service
+/opt/mat/MemoryAnalyzer -consoleLog -nosplash \
+    -application com.jvmind.mat.query.QueryServiceApp
+
+# Terminal 2: heapdump worker (separate process)
+jvmind-worker
+```
+
+The bundled query-service jar ships inside `vendor/mat/`, so users don't need to compile Java themselves.
+
+### Agent internals
+
+The agent is a **LangGraph** state machine in `react_agent/graph/`:
+
+- `facade.LangGraphAgent` — public API, matches the legacy agent's interface
+- `graph_builder.build_graph` — wires nodes (Agent → Tools → Finalize)
+- `nodes` — tool execution + structured reasoning (cross-domain diagnosis for OOM)
+- `sse_adapter` — yields `user` / `token` / `step` / `fact_added` / `final` / `error` / `done` events
+- `llm_compat` / `parsing_compat` — shared mixins for tool-call error detection
+
+Native OpenAI function-calling is the default. If a provider rejects the `tools` parameter, the agent surfaces a clear error rather than silently degrading.
+
+---
+
+## Configuration
+
+See [`.env.example`](./.env.example) for the full list. Key knobs:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `HOST` / `PORT` | `127.0.0.1` / `8000` | Bind address |
+| `DATABASE_URL` | `sqlite:///./data/app.db` | SQLAlchemy URL; switch to PostgreSQL for prod |
+| `OPENAI_API_KEY` | — | Required for remote providers; leave empty when using local Ollama |
+| `OPENAI_BASE_URL` | `https://api.deepseek.com/v1` | Any OpenAI-compatible endpoint |
+| `OPENAI_MODEL` | `deepseek-chat` | Model name |
+| `OPENAI_TIMEOUT_SECONDS` | `60` | Per-LLM-call timeout |
+| `CONFIG_ENCRYPTION_KEY` | — | Encrypts persisted API keys at rest |
+| `HEAPDUMP_*` | see `.env.example` | Only relevant if using heapdump analysis |
+
+The web UI also has a Settings (⚙️) dialog for LLM config — changes hot-reload the agent and re-encrypt stored keys.
+
+---
+
+## Development
+
+```bash
+# Run dev server with auto-reload
+uvicorn server:app --reload --port 8000
+
+# Run all tests
+python -m pytest _tests --no-cov
+
+# Frontend dev (Vite hot-reload)
+cd frontend && npm install && npm run dev
+
+# Frontend production build
+cd frontend && npm run build
+
+# Heapdump worker (separate process)
+jvmind-worker
+```
+
+Project layout:
+
+```
+jvmind-ce/
+├── server.py              # FastAPI entry point
+├── app/                   # routes, middleware, helpers
+├── react_agent/
+│   ├── graph/             # LangGraph agent (default)
+│   ├── gc_analyzer/       # GC log parsers (JDK 8 + JDK 9+)
+│   ├── jstack_analyzer.py
+│   ├── mat_tools.py       # Heapdump tool wrappers
+│   ├── heapdump_worker/   # Background MAT parser
+│   ├── memory_db.py
+│   ├── user_manager_db.py # single-user
+│   └── db.py / models.py
+├── frontend/              # vanilla JS + Vite
+├── vendor/mat/            # bundled query-service jar
+├── scripts/install_mat.sh # one-step MAT install
+└── _tests/                # pytest suite (146 tests)
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and [CONVENTIONS.md](./CONVENTIONS.md).
+
+## Credits
+
+JVMind CE is extracted from the commercial JVMind product. The commercial edition includes multi-user auth, team workspaces, Paddle billing, PostHog analytics, and other features that this repository deliberately omits.

jvmind_ce-0.1.6/README.md

@@ -0,0 +1,226 @@
+# JVMind Community Edition
+
+> An AI-powered JVM diagnostics agent. **Single-user · local-first · open source.**
+>
+> [中文文档 (Chinese)](./README.zh-CN.md) · [Report a bug](https://github.com/jvmind/jvmind-ce/issues/new?template=bug.md) · [Request a feature](https://github.com/jvmind/jvmind-ce/issues/new?template=feature.md)
+
+JVMind CE is a JVM performance diagnostics assistant built on OpenAI-compatible LLMs. It runs the agent as a local web service, accepts uploaded logs/dumps, and streams diagnostic conclusions back over SSE.
+
+- 🧠 **LangGraph agent** — Tool orchestration via LangGraph state machines (native OpenAI function-calling).
+- 🪵 **GC log analysis** — JDK 8 / 11 / 17 / 21 / 25 collectors (G1, Parallel, ZGC, Shenandoah, Serial, CMS). Pure regex parsers, no external runtime deps.
+- 🧵 **jstack thread analysis** — Deadlock detection, lock-contention hotspots, thread-pool distribution, flame graph, per-thread drill-down.
+- 💾 **Heapdump analysis (optional)** — Parses GB-sized hprof files via Eclipse MAT (requires JDK 21). Ships with the bundled query-service plugin.
+- 🔌 **OpenAI-compatible LLM** — DeepSeek, OpenAI, Qwen, Kimi, Ollama (local), and any compatible endpoint. Hot-reloadable UI config.
+- 🏠 **Ollama local inference** — Run entirely offline with no data leaving your machine. Zero-cost, no API key required.
+
+The community edition ships **without** billing, team management, or rate limits. For those, use a commercial offering.
+
+![JVMind CE Screenshot](frontend/public/image/chat_window.png)
+
+---
+
+## Quick Start
+
+### Install from PyPI
+
+```bash
+pip install jvmind-ce
+jvmind
+# open http://127.0.0.1:8000
+```
+
+### Install from source (developer mode)
+
+```bash
+git clone https://github.com/jvmind/jvmind-ce.git
+cd jvmind-ce
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+jvmind
+```
+
+### Configure the LLM
+
+The UI prompts for an API key on first launch. Two options:
+
+**Option A — Remote LLM provider (DeepSeek, OpenAI, etc.):**
+
+```bash
+cp .env.example .env
+# Edit .env:
+OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
+OPENAI_BASE_URL=https://api.deepseek.com/v1
+OPENAI_MODEL=deepseek-chat
+```
+
+**Option B — Local Ollama (no API key, zero-cost, fully offline):**
+
+```bash
+# 1. Install & start Ollama: https://ollama.com
+# 2. Pull a model:
+ollama pull qwen2.5
+# 3. In the JVMind UI, click "Ollama · Local" preset in Settings (⚙️)
+#    or set in .env:
+OPENAI_BASE_URL=http://localhost:11434/v1
+OPENAI_MODEL=qwen2.5
+#    Leave OPENAI_API_KEY empty — Ollama doesn't need one.
+```
+
+The agent uses native OpenAI function-calling, so any model supporting `tools` works. DeepSeek's `deepseek-chat` is a sensible default for remote inference; `qwen2.5` or `llama3.1` are good choices for local Ollama.
+
+> **Privacy**: When using Ollama with a local model, no data ever leaves your machine — all GC logs, thread dumps, heap dumps, and conversation content stay local.
+
+---
+
+## Features
+
+### GC log analysis
+
+Open the **📊 GC Logs** tab, upload a log file. The pipeline:
+
+1. Stream-upload → store raw text in DB
+2. Parser (pure regex) extracts events, computes statistics, builds overview
+3. Render: 8 status cards + per-collector table + heap chart + pause histogram + top-10 slowest
+4. Trigger a streamed LLM diagnosis with the structured template (overall health, key issues, parameter tuning, follow-up metrics)
+
+Supported collectors: **G1** · **Parallel** · **Serial** · **ZGC** · **Shenandoah** · **CMS**. JDK 9+ unified log format and JDK 8 PrintGCDetails are both supported.
+
+### jstack thread analysis
+
+Open the **🧵 Thread Dumps** tab, upload a `jstack -l` dump. Features:
+
+- Thread state histogram (RUNNABLE / BLOCKED / WAITING / TIMED_WAITING)
+- Deadlock detection with lock chain visualization
+- Lock contention hotspots (holder + waiters list, click-to-drill)
+- Thread pool distribution, flame graph, single-thread drill-down
+- Streamed LLM diagnosis (whole dump or single thread)
+
+### Heapdump analysis (optional — requires Eclipse MAT + JDK 21)
+
+The **🔍 Heap Dumps** tab uploads GB-sized `.hprof` files. The architecture:
+
+```
+  Browser ─▶ FastAPI (upload routes) ─▶ local disk: <dump_dir>/<report_id>/
+                                              │
+                                              ▼
+                            worker_loop ─▶ ParseHeapDump.sh
+                                              │
+                                              ▼
+                          ┌───── query-service (HTTP) ◀─────┐
+                          │   bundled in vendor/mat/         │
+                          └──────────────────────────────────┘
+                                              │
+                                              ▼
+  Browser ◀────── SSE progress / JSON query results ◀───── FastAPI proxy
+```
+
+**Install MAT and the query-service in one step:**
+
+```bash
+./scripts/install_mat.sh /opt/mat
+# or: MAT_HOME=/opt/mat ./scripts/install_mat.sh
+```
+
+This downloads Eclipse MAT, extracts it, and copies the bundled `com.jvmind.mat.query-0.1.0.jar` into the MAT plugins directory. **Note: MAT requires JDK 21.** Configure and run:
+
+```bash
+# .env
+MAT_HOME=/opt/mat
+MAT_QUERY_SERVICE_URL=http://127.0.0.1:8090
+```
+
+```bash
+# Terminal 1: query-service
+/opt/mat/MemoryAnalyzer -consoleLog -nosplash \
+    -application com.jvmind.mat.query.QueryServiceApp
+
+# Terminal 2: heapdump worker (separate process)
+jvmind-worker
+```
+
+The bundled query-service jar ships inside `vendor/mat/`, so users don't need to compile Java themselves.
+
+### Agent internals
+
+The agent is a **LangGraph** state machine in `react_agent/graph/`:
+
+- `facade.LangGraphAgent` — public API, matches the legacy agent's interface
+- `graph_builder.build_graph` — wires nodes (Agent → Tools → Finalize)
+- `nodes` — tool execution + structured reasoning (cross-domain diagnosis for OOM)
+- `sse_adapter` — yields `user` / `token` / `step` / `fact_added` / `final` / `error` / `done` events
+- `llm_compat` / `parsing_compat` — shared mixins for tool-call error detection
+
+Native OpenAI function-calling is the default. If a provider rejects the `tools` parameter, the agent surfaces a clear error rather than silently degrading.
+
+---
+
+## Configuration
+
+See [`.env.example`](./.env.example) for the full list. Key knobs:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `HOST` / `PORT` | `127.0.0.1` / `8000` | Bind address |
+| `DATABASE_URL` | `sqlite:///./data/app.db` | SQLAlchemy URL; switch to PostgreSQL for prod |
+| `OPENAI_API_KEY` | — | Required for remote providers; leave empty when using local Ollama |
+| `OPENAI_BASE_URL` | `https://api.deepseek.com/v1` | Any OpenAI-compatible endpoint |
+| `OPENAI_MODEL` | `deepseek-chat` | Model name |
+| `OPENAI_TIMEOUT_SECONDS` | `60` | Per-LLM-call timeout |
+| `CONFIG_ENCRYPTION_KEY` | — | Encrypts persisted API keys at rest |
+| `HEAPDUMP_*` | see `.env.example` | Only relevant if using heapdump analysis |
+
+The web UI also has a Settings (⚙️) dialog for LLM config — changes hot-reload the agent and re-encrypt stored keys.
+
+---
+
+## Development
+
+```bash
+# Run dev server with auto-reload
+uvicorn server:app --reload --port 8000
+
+# Run all tests
+python -m pytest _tests --no-cov
+
+# Frontend dev (Vite hot-reload)
+cd frontend && npm install && npm run dev
+
+# Frontend production build
+cd frontend && npm run build
+
+# Heapdump worker (separate process)
+jvmind-worker
+```
+
+Project layout:
+
+```
+jvmind-ce/
+├── server.py              # FastAPI entry point
+├── app/                   # routes, middleware, helpers
+├── react_agent/
+│   ├── graph/             # LangGraph agent (default)
+│   ├── gc_analyzer/       # GC log parsers (JDK 8 + JDK 9+)
+│   ├── jstack_analyzer.py
+│   ├── mat_tools.py       # Heapdump tool wrappers
+│   ├── heapdump_worker/   # Background MAT parser
+│   ├── memory_db.py
+│   ├── user_manager_db.py # single-user
+│   └── db.py / models.py
+├── frontend/              # vanilla JS + Vite
+├── vendor/mat/            # bundled query-service jar
+├── scripts/install_mat.sh # one-step MAT install
+└── _tests/                # pytest suite (146 tests)
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and [CONVENTIONS.md](./CONVENTIONS.md).
+
+## Credits
+
+JVMind CE is extracted from the commercial JVMind product. The commercial edition includes multi-user auth, team workspaces, Paddle billing, PostHog analytics, and other features that this repository deliberately omits.