Skip to main content

AK-Primus v0.2.0

Intelligent token compression + routing MCP server with adaptive self-healing.

Every LLM request passes through a 7-layer pipeline selected by an 8-class hybrid classifier. The right compression and retrieval stack runs automatically for each request type. Nothing is applied blindly. The system gets cheaper the more it is used.

Request → Classifier → Router → [Cache | Memory | Compress | Search | Prompt-Opt] → LLM
                                                                                       ↓
                                                        Quality Score ← Response ←────┘
                                                              ↓
                                                    Adaptive Profile Update

What's new in 0.2.0

Area Change
Compression Expansion guard — never inflates token count; LLMLingua-1 uses GPT-2 (was 7B Llama)
Classifier ML hybrid (400-example logistic regression + rule fast-path); 88%+ accuracy on 275-scenario suite
Cache 3-level lookup: SHA-256 exact → ChromaDB HNSW ANN → SQLite cosine fallback
Memory L1 working memory + L2 episodic (session consolidation) + L3 semantic (cross-session ChromaDB)
DSPy 4 typed Signatures wired end-to-end; BootstrapFewShot + MIPRO2 with disk cache
Quality ROUGE-L + BERTScore + LLM-as-judge blended score; score_async() variant
Transport AK_PRIMUS_TRANSPORT=http — Starlette ASGI with /health, /ready, /metrics, SSE
Testing 84 pytest tests + 275-scenario benchmark suite with per-class accuracy CI gate

Architecture

ak-primus/
├── core/
│   └── ak_primus/
│       ├── classifier.py          # 8-class hybrid (rule + ML logistic regression)
│       ├── router.py              # Stack selection per request type
│       ├── server.py              # MCP server — 7 tools, stdio + HTTP/SSE
│       ├── layers/
│       │   ├── cache.py           # 3-level semantic cache (exact / HNSW / cosine)
│       │   ├── compression.py     # LLMLingua-2, LLMLingua-1, LongLLMLingua, SelectiveContext
│       │   ├── memory.py          # L1 working | L2 episodic | L3 semantic (ChromaDB)
│       │   ├── metrics.py         # tiktoken real token counting + cost accounting
│       │   ├── prompt_opt.py      # DSPy BootstrapFewShot + MIPRO2, OPRO, Medprompt
│       │   ├── quality.py         # ROUGE-L + BERTScore + LLM-as-judge + adaptive profile
│       │   └── search.py          # HyDE, RAPTOR, FLARE, ColBERT retrieval
│       ├── ml/
│       │   └── classifier_ml.py   # Embedding-based logistic regression (400 training examples)
│       └── storage/
│           ├── session_store.py   # SQLite WAL — sessions, cache, profiles, memory_facts
│           └── vector_store.py    # ChromaDB HNSW — semantic_cache + memory_facts
├── extension/
│   └── src/
│       ├── extension.ts           # VS Code extension entry point
│       ├── dashboard.ts           # Real-time metrics webview
│       └── mcp-client.ts          # MCP stdio bridge
├── tests/
│   ├── unit/                      # 70 unit tests (all layers)
│   └── integration/               # 14 integration + benchmark threshold tests
└── benchmarks/
    └── run_1200_scenarios.py      # 275-scenario accuracy + latency suite

7 MCP Tools

Tool Purpose
classify_request Detect request type + return recommended stack with expected token reduction
compress_history Apply compression stack to message history; returns compressed messages + savings
build_context HyDE / RAPTOR / FLARE retrieval-augmented context building
optimize_prompt DSPy BootstrapFewShot / OPRO / Medprompt prompt optimisation
get_token_report Real tiktoken metrics, cost savings, session stats
process_request Master pipeline: classify → cache → memory → compress → quality → adapt
report_quality Feed quality signal (0–1) back into adaptive compression profile

process_request — master pipeline

{
  "optimized_messages": [...],
  "tokens_before": 1240,
  "tokens_after": 487,
  "tokens_saved": 753,
  "savings_pct": 60.7,
  "request_type": "code",
  "confidence": 0.91,
  "quality_score": 0.876,
  "adapted_ratio": 0.382,
  "cache_hit": false,
  "session_id": "sess-abc123",
  "lifetime_savings": 41250
}

8 Request Types

