Metadata-Version: 2.4
Name: schemap-tool
Version: 2.2.0
Summary: The AI Database Context Compiler for Claude Code, Cursor, Codex, and Copilot. Turn raw database structures into compact, AI-ready context maps.
Project-URL: Homepage, https://schemap-tool.pages.dev/
Project-URL: Documentation, https://schemap-tool.pages.dev/#features
Project-URL: Repository, https://github.com/alansyahmi/Schemap
Project-URL: Changelog, https://github.com/alansyahmi/Schemap/releases
Project-URL: Bug Tracker, https://github.com/alansyahmi/Schemap/issues
Author-email: Swarty <swarty@schemap.com>
License: MIT
Keywords: ai,claude,context-window,copilot,cursor,database,langchain-tools,mcp-server,schema-linter,schemap,text-to-sql,token-optimization
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: libsql
Requires-Dist: oracledb
Requires-Dist: psycopg[binary]>=3.1.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: pymysql
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: tiktoken>=0.6.0
Requires-Dist: watchdog>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: enrich
Requires-Dist: openai>=1.14.0; extra == 'enrich'
Description-Content-Type: text/markdown

<div align="center">
  <img src="docs/assets/Text_Logo__Dark_-removebg-preview2.png" alt="Schemap Logo — AI Database Context Compiler" width="320" />
</div>

<br/>

<div align="center">
  <h1>Stop AI Agents From Guessing Your Database.</h1>
  <p><strong>The Deterministic AI Database Context Compiler for Claude Code, Cursor, Codex, and Copilot.</strong></p>
</div>

<br/>

