limitations.md

Entroly Limitations

Entroly is a local context control plane. It can reduce what you send, preserve more useful context under a budget, and surface verification signals. It does not make provider calls free, guarantee perfect answers, or override provider terms.

What Entroly Does Not Guarantee

• No universal savings guarantee. Savings depend on repo size, prompt shape, model context window, tool-output volume, and how often provider prefix caches hit.
• No zero quality-loss guarantee. Benchmarks measure retention on specific datasets and budgets; some workloads lose accuracy when the budget is too tight.
• No provider certification. Entroly works through documented local proxy, SDK, MCP, and wrapper paths, but each provider account remains subject to that provider's terms, data policy, model limits, and rate limits.
• No fully local cloud inference. Entroly indexes and selects locally, but when you use a cloud LLM API, the optimized prompt still goes to that provider.
• No automatic legal/compliance decision. docs/provider-compliance.md is an engineering checklist, not legal advice.
• No perfect hallucination detection. WITNESS/STAVE/EICV are local verifiers with measured false positives and false negatives. Use strict mode only when conservative suppression is acceptable.
• No exact provider image token guarantee for every model. Entroly estimates image tokens from published provider formulas where available; provider usage metadata or token-count APIs remain the source of truth.

Best-Fit Workloads

• Large or medium repos where raw context does not fit.
• Chatty coding agents where repeated prefixes and old tool outputs dominate cost.
• Teams that want local preflight measurement before changing provider traffic.
• Workflows where evidence-grounded verification is useful even when it is not perfect.

Poor-Fit Workloads

• Tiny prompts that already fit comfortably.
• One-off creative tasks where all context is intentionally unstructured.
• Tasks where any compression, selection, or image downscaling is unacceptable.
• Provider/tool configurations whose terms do not permit local proxies or custom endpoints.

How To Measure Honestly

Use local commands first:

entroly simulate --budget 4096
entroly perf --budget 4096 --json
entroly verify-claims

These commands do not call an LLM. They estimate local context reduction and optimizer latency. They are not a bill guarantee because they exclude output tokens, provider cache hit rates, retries, tool-use overhead, and model-specific pricing changes.

For live traffic, inspect response headers such as:

• X-Entroly-Action
• X-Entroly-Outcome
• X-Entroly-Transform-Compliant
• X-Entroly-Tokens-Saved-Pct
• X-Entroly-Cache-Hit-Rate

Provider invoices and provider usage metadata remain the billing source of truth.

Session Rescue and Cache Safety

Session rescue runs only for traffic routed through entroly proxy. It does not edit a host application's stored transcript, terminate the host's loop, or recover a session that never sends another request through Entroly.

The guard preserves ordinary user messages and recent turns. If old recoverable tool output is insufficient to bring a request under the safety watermark, the proxy returns an actionable 413 rather than silently deleting user evidence or forwarding a likely provider rejection.

Recovery is local, not magic: the session-rescue JSON store contains the full original tool output in plaintext. Losing or deleting that store removes Entroly's recovery path. Protect it with filesystem permissions, source-control exclusions, retention policy, and backups appropriate for the underlying data.

Live-zone layout and exact context matching improve prefix stability but do not guarantee provider cache hits or savings. Provider thresholds, TTL, pricing, routing, and account behavior remain authoritative. See runaway-session rescue and prompt-cache safety.

Image Inputs

Image optimization is opt-in. The default behavior is to preserve image bytes and only report estimates/recommendations. When enabled, Entroly gates any image rewrite on estimated token savings and a quality floor.

References for current formulas and token-count behavior:

• OpenAI image token accounting: https://platform.openai.com/docs/guides/images-vision
• Anthropic vision image sizing and rough token estimate: https://docs.anthropic.com/en/docs/build-with-claude/vision
• Gemini multimodal token counting: https://ai.google.dev/gemini-api/docs/tokens

Context Receipts

Context Receipts are an audit trail for local context selection. They improve inspectability, but they do not prove that the selected context is complete or that an answer is legally, financially, medically, or operationally correct. Each receipt includes a deterministic risk_summary so these boundaries are visible in the artifact instead of hidden in marketing copy.

• Dependency detection is heuristic. The MVP catches obvious defined terms and references such as as defined in, subject to, pursuant to, see section, exhibits, schedules, addenda, and clauses. It can miss implicit dependencies, unusual drafting styles, scanned/OCR errors, tables, footnotes, and jurisdiction-specific language.
• BM25-style retrieval is lexical. The semantic/vector scorer and reranker are extension points, but the local default does not claim embedding-level recall.
• Page numbers are preserved only when the input text exposes page markers. PDF layout reconstruction and OCR are outside this MVP path.
• Fingerprints make a receipt reproducible for the ingested text bytes. They do not certify that the source corpus was complete, authorized, or unchanged outside the files Entroly saw.
• Omitted-context warnings are conservative signals, not exhaustive proof of all missing evidence.
• selection_certificate proves feasibility and, for bounded frontiers, optimality only for Entroly's declared internal retrieval-score objective. It does not prove evidence recall, answer correctness, or model utilization. Larger frontiers carry a conservative relaxed regret bound rather than an exact-optimality claim.
• risk_summary.coverage_score and review_level are local heuristics derived from chunk coverage, token coverage, unresolved dependencies, and omitted relevant chunks. They are triage signals, not correctness probabilities.
• Human review is required for contracts, compliance, policy, and audit use cases. Use receipts to inspect evidence and risk, not as a substitute for professional review.

Compliance Checklist

Before production use:

1. Confirm your provider and tool terms permit the chosen proxy, wrapper, or SDK path.
2. Run entroly doctor --privacy.
3. Run provider-shape tests for the APIs you use.
4. Start in audit/observe mode, inspect headers, then enable stronger mutation paths deliberately.
5. Keep benchmark claims tied to committed artifacts and dated reproduction commands.