User Prompt
      ↓
Intent Guard           ← extracts & seals user intent (immutable)
      ↓
Prompt Classification  ← 7-layer multi-label classification (no keyword-only)
      ↓
Dependency Resolution  ← FallbackGraphEngine (AST, imports, symbols, git)
      ↓
Adaptive Context Expansion ← value-based: (relevance × confidence × proximity) / token_cost
      ↓
Precise Context Extraction ← line-level, never full files
      ↓
Prompt Optimization    ← compression + constraint injection (no creative rewriting)
      ↓
Semantic Validation    ← reject if similarity < 0.90
      ↓
Drift Detection        ← scope widening, hallucinated files, altered intent
      ↓
Prompt Compiler        ← final assembly for LLM
      ↓
AI Agent / LLM

pip install llm-prompt-optimizer

# With ML-powered semantic similarity (recommended):
pip install "llm-prompt-optimizer[ml]"

# With Anthropic adapter:
pip install "llm-prompt-optimizer[anthropic]"

# Everything:
pip install "llm-prompt-optimizer[all]"

from llm_prompt_optimizer import Optimizer

optimizer = Optimizer()

result = optimizer.optimize(
    prompt="Debug condition mismatch in the provided /path/repository/file. No code changes.",
    strict_mode=True,
    repo_root="/path/to/your/repo",
)

print(result.optimized_prompt.text)
print(f"Tokens: {result.optimized_prompt.token_estimate}")
print(f"Similarity: {result.optimized_prompt.semantic_similarity:.3f}")
print(f"Category: {result.classification.primary_category.value}")
print(f"Intent: {result.intent_lock.intent_summary}")
print(f"Drift clean: {result.drift_report.is_clean}")

# Optimize a prompt
llm-prompt-optimizer optimize "debug condition mismatch in path/to/folder"

# Strict mode (no dependency expansion)
llm-prompt-optimizer optimize "debug condition mismatch" --strict

# JSON output
llm-prompt-optimizer optimize "debug condition mismatch" --json

# Classify a prompt
llm-prompt-optimizer classify "implement /health endpoint in api/routes.py"

# Validate semantic similarity
llm-prompt-optimizer validate \
  --raw "debug condition mismatch" \
  --optimized "# Task\ndebug condition mismatch\n## Constraints\n- No code changes."

# Detect drift
llm-prompt-optimizer detect-drift \
  --raw "debug condition mismatch" \
  --optimized "debug condition mismatch. Also refactor everything."

# Estimate token cost
llm-prompt-optimizer estimate-cost "debug condition mismatch"

# Run benchmark suite
llm-prompt-optimizer benchmark

# Start MCP server (stdio — for Claude Desktop / Cursor)
llm-prompt-optimizer serve --transport stdio

# Start HTTP server
llm-prompt-optimizer serve --transport http --port 8765

# WebSocket server
llm-prompt-optimizer serve --transport websocket --port 8766

{
  "mcpServers": {
    "llm-prompt-optimizer": {
      "command": "llm-prompt-optimizer",
      "args": ["serve", "--transport", "stdio"],
      "env": {
        "LPO_STRICT_INTENT": "true",
        "LPO_SEMANTIC_THRESHOLD": "0.90",
        "LPO_LOG_LEVEL": "WARNING"
      }
    }
  }
}