Type Classifier Trigger Default Stack
code Code keywords + task verbs + C++/C# detection SelectiveContext → PrefixCache
rag_doc Documents present + QA-style question HyDE retrieval + LLMLingua-2
agent_session Multi-turn history + follow-up phrases WorkingMemory + L3 semantic
domain_expert Legal / medical / finance domain terms Medprompt + SelectiveContext
multi_hop "relationship", "compare", "trace" patterns RAPTOR + ChainOfThought
math Equations, proof, calculate keywords LLMLingua-1 (formula-aware)
fixed_template Long system prompt (>600 tokens) PrefixCache (no compression)
simple_qa Short conversational question Light SelectiveContext

Installation

# Minimal (core MCP server, no ML)
pip install ak-primus

# Full (all optional groups)
pip install "ak-primus[all]"

# From source
git clone https://github.com/ak-primus/ak-primus
pip install -e "core[all]"
Group Installs When to use
compress LLMLingua, transformers, torch Token compression
retrieval sentence-transformers, chromadb, scikit-learn Semantic cache + search
optimize dspy-ai, evaluate DSPy + ROUGE/BERTScore
http uvicorn, starlette HTTP/SSE transport
dev pytest, ruff, mypy Development

Quick Start

Claude Desktop

{
  "mcpServers": {
    "ak-primus": {
      "command": "ak-primus",
      "args": ["serve"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Docker

# stdio (MCP)
docker build -f Dockerfile.akprimus --target runtime -t ak-primus:0.2.0 .
docker run -i --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" -v ak_data:/data ak-primus:0.2.0

# HTTP/SSE with health probes
docker compose --profile http up
curl http://localhost:8080/health

Self-Healing Compression

The adaptive profile tunes compression ratios over time per (workspace, request_type):

quality ≥ 0.85  → compress more aggressively next time
quality < 0.70  → back off compression

After ~50 samples per type, the ratio converges to the Pareto-optimal point.

# Feed quality signal back after reviewing LLM response
curl -s http://localhost:8080/mcp -d '{"tool":"report_quality","quality_score":0.92,"request_type":"code"}'

Running Tests

pytest tests/ -q                              # 84 tests
python benchmarks/run_1200_scenarios.py --quick   # accuracy + latency

Benchmark (v0.2.0, 275 scenarios)

Class Accuracy
math 96%
fixed_template 100%
agent_session 92%
domain_expert 90%
multi_hop 90%
simple_qa 88%
code 82%
rag_doc 80%
Overall ~88%

Classifier latency: p50 < 1ms, p95 < 5ms (rule-based path, no model load).


Environment Variables

Variable Default Description
AK_PRIMUS_MODEL claude-sonnet-4-6 LLM model for DSPy / OPRO / judge
AK_PRIMUS_TRANSPORT stdio stdio or http
AK_PRIMUS_HOST 127.0.0.1 HTTP bind host
AK_PRIMUS_PORT 8080 HTTP bind port
AK_PRIMUS_DB ~/.ak_primus/store.db SQLite path
AK_PRIMUS_DSPY_CACHE ~/.ak_primus/dspy_cache DSPy program cache

License

MIT

Metadata

Release files for ak-primus 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ak-primus 0.2.1
File Size Uploaded Provenance Actions
ak_primus-0.2.1.tar.gz 121.9 kB Without provenance Details for ak_primus-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ak-primus 0.2.1
File Interpreter ABI Platform Actions
ak_primus-0.2.1-py3-none-any.whl Python 3 none any Details for ak_primus-0.2.1-py3-none-any.whl

Total release size: 249.2 kB

Release files / ak_primus-0.2.1.tar.gz

Download URL ak_primus-0.2.1.tar.gz
Size 121.9 kB
Tags Source
SHA-256 checksum
How to use checksums
c2271cea0db9e9b6c49d1ea7b92aaaf48648665007e9c8e6ef45affd4abd6cd4
BLAKE2b-256 checksum
How to use checksums
057838eb8b71d7d31edc508a3576130c4f9bb274dc4d8e332e14795220469659
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.12

Release files / ak_primus-0.2.1-py3-none-any.whl

Download URL ak_primus-0.2.1-py3-none-any.whl
Size 127.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6345ba1ba4f33de94ed7681d2c83fb91f86c2ba2e76c8b316550f0d6c2da542a
BLAKE2b-256 checksum
How to use checksums
d368fa713aca68af94b1411233ab8e02536b55fde1efab55141b7a71e61c121f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.12

Security for ak-primus 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page