codemap-core 0.3.0__tar.gz → 0.3.1__tar.gz

{codemap_core-0.3.0 → codemap_core-0.3.1}/CHANGELOG.md

@@ -8,6 +8,50 @@ During `0.x`, MINOR may introduce breaking changes — they will be marked `BREA
 
 ## [Unreleased]
 
+## [0.3.1] — 2026-06-25
+
+Quick follow-up to 0.3.0. Lockstep version-only bump across all **20
+packages** to keep the family in sync; the only source change is in
+`codemap-aimemory`.
+
+### `codemap-aimemory` — LLM CLI configuration
+
+* New subcommand group **`codemap llm config`** (registered through the
+  `codemap.cli_commands` entry-point group introduced in 0.3.0):
+  * `codemap llm config set api-key <key>` — persist to
+    `~/.config/codemap/llm.yaml` (or `$XDG_CONFIG_HOME/codemap/llm.yaml`),
+    written `chmod 600` because it carries a credential.
+  * `codemap llm config set base-url <url>` / `model` / `backend`.
+  * `codemap llm config unset <key>` — clear one field; the on-disk
+    file only contains non-`None` values.
+  * `codemap llm config show` — print the effective config with one of
+    `[env]` / `[file]` / `[default]` annotated per field; API keys are
+    masked.
+  * `codemap llm config path` — print the config file location.
+* `codemap enrich` resolution order is now (first non-empty wins):
+  CLI flag → env var → file config (new in 0.3.1) → built-in defaults.
+* Behavioural reminder: **API key is the LLM on/off switch.**
+  `codemap index` never calls any LLM; `codemap enrich` without a key
+  errors out cleanly, never silently. No background LLM traffic.
+
+### Documentation
+
+* README + README.zh-CN: new "Output formats" section documenting every
+  file under `.codemap/` and `.ai-memory/` (kind, shape, who consumes it).
+* README + README.zh-CN: new "LLM configuration" section with the
+  three-source resolution order and a Chinese / open-source LLM endpoint
+  cheatsheet (DeepSeek, GLM, MiniMax, Kimi, Qwen, MiMo, Ollama, native
+  Anthropic) — all use `--backend openai` with their own `base-url`.
+* INSTALL: bump heading and mention the new CLI.
+
+### Plugin tests
+
+19 new unit tests in `codemap-aimemory` covering: XDG path resolution,
+load / save / unset round-trip, `chmod 600` on save, corrupt-YAML
+graceful fallback, dash-vs-underscore key aliasing, CLI set / show /
+unset / path, source-annotation correctness in `show`. Plugin test
+total: 38 → 57. Other plugins unchanged.
+
 ## [0.3.0] — 2026-06-25
 
 The four-layer-memory-model L1 release. The plugin family grows from

{codemap_core-0.3.0 → codemap_core-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codemap-core
-Version: 0.3.0
+Version: 0.3.1
 Summary: Language-neutral code index for AI agents
 Project-URL: Homepage, https://github.com/qxbyte/codemap
 Project-URL: Repository, https://github.com/qxbyte/codemap
@@ -78,8 +78,10 @@ mappings, and cross-file relationships without grepping the entire
 project. Indexing is static, fast, and reproducible — no LLM in the
 index path.
 
-**Status**: 0.2.0 stable. Installable from PyPI as `codemap-core`
-plus 17 `codemap-<lang>` plugins.
+**Status**: 0.3.1 stable. Installable from PyPI as `codemap-core`
+plus 17 `codemap-<lang>` plugins + 2 framework / output plugins
+(`codemap-mybatis`, `codemap-aimemory`, added in 0.3.0; 0.3.1
+adds the `codemap llm config` CLI).
 
 > 👉 **In a hurry?** The [`INSTALL.md`](./INSTALL.md) guide is the
 > definitive walkthrough — it covers `pipx` / `uv tool` / `pip`,
@@ -315,6 +317,14 @@ codemap routes                          # HTTP routes from the http_route bridge
 
 # Machine-readable output: all commands take --json
 codemap --json callers '<symbol-id>'
+
+# Optional LLM enrichment (codemap-aimemory plugin, 0.3.0+)
+codemap llm config set api-key sk-xxx       # persist to ~/.config/codemap/llm.yaml
+codemap llm config set base-url https://api.deepseek.com/v1
+codemap llm config set model deepseek-chat
+codemap llm config show                     # masked-key view + value source
+codemap enrich .                            # fills .ai-memory/enrichment/*.yml
+codemap enrich . --dry-run                  # count fn/method symbols, no API call
 ```
 
 Exit codes follow `sysexits.h` (ADR-005); see
