Skip to content

Commit fde69e0

Browse files
OgeonX-AiOgeonX-Ai
authored
chore: stabilize universal refiner local updates
Merged after local release:verify and all GitHub CI checks passed.
1 parent 59f3475 commit fde69e0

22 files changed

Lines changed: 267 additions & 47 deletions

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
# Runtime state and local databases
88
.refiner/
99
**/.refiner/
10+
.claude/worktrees/
11+
**/.claude/worktrees/
1012
.gemini/memory.json
1113
**/.gemini/memory.json
1214
**/.gemini/blackboard.json
@@ -19,6 +21,10 @@
1921
.env
2022
.env.*
2123
!.env.example
24+
.gemini-refiner.json
25+
.universal-refiner.json
26+
**/.gemini-refiner.json
27+
**/.universal-refiner.json
2228

2329
# Editor and OS artifacts
2430
.vscode/

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ That distinction matters because this repo is about credible system direction, n
4242

4343
```mermaid
4444
flowchart LR
45-
CLI["AI CLI\n(Claude / Cursor)"] -->|"stdio"| PI["PromptImprover\n(gemini-prompt-refiner)"]
45+
CLI["AI CLI\n(Claude / Cursor)"] -->|"stdio"| PI["PromptImprover\n(universal-refiner)"]
4646
subgraph internal["PromptImprover Engine"]
4747
RAG["RAG Snippets\n(FlexSearch)"]
4848
Memory["SQLite Memory\n(LocalBrain)"]
@@ -77,15 +77,15 @@ cd Promptimprover
7777
./build_and_install.sh
7878
```
7979

