malimgraph 0.1.1__tar.gz

malimgraph-0.1.1/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git config *)",
+      "Bash(git commit -m ' *)",
+      "Bash(git remote *)",
+      "Bash(git branch *)",
+      "Bash(git push *)",
+      "Bash(git add *)",
+      "Bash(gh run *)",
+      "mcp__Claude_in_Chrome__tabs_context_mcp",
+      "Bash(pip install *)",
+      "PowerShell(python --version)",
+      "PowerShell(python -m pip install ruff 2>&1)"
+    ]
+  }
+}

malimgraph-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: pip install ruff
+      - name: Run ruff check
+        run: ruff check src/ tests/
+      - name: Run ruff format check
+        run: ruff format --check src/ tests/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+        env:
+          ANTHROPIC_API_KEY: ""  # Tests that need this are mocked

malimgraph-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,78 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release-build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build release distributions
+        run: |
+          python -m pip install build hatchling
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: release-build
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/malimgraph/${{ github.ref_name }}
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  package-skills:
+    name: Package Claude Skills
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Package all skills
+        run: |
+          mkdir -p dist
+          cd skills/pdf-to-knowledge-graph && zip -r ../../dist/pdf-to-knowledge-graph.skill SKILL.md scripts/ && cd ../..
+          cd skills/pdf-to-chunks && zip -r ../../dist/pdf-to-chunks.skill SKILL.md scripts/ && cd ../..
+          cd skills/document-to-html && zip -r ../../dist/document-to-html.skill SKILL.md scripts/ && cd ../..
+          cd skills/graph-db-admin && zip -r ../../dist/graph-db-admin.skill SKILL.md scripts/ && cd ../..
+          cd skills/chunks-to-pgvector && zip -r ../../dist/chunks-to-pgvector.skill SKILL.md scripts/ && cd ../..
+
+      - name: Upload skills to GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/pdf-to-knowledge-graph.skill
+            dist/pdf-to-chunks.skill
+            dist/document-to-html.skill
+            dist/graph-db-admin.skill
+            dist/chunks-to-pgvector.skill
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

malimgraph-0.1.1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.pyo
+.Python
+*.egg-info/
+dist/
+build/
+.env
+.venv
+venv/
+.pytest_cache/
+.ruff_cache/
+*.egg

malimgraph-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Malim AI Labs Social Enterprise (003827047-U)
+
+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.

malimgraph-0.1.1/Makefile