{
  "mcpServers": {
    "lpo": {
      "command": "lpo",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

# 1) install the package
pip install llm-prompt-optimizer

# 2) register the MCP server in your host (see "MCP Server Integration" above)

# 3) install the auto-routing rule
llm-prompt-optimizer install-rules

# inspect / undo at any time
llm-prompt-optimizer rules-status
llm-prompt-optimizer uninstall-rules

<!-- BEGIN llm-prompt-optimizer v1 -->
…rule text…
<!-- END llm-prompt-optimizer -->

llm-prompt-optimizer rules-status

llm-prompt-optimizer install-rules    # safe to run multiple times

llm-prompt-optimizer uninstall-rules

llm-prompt-optimizer uninstall-rules --purge-unknown

llm-prompt-optimizer install-rules \
  [--host claude-code|cursor|continue] \  # repeat for multiple; default = auto-detect
  [--scope user-global|project] \         # default: user-global
  [--project-root <path>] \               # required if --scope project
  [--force] \                             # skip MCP-registration health check
  [--dry-run] \                           # show what would change, don't write
  [--json]                                # machine-readable output

llm-prompt-optimizer uninstall-rules \
  [--purge-unknown] \                     # sweep orphans not in the manifest
  [--dry-run] \
  [--json]

llm-prompt-optimizer rules-status [--json]

llm-prompt-optimizer install-rules --scope project --project-root .

# Start API server
uvicorn llm_prompt_optimizer.api.app:app --host 0.0.0.0 --port 8765

# Build and run the API server
docker compose up optimizer-api

# Run tests
docker compose --profile test up optimizer-test

# MCP stdio mode (for agent integration)
docker compose --profile mcp up optimizer-mcp

# Policy
LPO_STRICT_INTENT=true
LPO_SEMANTIC_THRESHOLD=0.90
LPO_TOKEN_BUDGET=8000

# MCP Server
LPO_MCP_HOST=127.0.0.1
LPO_MCP_PORT=8765
LPO_MCP_TRANSPORT=stdio

# Logging
LPO_LOG_LEVEL=INFO

# Graph Provider (optional — uses FallbackGraphEngine by default)
LPO_GRAPH_PROVIDER=

from llm_prompt_optimizer import Optimizer, OptimizerConfig
from llm_prompt_optimizer.config.settings import PolicyConfig, TokenBudgetConfig

config = OptimizerConfig()
config.policy.strict_intent_mode = True
config.policy.semantic_similarity_threshold = 0.90
config.policy.allow_scope_expansion = "controlled"
config.token_budget.default_budget_tokens = 8000
config.token_budget.adaptive_budgeting = True

optimizer = Optimizer(config=config)

from llm_prompt_optimizer.plugins.system import PolicyPlugin, OptimizerPlugin, PluginSystem
from llm_prompt_optimizer import Optimizer

class MyEnterprisePolicy(PolicyPlugin):
    name = "enterprise_policy"
    version = "1.0.0"
    plugin_type = "policy"

    def initialize(self, config):
        self.blocked_terms = config.get("blocked_terms", [])

    def evaluate(self, context):
        violations = []
        intent = context.get("intent_lock")
        if intent:
            for term in self.blocked_terms:
                if term in intent.intent_summary.lower():
                    violations.append(f"Blocked term: {term}")
        return violations

plugins = PluginSystem()
plugins.register(MyEnterprisePolicy(), config={"blocked_terms": ["prod_db"]})

optimizer = Optimizer(plugin_system=plugins)

context_value_score = (relevance × confidence × execution_proximity) / token_cost

{
  "file": "utils/condition.py",
  "start_line": 61,
  "end_line": 95,
  "symbol": "calculate_condition",
  "confidence": 0.93,
  "reason": "Symbol definition: calculate_condition"
}

python benchmarks/run_benchmarks.py
python benchmarks/run_benchmarks.py --json
python benchmarks/run_benchmarks.py --case debug_condition_mismatch

# Clone
git clone https://github.com/your-org/llm-prompt-optimizer
cd llm-prompt-optimizer

# Install in dev mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run tests with coverage
pytest tests/ --cov=llm_prompt_optimizer --cov-report=html

# Lint
ruff check llm_prompt_optimizer/

# Type check
mypy llm_prompt_optimizer/

# Run benchmarks
python benchmarks/run_benchmarks.py

llm-prompt-optimizer/
├── llm_prompt_optimizer/
│   ├── core/
│   │   ├── intent_guard/         # IntentGuard — locks user intent
│   │   ├── classifier/           # Multi-layer prompt classification
│   │   ├── dependency_resolution/ # DependencyResolver orchestrator
│   │   ├── adaptive_context_expansion/ # Value-based expansion
│   │   ├── precise_context/      # Line-level extraction
│   │   ├── optimizer/            # PromptOptimizer + PromptCompiler
│   │   ├── semantic_validator/   # Similarity validation
│   │   ├── drift_detection/      # Drift detector
│   │   ├── fallback_graph/       # Standalone AST graph engine
│   │   ├── token_budget/         # Token budget management
│   │   ├── policy/               # PolicyEngine
│   │   ├── telemetry/            # TelemetryEngine + AuditLogger
│   │   └── benchmarking/         # BenchmarkEngine
│   ├── adapters/                 # LLM adapters (Anthropic, OpenAI, Ollama…)
│   ├── mcp_server/               # MCP server (stdio, HTTP, WebSocket, IPC)
│   ├── installer/                # Host-rule install/uninstall (CLAUDE.md, .cursorrules, …)
│   ├── api/                      # FastAPI REST endpoints
│   ├── sdk/                      # Optimizer SDK (main entry point)
│   ├── plugins/                  # Plugin system
│   ├── models/                   # Typed data models
│   ├── config/                   # Configuration
│   └── utils/                    # Helpers, token estimation, AST tools
├── examples/
│   ├── claude_mcp/               # Claude Desktop MCP integration
│   ├── langchain/                # LangChain integration
│   └── local_agents/             # Custom plugin examples
├── tests/
│   ├── core/                     # Unit tests per component
│   ├── integration/              # Full pipeline + MCP tests
│   └── api/                      # API endpoint tests
├── benchmarks/                   # Benchmark runner + cases
├── docs/                         # Extended documentation
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── .env.example