80-
Both installers perform a deterministic dependency install, run the full test suite, build the package, install it globally, and verify the `gemini-prompt-refiner` command. Add that command to your MCP client configuration. See the [Setup Guide](https://github.com/Coding-Autopilot-System/Promptimprover/wiki/Setup-Guide) for full configuration instructions.
80+
Both installers perform a deterministic dependency install, run the full test suite, build the package, install it globally, and verify the `universal-refiner` command. Add that command to your MCP client configuration. See the [Setup Guide](https://github.com/Coding-Autopilot-System/Promptimprover/wiki/Setup-Guide) for full configuration instructions.
8181

8282
For optional automatic pre-prompt linting and post-execution recording, see the [cross-CLI automation guide](./docs/cross-cli-automation.md). Claude Code and Gemini CLI expose the required lifecycle hooks. Codex currently requires MCP-first instructions or explicit helper invocation because its hook lifecycle does not transparently intercept each prompt.
8383

8484
## Local Semantic Model
8585

8686
PromptImprover uses a local OpenAI-compatible endpoint before optional MCP sampling. The safe defaults target `http://localhost:9000/v1`, use `gemma3:12b` first, and fall back to `gemma3:1b`. If neither local model nor MCP sampling is available, rule-based refinement continues without semantic output.
8787

88-
Override the defaults per repository with `.gemini-refiner.json`:
88+
Override the defaults per repository with `.universal-refiner.json`:
8989

9090
```json
9191
{

‎build_and_install.ps1‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@ try {
1313
npm install --global . --no-fund
1414

1515
$package = Get-Content .\package.json -Raw | ConvertFrom-Json
16-
$command = Get-Command gemini-prompt-refiner -ErrorAction Stop
16+
$command = Get-Command universal-refiner -ErrorAction Stop
1717
Write-Host "Prompt Refiner v$($package.version) installed: $($command.Source)" -ForegroundColor Green
1818
}
1919
finally {
2020
Pop-Location
21-
}
21+
}

‎build_and_install.sh‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,6 @@ npm test
1111
npm run build
1212
npm install --global . --no-fund
1313

14-
command -v gemini-prompt-refiner >/dev/null 2>&1
14+
command -v universal-refiner >/dev/null 2>&1
1515
VERSION=$(node -p "require('./package.json').version")
16-
printf 'Prompt Refiner v%s installed: %s\n' "$VERSION" "$(command -v gemini-prompt-refiner)"
16+
printf 'Prompt Refiner v%s installed: %s\n' "$VERSION" "$(command -v universal-refiner)"

‎docs/cross-cli-automation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ PromptImprover ships fail-open pre-prompt and post-execution helpers:
55
- `promptimprover-hook-pre` makes one latency-safe rule-based `lint_prompt` call, creates a trackable prompt ID, and injects advisory context. Interactive MCP linting continues to use semantic providers by default.
66
- `promptimprover-hook-post` records privacy-safe completion metadata with `record_agent_output`.
77

8-
Both commands read hook JSON from stdin, write JSON only to stdout, report failures to stderr, and always allow the client to continue. They start the same built MCP server used by `gemini-prompt-refiner`. Set `PROMPTIMPROVER_SERVER_PATH` only when testing a nonstandard build.
8+
Both commands read hook JSON from stdin, write JSON only to stdout, report failures to stderr, and always allow the client to continue. They start the same built MCP server used by `universal-refiner`. Set `PROMPTIMPROVER_SERVER_PATH` only when testing a nonstandard build.
99

1010
The helpers store only prompt ID, client name, and creation time in the OS temporary directory. They do not persist prompt or response bodies. Completion records contain output length rather than response text.
1111

‎docs/operator-testing.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ npm.cmd run acceptance:package-runtime
127127
Expected result:
128128

129129
```text
130-
Package runtime smoke passed: installed gemini-prompt-refiner-8.0.0 and served /api/health on <port>.
130+
Package runtime smoke passed: installed universal-refiner-8.0.0 and served /api/health on <port>.
131131
```
132132

133133
This catches missing production dependencies that are hidden by the local workspace.

‎docs/portfolio-proof.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This repo is best read as an enterprise-oriented MCP and prompt-governance proto
44

55
## Present-State Evidence
66

7-
- `universal-refiner/package.json` defines the active package as `gemini-prompt-refiner` and describes it as cross-CLI prompt refinement using an MCP server.
7+
- `universal-refiner/package.json` defines the active package as `universal-refiner` and describes it as cross-CLI prompt refinement using an MCP server.
88
- `universal-refiner/tests/` contains targeted Vitest coverage for detectors, history, lessons, memory, snippets, predictive refinement, timeline behavior, and server behavior.
99
- `build_and_install.ps1` installs the `universal-refiner` package globally as `prompt-refiner`, showing the intended operator entry point.
1010

‎universal-refiner/.gemini/settings.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"mcpServers": {
33
"prompt-refiner": {
4-
"command": "gemini-prompt-refiner",
4+
"command": "universal-refiner",
55
"args": []
66
}
77
}

‎universal-refiner/.universal-refiner.example.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"_comment_usage": "Copy this file to .universal-refiner.json in the universal-refiner directory. ConfigManager reads .universal-refiner.json at server startup; restart the MCP server after changes.",
3+
"_comment_fields": {
4+
"semantic.localEnabled": "true = LocalOpenAiProvider is tried first. false = skip local model entirely.",
5+
"semantic.baseUrl": "OpenAI-compatible /v1 base URL. Ollama default: http://localhost:11434/v1. LM Studio default: http://localhost:1234/v1.",
6+
"semantic.models": "Model names to try in order. First reachable model wins. Use exact Ollama model tags.",
7+
"semantic.mcpSamplingEnabled": "true = fall back to MCP sampling if local model fails or is unreachable.",
8+
"semantic.allowNonLoopback": "Set to true only if baseUrl is a non-loopback host. Leave false for localhost."
9+
},
10+
"semantic": {
11+
"localEnabled": true,
12+
"baseUrl": "http://localhost:11434/v1",
13+
"models": ["gemma3:12b", "gemma3"],
14+
"mcpSamplingEnabled": true,
15+
"timeoutMs": 120000,
16+
"temperature": 0.2
17+
}
18+
}

‎universal-refiner/README.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Universal Refiner
2+
3+
MCP server for prompt governance. Provides the `refine_prompt` tool that enriches
4+
prompts with project mandates, agentic context, and semantic refinement via a local
5+
model or MCP sampling fallback.
6+
7+
## Quick Start
8+
9+
```powershell
10+
# From the universal-refiner directory
11+
npm run build
12+
node dist/src/index.js
13+
```
14+
15+
The server registers as an MCP stdio transport. Global registration is managed by
16+
`scripts/operations/register-global.ps1`.
17+
18+
## Local Model Configuration
19+
20+
`refine_prompt` routes semantic refinement through `LocalOpenAiProvider` first (tier-0),
21+
then falls back to `McpSamplingProvider` if the local model is unreachable or returns an error.
22+
23+
Configuration is read from `.universal-refiner.json` in the working directory at **server startup**.
24+
After changing this file you must **restart the MCP server process** for the change to take effect.
25+
26+
### Wiring Ollama / Gemma
27+
28+
1. Start Ollama with the Gemma model:
29+
30+
```powershell
31+
ollama pull gemma3:12b
32+
ollama serve
33+
```
34+
35+
Ollama listens at `http://localhost:11434` by default.
36+
37+
2. Create `.universal-refiner.json` in `universal-refiner/`:
38+
39+
```json
40+
{
41+
"semantic": {
42+
"localEnabled": true,
43+
"baseUrl": "http://localhost:11434/v1",
44+
"models": ["gemma3:12b", "gemma3"],
45+
"mcpSamplingEnabled": true
46+
}
47+
}
48+
```
49+
50+
Copy `.universal-refiner.example.json` as a starting point.
51+
52+
3. Restart the MCP server.
53+
54+
### Config Fields
55+
56+
| Field | Type | Default | Description |
57+
|-------|------|---------|-------------|
58+
| `semantic.localEnabled` | boolean | `true` | Enable `LocalOpenAiProvider` as tier-0 |
59+
| `semantic.baseUrl` | string | `http://localhost:9000/v1` | OpenAI-compatible `/v1` base URL. **Ollama default is port 11434, not 9000.** |
60+
| `semantic.models` | string[] | `["gemma3:12b", "gemma3:1b"]` | Model names tried in order. First reachable model wins. |
61+
| `semantic.mcpSamplingEnabled` | boolean | `true` | Fall back to MCP sampling if local model fails |
62+
| `semantic.timeoutMs` | number | `120000` | Request timeout in milliseconds |
63+
| `semantic.temperature` | number | `0.2` | Sampling temperature (0–2) |
64+
| `semantic.allowNonLoopback` | boolean | `false` | Must be `true` for non-loopback base URLs (e.g., remote server). Leave `false` for localhost. |
65+
66+
> **Important:** The hardcoded default `baseUrl` is port 9000, not 11434. Ollama serves on
67+
> port 11434. Without a `.universal-refiner.json` overriding `baseUrl`, `LocalOpenAiProvider`
68+
> will silently fail to connect and fall through to MCP sampling.
69+
70+
### LM Studio
71+
72+
LM Studio exposes the same OpenAI-compatible `/v1` API. Use:
73+
74+
```json
75+
{
76+
"semantic": {
77+
"localEnabled": true,
78+
"baseUrl": "http://localhost:1234/v1",
79+
"models": ["gemma-3-12b-it"]
80+
}
81+
}
82+
```
83+
84+
### Provider Chain
85+
86+
When a `refine_prompt` call arrives:
87+
88+
1. `LocalOpenAiProvider` is tried first (if `localEnabled: true`).
89+
- Iterates `models` in order. On model failure, moves to the next model.
90+
- Returns `null` if all models fail (triggers fallback).
91+
2. `McpSamplingProvider` is tried next (if `mcpSamplingEnabled: true`).
92+
3. If both fail, `refine_prompt` returns the original prompt unchanged.
93+
94+
## Configuration File Reference
95+
96+
See `.universal-refiner.example.json` for an annotated template.
97+
98+
## Release Gate
99+
100+
```powershell
101+
npm run release:verify
102+
```
103+
104+
Runs build, 100% test coverage, MCP acceptance, semantic fallback, stress/soak, and audit checks.
105+
106+
## Security
107+
108+
- Never commit `.universal-refiner.json` if it contains sensitive values.
109+
Add it to `.gitignore` if you customise it beyond the example defaults.
110+
- `allowNonLoopback: false` (default) prevents the local provider from contacting
111+
non-loopback hosts, limiting the blast radius of a misconfigured `baseUrl`.

0 commit comments

Comments
 (0)