@@ -322,6 +332,103 @@ Exit codes follow `sysexits.h` (ADR-005); see
 
 ---
 
+## Output formats
+
+`codemap index` produces two parallel directories at the project root:
+
+```
+<project>/
+├── .codemap/        ← deterministic, machine-friendly index (queried by `codemap …`)
+└── .ai-memory/      ← four-layer-memory-model L1 layout (consumed by AI agents)
+```
+
+### `.codemap/` — deterministic index (JSON, 7 files)
+
+| File | Contents |
+|---|---|
+| `symbols.json` | All symbols keyed by `SymbolID`. Each entry: `kind`, `language`, `file`, `range`, `signature`, `annotations`, `confidence`, `extra` (per-language metadata: `pending_calls`, `http_route`, `supertypes`, `imports`, `params`, `return_type`, `change_count_90d`, …). |
+| `edges.json` | Directed relations: `calls` / `extends` / `implements` / `overrides` / `references` / `routes_to` / `maps_to` / `imports` / `accesses_table`. Each carries `confidence` ∈ {`high`, `medium`, `low`}. |
+| `routes.json` | HTTP routes minted by the `http_route` bridge from `extra["http_route"]`. |
+| `aliases.json` | Synthetic intermediate ↔ real symbol links (e.g. route → handler). |
+| `manifest.json` | Project root, `codemap_version`, registered indexers + bridges + their versions, per-file sha256 / mtime / language. |
+| `diagnostics.json` | Indexer / bridge warnings collected during the run (severity + code + message + producer). |
+| `.lock` | Cross-process write lock; do not edit. |
+
+### `.ai-memory/` — four-layer memory L1 (YAML, 6 files)
+
+Generated by `codemap-aimemory` when installed. AI agents read this
+tree directly. Stable `entity_id` slugs are derived from the SCIP
+`SymbolID` (e.g. `fn-calcPrice` / `cls-OrderService` / `tbl-sf_coupon`).
+
+```
+.ai-memory/
+├── entities/
+│   ├── functions.yml      fn-* / cls-* with calls / called_by /
+│   │                      related_tables / signature / line_range /
+│   │                      confidence / change_count_90d / business_meaning
+│   ├── tables.yml         tbl-* table entities
+│   └── files.yml          file-* file entries
+├── relations/
+│   ├── call-graph.yml      `{from, to, type=calls, confidence}`
+│   ├── table-relations.yml `{from, to, type=accesses_table, confidence}`
+│   └── rule-constraints.yml empty placeholder (L2 owns)
+└── enrichment/             OPTIONAL: LLM-generated explanations
+    └── <sha1[:12]>.yml     `{symbol_id, business_meaning,
+                              related_rules, confidence:"llm",
+                              source_model, generated_at}`
+```
+
+Two-hop fan-out: when a Java method `maps_to` a `sql_mapping` that
+`accesses_table` T, T automatically lands on the method's
+`related_tables`. So `fn-selectByUser.related_tables = [tbl-sf_coupon]`
+without the agent needing to follow the chain itself.
+
+---
+
+## LLM configuration (optional)
+
+The core index is **always LLM-free** — `codemap index` never calls any
+LLM. Only the optional `codemap enrich` command in `codemap-aimemory`
+writes the `enrichment/` overlay, and only when **you** invoke it. The
+existence of an API key is the on/off switch: without one, `codemap
+enrich` exits with a clear error and no network call is made.
+
+Three configuration sources, **first non-empty wins**:
+
+1. **CLI flag** — `--api-key`, `--base-url`, `--model`, `--backend`
+2. **Environment variable** — `CODEMAP_LLM_API_KEY` (also
+   `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`); `CODEMAP_LLM_BASE_URL`
+   (also `OPENAI_BASE_URL`, `ANTHROPIC_BASE_URL`);
+   `CODEMAP_LLM_MODEL`; `CODEMAP_LLM_BACKEND`
+3. **Persistent file config** — `~/.config/codemap/llm.yaml` (managed
+   by `codemap llm config set/unset/show`; written `chmod 600`)
+4. Built-in defaults — backend `openai`, model `gpt-4o-mini`
+
+### Common provider endpoints (OpenAI-compatible — `--backend openai`)
+
+| Provider | Model example | Base URL |
+|---|---|---|
+| OpenAI | `gpt-4o-mini` | `https://api.openai.com/v1` *(default)* |
+| DeepSeek | `deepseek-chat` | `https://api.deepseek.com/v1` |
+| 智谱 GLM | `glm-4-flash` | `https://open.bigmodel.cn/api/paas/v4/` |
+| MiniMax | `abab6.5s-chat` | `https://api.minimax.chat/v1` |
+| 月之暗面 Kimi | `moonshot-v1-8k` | `https://api.moonshot.cn/v1` |
+| 阿里通义 | `qwen-plus` | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| 小米 MiMo | `mimo-large` | *(per vendor docs; OpenAI-compatible)* |
+| Ollama (local) | `llama3` | `http://localhost:11434/v1` — use `--backend ollama` (key not needed) |
+| Anthropic native | `claude-sonnet-4-5` | *(use `--backend anthropic`; requires `anthropic` SDK via `pip install codemap-aimemory[llm]`)* |
+
+Example with DeepSeek:
+
+```bash
+codemap llm config set base-url https://api.deepseek.com/v1
+codemap llm config set api-key sk-xxx
+codemap llm config set model deepseek-chat
+codemap enrich .
+```
+
+---
+
 ## Configuration
 
 Project-level configuration lives at `.codemap/config.yaml` (committed

{codemap_core-0.3.0 → codemap_core-0.3.1}/README.md

@@ -11,8 +11,10 @@ mappings, and cross-file relationships without grepping the entire
 project. Indexing is static, fast, and reproducible — no LLM in the
 index path.
 
-**Status**: 0.2.0 stable. Installable from PyPI as `codemap-core`
-plus 17 `codemap-<lang>` plugins.
+**Status**: 0.3.1 stable. Installable from PyPI as `codemap-core`
+plus 17 `codemap-<lang>` plugins + 2 framework / output plugins
+(`codemap-mybatis`, `codemap-aimemory`, added in 0.3.0; 0.3.1
+adds the `codemap llm config` CLI).
 
 > 👉 **In a hurry?** The [`INSTALL.md`](./INSTALL.md) guide is the
 > definitive walkthrough — it covers `pipx` / `uv tool` / `pip`,
@@ -248,6 +250,14 @@ codemap routes                          # HTTP routes from the http_route bridge
 
 # Machine-readable output: all commands take --json
 codemap --json callers '<symbol-id>'
+
+# Optional LLM enrichment (codemap-aimemory plugin, 0.3.0+)
+codemap llm config set api-key sk-xxx       # persist to ~/.config/codemap/llm.yaml
+codemap llm config set base-url https://api.deepseek.com/v1
+codemap llm config set model deepseek-chat
+codemap llm config show                     # masked-key view + value source
+codemap enrich .                            # fills .ai-memory/enrichment/*.yml
+codemap enrich . --dry-run                  # count fn/method symbols, no API call
 ```
 
 Exit codes follow `sysexits.h` (ADR-005); see
@@ -255,6 +265,103 @@ Exit codes follow `sysexits.h` (ADR-005); see
 
 ---
 
+## Output formats
+
+`codemap index` produces two parallel directories at the project root:
+
+```
+<project>/
+├── .codemap/        ← deterministic, machine-friendly index (queried by `codemap …`)
+└── .ai-memory/      ← four-layer-memory-model L1 layout (consumed by AI agents)
+```
+
+### `.codemap/` — deterministic index (JSON, 7 files)
+
+| File | Contents |
+|---|---|
+| `symbols.json` | All symbols keyed by `SymbolID`. Each entry: `kind`, `language`, `file`, `range`, `signature`, `annotations`, `confidence`, `extra` (per-language metadata: `pending_calls`, `http_route`, `supertypes`, `imports`, `params`, `return_type`, `change_count_90d`, …). |
+| `edges.json` | Directed relations: `calls` / `extends` / `implements` / `overrides` / `references` / `routes_to` / `maps_to` / `imports` / `accesses_table`. Each carries `confidence` ∈ {`high`, `medium`, `low`}. |
+| `routes.json` | HTTP routes minted by the `http_route` bridge from `extra["http_route"]`. |
+| `aliases.json` | Synthetic intermediate ↔ real symbol links (e.g. route → handler). |
+| `manifest.json` | Project root, `codemap_version`, registered indexers + bridges + their versions, per-file sha256 / mtime / language. |
+| `diagnostics.json` | Indexer / bridge warnings collected during the run (severity + code + message + producer). |
+| `.lock` | Cross-process write lock; do not edit. |
+
+### `.ai-memory/` — four-layer memory L1 (YAML, 6 files)
+
+Generated by `codemap-aimemory` when installed. AI agents read this
+tree directly. Stable `entity_id` slugs are derived from the SCIP
+`SymbolID` (e.g. `fn-calcPrice` / `cls-OrderService` / `tbl-sf_coupon`).
+
+```
+.ai-memory/
+├── entities/
+│   ├── functions.yml      fn-* / cls-* with calls / called_by /
+│   │                      related_tables / signature / line_range /
+│   │                      confidence / change_count_90d / business_meaning
+│   ├── tables.yml         tbl-* table entities
+│   └── files.yml          file-* file entries
+├── relations/
+│   ├── call-graph.yml      `{from, to, type=calls, confidence}`
+│   ├── table-relations.yml `{from, to, type=accesses_table, confidence}`
+│   └── rule-constraints.yml empty placeholder (L2 owns)
+└── enrichment/             OPTIONAL: LLM-generated explanations
+    └── <sha1[:12]>.yml     `{symbol_id, business_meaning,
+                              related_rules, confidence:"llm",
+                              source_model, generated_at}`
+```
+
+Two-hop fan-out: when a Java method `maps_to` a `sql_mapping` that
+`accesses_table` T, T automatically lands on the method's
+`related_tables`. So `fn-selectByUser.related_tables = [tbl-sf_coupon]`
+without the agent needing to follow the chain itself.
+
+---
+
+## LLM configuration (optional)
+
+The core index is **always LLM-free** — `codemap index` never calls any
+LLM. Only the optional `codemap enrich` command in `codemap-aimemory`
+writes the `enrichment/` overlay, and only when **you** invoke it. The
+existence of an API key is the on/off switch: without one, `codemap
+enrich` exits with a clear error and no network call is made.
+
+Three configuration sources, **first non-empty wins**:
+
+1. **CLI flag** — `--api-key`, `--base-url`, `--model`, `--backend`
+2. **Environment variable** — `CODEMAP_LLM_API_KEY` (also
+   `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`); `CODEMAP_LLM_BASE_URL`
+   (also `OPENAI_BASE_URL`, `ANTHROPIC_BASE_URL`);
+   `CODEMAP_LLM_MODEL`; `CODEMAP_LLM_BACKEND`
+3. **Persistent file config** — `~/.config/codemap/llm.yaml` (managed
+   by `codemap llm config set/unset/show`; written `chmod 600`)
+4. Built-in defaults — backend `openai`, model `gpt-4o-mini`
+
+### Common provider endpoints (OpenAI-compatible — `--backend openai`)
+
+| Provider | Model example | Base URL |
+|---|---|---|
+| OpenAI | `gpt-4o-mini` | `https://api.openai.com/v1` *(default)* |
+| DeepSeek | `deepseek-chat` | `https://api.deepseek.com/v1` |
+| 智谱 GLM | `glm-4-flash` | `https://open.bigmodel.cn/api/paas/v4/` |
+| MiniMax | `abab6.5s-chat` | `https://api.minimax.chat/v1` |
+| 月之暗面 Kimi | `moonshot-v1-8k` | `https://api.moonshot.cn/v1` |
+| 阿里通义 | `qwen-plus` | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| 小米 MiMo | `mimo-large` | *(per vendor docs; OpenAI-compatible)* |
+| Ollama (local) | `llama3` | `http://localhost:11434/v1` — use `--backend ollama` (key not needed) |
+| Anthropic native | `claude-sonnet-4-5` | *(use `--backend anthropic`; requires `anthropic` SDK via `pip install codemap-aimemory[llm]`)* |
+
+Example with DeepSeek:
+
+```bash
+codemap llm config set base-url https://api.deepseek.com/v1
+codemap llm config set api-key sk-xxx
+codemap llm config set model deepseek-chat
+codemap enrich .
+```
+
+---
+
 ## Configuration
 
 Project-level configuration lives at `.codemap/config.yaml` (committed

{codemap_core-0.3.0 → codemap_core-0.3.1}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "hatchling.build"
 # (`codemap-java`, `codemap-go`, …) — this is the engine; the others
 # are language adapters.
 name = "codemap-core"
-version = "0.3.0"
+version = "0.3.1"
 description = "Language-neutral code index for AI agents"
 readme = "README.md"
 license = { file = "LICENSE" }