[![PyPI Version](https://img.shields.io/pypi/v/schemap-tool.svg)](https://pypi.org/project/schemap-tool/)
[![Python Version](https://img.shields.io/pypi/pyversions/schemap-tool.svg)](https://pypi.org/project/schemap-tool/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## Why Schemap?

Modern **AI coding agents** (Claude Code, Cursor, GitHub Copilot, Codex) struggle with complex production databases. 

Raw `pg_dump` SQL dumps waste **10,000+ tokens**, introduce noisy system metadata, cause broken multi-table JOINs, and force LLMs to guess business relationships.

**Schemap solves this.** Schemap is a deterministic CLI compiler that extracts database schemas, computes **AI Readiness Scores**, and generates compressed, token-optimized context maps (`schemap_database_context.md`, `CLAUDE.md`, `AGENTS.md`).

- **Token-optimized context:** Run `schemap benchmark` against your own schema to measure the raw-vs-compiled token footprint.
- **Local-first & deterministic:** Schema extraction and compilation run locally by default. Optional `--enrich` uses the configured OpenAI API, and licensed CI/CD usage performs an online license check.
- **Sub-2ms Compilation:** Compiles 200+ table database schemas in under 3 milliseconds.
- **Multi-Database Support:** PostgreSQL, MySQL, Turso / libSQL, SQLite, and Oracle.

---

## Benchmark: Raw SQL vs. Schemap Context

Compression varies by schema. Run `schemap benchmark` to measure the token footprint, relationship coverage, AI Readiness Score, and generation latency for your own database.

| Metric | Raw SQL Dump | Schemap AI Context | Difference |
| :--- | :--- | :--- | :--- |
| **Token Footprint** | Full raw schema estimate | **Compiled context** | Measured per schema |
| **Relationship Mapping** | Implicit / Scattered | **Explicit FK Graph** | **Instant JOIN Clarity** |
| **AI Readiness Score** | Unmeasured | **Diagnosed (e.g. 78/100)** | **Actionable Fix Roadmap** |
| **Agent Rule Files** | None | **CLAUDE.md & AGENTS.md** | **Native Agent Integration** |

---

## Installation & Quick Start

Install Schemap globally as a developer CLI via **`pipx`** (recommended) or `uv` / `pip`:

```bash
pipx install schemap-tool
```

> **Alternative package managers:**
> - **uv:** `uv tool install schemap-tool`
> - **pip:** `pip install schemap-tool`

### 1. Verify Installation
```bash
schemap --version
# Schemap 2.2.0
```

### 2. Upgrading Schemap
To upgrade an existing installation to the latest release:

```bash
pipx upgrade schemap-tool
```
*(Or `uv tool upgrade schemap-tool` / `pip install --upgrade schemap-tool`)*

### 3. Initialize Configuration
Generate a lightweight `schemap.yaml` config file with predefined domain mappings:

```bash
schemap init
```

Example `schemap.yaml` with domain mappings:
```yaml
database:
  connection_url: "sqlite:///test.db"

output:
  file_path: "./schemap_database_context.md"

domain:
  mappings:
    cust: "Customer"
    tx: "Transaction"
    inv: "Invoice"
    acct: "Account"
```

*For full boilerplate options (schema descriptions, table exclusions):*
```bash
schemap init --full
```

### 4. Run Database Health Diagnostic (`schemap doctor`)
Diagnose database readiness and identify missing foreign keys, undocumented tables, or ambiguous column names:

```bash
schemap doctor
```

*Output:*
```text
==================================================
 Schemap AI Database Health Check
==================================================
  Connection:            Connected (39 tables)
  Relationships Analyzed: 26
--------------------------------------------------
  AI Readiness Score:
  [###########---------] 53/100

  Top Issues Identified:
  - [Priority 1 - Missing Documentation] 39 tables lack descriptions/comments (-20 pts)
  - [Priority 2 - Disconnected Entities] 20 tables have no foreign keys (-7 pts)
  - [Priority 3 - Ambiguous Naming] 44 unresolved abbreviations detected (-20 pts)
--------------------------------------------------
 Recommendation: Run `schemap context` to generate AI-ready database context.
==================================================
```

### 5. Compile AI Database Context (`schemap context`)
Compile `schemap_database_context.md` containing relationship maps, central tables, and standard SQL JOIN snippets:

```bash
schemap context
```

### 4. Generate Agent Instruction Files (`schemap agents`)
Generate `CLAUDE.md` and `AGENTS.md` rules for your workspace:

```bash
schemap agents
```

### 5. Benchmark Context Efficiency (`schemap benchmark`)
Measure real-time token compression and compilation speed:

```bash
schemap benchmark
```

---

## Complete CLI Reference

| Command | Purpose | JSON Output Flag |
| :--- | :--- | :--- |
| `schemap doctor` | Onboarding health check & diagnostic | `schemap doctor --json` |
| `schemap context` | Compile `database_context.md` context map | `schemap context --format=json` |
| `schemap agents` | Generate `CLAUDE.md` and `AGENTS.md` | N/A |
| `schemap benchmark` | Measure raw SQL vs Schemap token savings & latency | `schemap benchmark --json` |
| `schemap score` | Analyze AI Readiness Score (0-100) & issue roadmap | `schemap score --json` |
| `schemap inspect` | Inspect raw database table & column metadata | `schemap inspect --json` |
| `schemap diff` | Track structural schema changes (`+`, `~`, `-`) | N/A |

---

## Supported Databases

- **PostgreSQL** (`postgresql://user:password@localhost:5432/my_db`)
- **Turso / Remote libSQL** (`libsql://...`)
- **Local SQLite** (`sqlite:///path/to/db.sqlite3`)
- **MySQL** (`mysql://user:password@localhost:3306/my_db`)
- **Oracle** (`oracle://user:password@localhost:1521/my_db`)

---

## CI/CD Integration & Licensing

Automate context map updates on every migration commit with GitHub Actions:

- **Free Tier:** Full local CLI for databases up to 100 tables, including inspection, scoring, context, diffs, benchmarks, and exports.
- **Pro Tier:** Unlimited tables, CI/CD GitHub Actions integration, and production workflow support.

### License management

Activate a purchased license globally with the schemap activate command.
Use schemap status --verify to check it against the license service, and schemap logout
to remove global credentials. The CLI resolves command-line, environment, global, and legacy
project configuration credentials in that order. CI/CD should provide SCHEMAP_LICENSE_KEY
through the repository secret store.

---

## Key Terms & Keywords (SEO)

`database context for AI agents` • `Claude Code database schema` • `Cursor rules database context` • `SQL token reduction` • `database schema to markdown` • `MCP database server` • `LangChain database tool` • `text-to-SQL prompt optimization` • `AI database schema generator`