@@ -0,0 +1,45 @@
+.PHONY: install dev lint test build skills clean
+
+install:
+	pip install -e .
+
+dev:
+	pip install -e ".[dev,all]"
+
+lint:
+	ruff check src/ tests/
+	ruff format --check src/ tests/
+
+format:
+	ruff format src/ tests/
+	ruff check --fix src/ tests/
+
+test:
+	pytest tests/ -v
+
+test-cov:
+	pytest tests/ -v --tb=short --cov=malimgraph --cov-report=term-missing
+
+build:
+	python -m build
+
+skills:
+	@echo "Packaging skills..."
+	@mkdir -p dist
+	cd skills/pdf-to-knowledge-graph && zip -r ../../dist/pdf-to-knowledge-graph.skill SKILL.md scripts/
+	cd skills/pdf-to-chunks && zip -r ../../dist/pdf-to-chunks.skill SKILL.md scripts/
+	cd skills/document-to-html && zip -r ../../dist/document-to-html.skill SKILL.md scripts/
+	cd skills/graph-db-admin && zip -r ../../dist/graph-db-admin.skill SKILL.md scripts/
+	cd skills/chunks-to-pgvector && zip -r ../../dist/chunks-to-pgvector.skill SKILL.md scripts/
+	@echo "Skills packaged in dist/"
+
+clean:
+	rm -rf dist/ build/ *.egg-info src/*.egg-info __pycache__
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -name "*.pyc" -delete
+
+serve:
+	malimgraph serve
+
+serve-http:
+	malimgraph serve --transport http --port 8080

malimgraph-0.1.1/PKG-INFO

@@ -0,0 +1,374 @@
+Metadata-Version: 2.4
+Name: malimgraph
+Version: 0.1.1
+Summary: Transform PDF documents into structured knowledge graphs with citation provenance
+Project-URL: Homepage, https://github.com/AiMalim/malimgraph
+Project-URL: Documentation, https://ailabs.malim.my/malimgraph
+Project-URL: Repository, https://github.com/AiMalim/malimgraph
+Project-URL: Issues, https://github.com/AiMalim/malimgraph/issues
+Author-email: Malim AI Labs <hello@malim.my>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: apache-age,cypher,graphrag,knowledge-graph,mcp,neo4j,nlp,pdf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.40
+Requires-Dist: click>=8.0
+Requires-Dist: mcp>=1.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pymupdf>=1.24
+Provides-Extra: age
+Requires-Dist: psycopg2-binary>=2.9; extra == 'age'
+Provides-Extra: all
+Requires-Dist: neo4j>=5.0; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Requires-Dist: pgvector>=0.2; extra == 'all'
+Requires-Dist: psycopg2-binary>=2.9; extra == 'all'
+Requires-Dist: sentence-transformers>=3.0; extra == 'all'
+Requires-Dist: voyageai>=0.2; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: local
+Requires-Dist: sentence-transformers>=3.0; extra == 'local'
+Provides-Extra: neo4j
+Requires-Dist: neo4j>=5.0; extra == 'neo4j'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: pgvector
+Requires-Dist: pgvector>=0.2; extra == 'pgvector'
+Requires-Dist: psycopg2-binary>=2.9; extra == 'pgvector'
+Provides-Extra: voyage
+Requires-Dist: voyageai>=0.2; extra == 'voyage'
+Description-Content-Type: text/markdown
+
+# MalimGraph
+
+```
+███╗   ███╗ █████╗ ██╗     ██╗███╗   ███╗ ██████╗ ██████╗  █████╗ ██████╗ ██╗  ██╗
+████╗ ████║██╔══██╗██║     ██║████╗ ████║██╔════╝ ██╔══██╗██╔══██╗██╔══██╗██║  ██║
+██╔████╔██║███████║██║     ██║██╔████╔██║██║  ███╗██████╔╝███████║██████╔╝███████║
+██║╚██╔╝██║██╔══██║██║     ██║██║╚██╔╝██║██║   ██║██╔══██╗██╔══██║██╔═══╝ ██╔══██║
+██║ ╚═╝ ██║██║  ██║███████╗██║██║ ╚═╝ ██║╚██████╔╝██║  ██║██║  ██║██║     ██║  ██║
+╚═╝     ╚═╝╚═╝  ╚═╝╚══════╝╚═╝╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝
+```
+
+[![PyPI version](https://badge.fury.io/py/malimgraph.svg)](https://badge.fury.io/py/malimgraph)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
+[![CI](https://github.com/malim-ai-labs/malim-graph-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/malim-ai-labs/malim-graph-plugin/actions/workflows/ci.yml)
+
+**From documents to knowledge graphs.**
+
+Transform PDF documents into structured knowledge graphs with full citation provenance. Every entity and relationship traces back to the exact PDF page and verbatim text that supports it.
+
+---
+
+## Features
+
+| Tool | Description |
+|------|-------------|
+| `extract_knowledge_graph` | Hybrid rule + LLM extraction → entities, relationships, citations |
+| `chunk_document` | Token-aware overlapping chunks with heading context for RAG |
+| `render_document_html` | Structured HTML with page anchors, entity annotations, TOC + search |
+| `manage_graph_db` | Load, query, and manage graphs in Neo4j or PostgreSQL (Apache AGE) |
+| `embed_and_store_chunks` | Embed chunks into PostgreSQL pgvector (OpenAI / Voyage / local) |
+
+**Three ways to use:**
+- **MCP Server** — connect to Claude Desktop, Claude Code, or claude.ai
+- **CLI** — `malimgraph extract`, `chunk`, `render`, `db`, `vector`
+- **Claude Skills** — 5 installable `.skill` packages for claude.ai
+
+---
+
+## Quick Start
+
+```bash
+pip install malimgraph
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Extract knowledge graph
+malimgraph extract --input report.pdf --output ./output/ --format all
+
+# Chunk for RAG
+malimgraph chunk --input report.pdf --output ./chunks/
+
+# Embed chunks into pgvector
+export PGVECTOR_URI="postgresql://user:pass@localhost:5432/mydb"
+export OPENAI_API_KEY=sk-...
+malimgraph vector load --input ./chunks/chunks.json
+
+# Render as browsable HTML
+malimgraph render --input report.pdf --output document.html
+```
+
+---
+
+## How It Works
+
+```
+PDF
+ │
+ ▼
+pdf_reader.py ──────────────────────────────────────────────┐
+ │  (PyMuPDF: text, headings, tables, page structure)       │
+ ├──────────────────────────────────┐                        │
+ ▼                                  ▼                        ▼
+rule_extractor.py              llm_extractor.py          chunker.py
+ │ (regex: dates, amounts,      │ (Anthropic API:         │ (sliding window
+ │  emails, legal refs,         │  semantic entities,     │  with heading
+ │  section numbers)            │  relationships,         │  context)
+ │                              │  source_text required)  │
+ └──────────────┬───────────────┘                         │
+                ▼                                          ▼
+          graph_builder.py                          embedder.py
+           │ (merge + dedup:                        │ (OpenAI / Voyage /
+           │  hybrid method,                        │  local sentence-
+           │  citation accumulation,                │  transformers)
+           │  stable IDs)                           │
+           ▼                                        ▼
+     knowledge_graph.json                    vector_client.py
+           │                                 (pgvector: HNSW index,
+     ┌─────┴──────┐                           cosine similarity search)
+     ▼             ▼
+ cypher.py     age_sql.py
+ (.cypher)      (.sql)
+```
+
+---
+
+## Three Ways to Use
+
+### MCP Server
+
+```bash
+# stdio (for Claude Desktop / Claude Code)
+malimgraph serve
+
+# HTTP (for remote connections / claude.ai)
+malimgraph serve --transport http --port 8080
+```
+
+**Claude Desktop config** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "malimgraph": {
+      "command": "malimgraph",
+      "args": ["serve"],
+      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
+    }
+  }
+}
+```
+
+**Claude Code:**
+```bash
+claude mcp add malimgraph -- malimgraph serve
+```
+
+### CLI
+
+```bash
+# Extract knowledge graph from PDF
+malimgraph extract \
+  --input report.pdf \
+  --output ./output/ \
+  --entity-types auto \
+  --format all \
+  --graph-name my_graph
+
+# Chunk for embeddings
+malimgraph chunk \
+  --input report.pdf \
+  --output ./chunks/ \
+  --chunk-size 512 \
+  --overlap 64 \
+  --format json
+
+# Embed chunks into PostgreSQL pgvector
+malimgraph vector load \
+  --input ./chunks/chunks.json \
+  --uri "postgresql://user:pass@localhost:5432/mydb" \
+  --provider openai \
+  --table document_chunks
+
+# Semantic search over embedded chunks
+malimgraph vector search \
+  --query "What are the financial risks?" \
+  --uri "postgresql://user:pass@localhost:5432/mydb" \
+  --top-k 5
+
+# Render as browsable HTML
+malimgraph render \
+  --input report.pdf \
+  --output document.html \
+  --knowledge-graph ./output/knowledge_graph.json
+
+# Load into Neo4j
+malimgraph db load \
+  --input ./output/knowledge_graph.json \
+  --target neo4j \
+  --uri bolt://localhost:7687 \
+  --user neo4j \
+  --password secret
+
+# Query the graph
+malimgraph db query \
+  --target neo4j \
+  --uri bolt://localhost:7687 \
+  --query "MATCH (n:Organization) RETURN n.label, n.source_pages LIMIT 10"
+```
+
+### Claude Skills
+
+Download `.skill` files from [GitHub Releases](https://github.com/malim-ai-labs/malim-graph-plugin/releases) and install in claude.ai → Settings → Skills.
+
+| Skill | Trigger phrases |
+|-------|----------------|
+| `pdf-to-knowledge-graph` | "knowledge graph", "extract entities", "PDF to Cypher" |
+| `pdf-to-chunks` | "chunk document", "split for embeddings", "RAG chunks" |
+| `document-to-html` | "convert PDF to HTML", "render document", "make PDF browsable" |
+| `graph-db-admin` | "load into Neo4j", "Cypher query", "graph statistics" |
+| `chunks-to-pgvector` | "store in pgvector", "embed into PostgreSQL", "semantic search", "RAG with PostgreSQL" |
+
+---
+
+## Installation
+
+```bash
+# Core (knowledge graph + chunking + HTML)
+pip install malimgraph
+
+# With Neo4j support
+pip install "malimgraph[neo4j]"
+
+# With Apache AGE support
+pip install "malimgraph[age]"
+
+# With pgvector + OpenAI embeddings
+pip install "malimgraph[pgvector,openai]"
+
+# With pgvector + Voyage AI embeddings
+pip install "malimgraph[pgvector,voyage]"
+
+# With local embeddings (no API key needed)
+pip install "malimgraph[pgvector,local]"
+
+# Everything
+pip install "malimgraph[all]"
+```
+
+### Environment Variables
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-...      # Required for LLM extraction
+OPENAI_API_KEY=sk-...             # Required for OpenAI embeddings
+VOYAGE_API_KEY=pa-...             # Required for Voyage AI embeddings
+PGVECTOR_URI=postgresql://...     # PostgreSQL connection for pgvector
+NEO4J_URI=bolt://localhost:7687   # Neo4j connection
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=yourpassword
+AGE_CONNECTION_URI=host=...       # Apache AGE connection
+```
+
+---
+
+## Output Schema — `knowledge_graph.json`
+
+Every entity and relationship carries full citation provenance:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Stable hash ID: `e_` + MD5(type:label)[:8] |
+| `label` | string | Canonical entity name |
+| `type` | string | Entity type (Organization, Person, Date, …) |
+| `extraction_method` | enum | `rule` / `llm` / `hybrid` |
+| `confidence` | enum | `high` / `medium` / `low` |
+| `source_pages` | int[] | PDF page numbers where found |
+| `source_text` | string | Primary verbatim supporting quote |
+| `source_chunk_id` | string | Processing chunk ID |
+| `citations[]` | object[] | All supporting quotes with page refs |
+| `citation_count` | int | Stored as property in graph DBs |
+
+---
+
+## pgvector — Semantic Search Schema
+
+Chunks are stored with embeddings in PostgreSQL, enabling semantic search:
+
+```sql
+-- Find chunks most similar to a query
+SELECT chunk_text, source_file, page_numbers, heading_context,
+       1 - (embedding <=> '[...]'::vector) AS score
+FROM document_chunks
+ORDER BY embedding <=> '[...]'::vector
+LIMIT 10;
+
+-- Filter by document
+SELECT * FROM document_chunks
+WHERE document_id = 'annual_report_2024'
+ORDER BY embedding <=> '[...]'::vector LIMIT 5;
+```
+
+**Supported embedding providers:**
+
+| Provider | Default model | Dimension | API key |
+|----------|--------------|-----------|---------|
+| `openai` | `text-embedding-3-small` | 1536-d | `OPENAI_API_KEY` |
+| `voyage` | `voyage-3-large` | 1024-d | `VOYAGE_API_KEY` |
+| `local` | `all-MiniLM-L6-v2` | 384-d | none (CPU) |
+
+---
+
+## Database Setup
+
+### Neo4j
+```bash
+docker run -p 7474:7474 -p 7687:7687 \
+  -e NEO4J_AUTH=neo4j/yourpassword neo4j:latest
+```
+
+### Apache AGE (PostgreSQL)
+```bash
+docker run -p 5432:5432 -e POSTGRES_PASSWORD=secret apache/age:latest
+```
+
+### pgvector (PostgreSQL)
+```bash
+docker run -p 5432:5432 -e POSTGRES_PASSWORD=secret pgvector/pgvector:pg17
+```
+
+See [docs/database-setup.md](docs/database-setup.md) for full guides.
+
+---
+
+## Contributing
+
+1. Fork the repo
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Install dev deps: `pip install -e ".[dev]"`
+4. Run tests: `make test`
+5. Lint: `make lint`
+6. Submit a PR
+
+---
+
+## Credits
+
+Built by **[Malim AI Labs](https://ailabs.malim.my)** — AI-powered knowledge infrastructure for Southeast Asia.
+
+Malim AI Labs Social Enterprise (003827047-U) · Kuala Lumpur, Malaysia
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)