lynkr 8.0.0 → 9.0.1

package/docs/toon-integration-spec.md

@@ -1,130 +0,0 @@
-# TOON Integration Spec (Lynkr Spike)
-
-Date: 2026-02-17  
-Branch: `codex/toon-integration-spike`  
-Status: Implemented behind flags (`TOON_ENABLED=false` by default).
-
-## 1) Goal
-
-Reduce prompt token usage for large structured JSON context while preserving current Lynkr routing, tool execution semantics, and reliability.
-
-## 2) Non-Goals
-
-1. Do not replace Lynkr routing/fallback logic.
-2. Do not change MCP/tool protocol behavior.
-3. Do not change provider request envelope formats.
-4. Do not require TOON for normal operation.
-
-## 3) Integration Strategy (Minimal, Reversible)
-
-1. Add a TOON adapter module (encode-only for prompt context).
-2. Apply TOON only to eligible large JSON blobs before they are inserted into model-visible context.
-3. Keep original JSON in memory/session for execution and audit; only prompt copy is compressed.
-4. Fail open: if TOON conversion fails, send original JSON unchanged.
-
-## 4) What We Will Compress
-
-Eligible inputs (all required):
-
-1. Payload is valid JSON object/array.
-2. Payload size exceeds threshold (for example, `TOON_MIN_BYTES`).
-3. Payload is read-only context for model comprehension (not protocol-critical).
-
-Primary targets:
-
-1. Large tool output summaries inserted into prompt context.
-2. Large search/result payloads injected for reasoning.
-3. Structured data snapshots used for analysis tasks.
-
-## 5) What We Will Never Compress
-
-Hard exclusions:
-
-1. Tool schemas/definitions (`tools`, `input_schema`, function signatures).
-2. Tool call argument payloads that are executed by systems.
-3. Provider request envelopes (`/v1/messages`, `/chat/completions` body schema fields).
-4. Protocol control fields (roles, stop reasons, tool IDs, request IDs).
-5. Stored canonical session payloads used for replay/debug/audit.
-
-Rule: if a payload is machine-validated/executed downstream, keep JSON.
-
-## 6) Config Flags (Default Safe)
-
-Proposed env flags:
-
-1. `TOON_ENABLED=false` (default off)
-2. `TOON_MIN_BYTES=4096` (only convert larger payloads)
-3. `TOON_FAIL_OPEN=true` (fallback to JSON on any TOON error)
-4. `TOON_LOG_STATS=true` (log before/after token estimate for observability)
-
-## 7) Verification Gates
-
-Before enabling:
-
-1. Existing unit tests pass unchanged.
-2. Existing MCP smoke passes (`find_tool`/`call_tool` path).
-
-With `TOON_ENABLED=true`:
-
-1. Prompt A/B benchmark still passes functionally.
-2. No regression in Task/subagent behavior.
-3. Data-heavy prompt shows token reduction vs baseline.
-4. No increase in protocol/tool-call errors.
-
-## 8) Rollback Rules
-
-Immediate rollback:
-
-1. Set `TOON_ENABLED=false`.
-2. Restart Lynkr service.
-
-Code rollback:
-
-1. Revert TOON integration commit(s) on this branch.
-2. Re-run unit + MCP smoke gates.
-
-## 9) Risks and Mitigations
-
-1. Risk: semantic drift from transformed payloads.
-   - Mitigation: apply only to read-only context, fail-open on error, keep canonical JSON.
-2. Risk: negligible gains on non-tabular/deeply nested payloads.
-   - Mitigation: threshold + eligibility checks; skip low-value payloads.
-3. Risk: harder debugging.
-   - Mitigation: log conversion stats and keep original payload for diagnostics.
-
-## 10) Stock Provider Validation (Ollama Cloud)
-
-Date: 2026-02-17
-
-Runtime under test:
-
-1. `MODEL_PROVIDER=ollama`
-2. `OLLAMA_ENDPOINT=http://127.0.0.1:11434`
-3. `OLLAMA_MODEL=glm-5:cloud`
-4. `TOON_MIN_BYTES=256`
-5. `TOON_FAIL_OPEN=true`
-6. `TOON_LOG_STATS=true`
-
-Probe used:
-
-1. Send a two-message request where the second message is a large JSON blob.
-2. Ask model to classify the next message as `JSON` vs `OTHER` based on first character.
-3. Run once with `TOON_ENABLED=false`, once with `TOON_ENABLED=true`.
-
-Observed results:
-
-1. `TOON_ENABLED=false`
-   - Reply: `JSON`
-   - Provider header: `x-lynkr-provider: ollama`
-   - TOON log entries: `0`
-2. `TOON_ENABLED=true`
-   - Reply: `OTHER`
-   - Provider header: `x-lynkr-provider: ollama`
-   - TOON log entries: `1`
-   - Logged conversion stats: `originalBytes=6416`, `compressedBytes=5854` (saved `562` bytes, `8.76%`)
-
-Conclusion:
-
-1. TOON gating works on stock Ollama cloud path (not moonshot-specific).
-2. Compression is applied only when flag-enabled.
-3. Provider routing remains unchanged (`ollama`) during TOON transformation.

package/documentation/README.md

@@ -1,101 +0,0 @@
-# Lynkr Documentation
-
-Welcome to the comprehensive documentation for Lynkr, the self-hosted Claude Code proxy with multi-provider support.
-
----
-
-## Getting Started
-
-New to Lynkr? Start here:
-
-- **[Installation Guide](installation.md)** - Complete installation instructions for all methods (npm, git clone, homebrew, Docker)
-- **[Provider Configuration](providers.md)** - Detailed setup for all 12+ supported providers (Databricks, Bedrock, OpenRouter, Ollama, llama.cpp, Azure OpenAI, Azure Anthropic, OpenAI, LM Studio, Moonshot AI, Z.AI, Vertex AI)
-- **[Quick Start Examples](installation.md#quick-start-examples)** - Copy-paste configurations to get running fast
-
----
-
-## IDE & CLI Integration
-
-Connect Lynkr to your development tools:
-
-- **[Claude Code CLI Setup](claude-code-cli.md)** - Configure Claude Code CLI to use Lynkr
-- **[Codex CLI Setup](codex-cli.md)** - Configure OpenAI Codex CLI with Lynkr (config.toml, wire_api, troubleshooting)
-- **[Cursor IDE Integration](cursor-integration.md)** - Full Cursor IDE setup with troubleshooting
-- **[Embeddings Configuration](embeddings.md)** - Enable @Codebase semantic search with 4 provider options (Ollama, llama.cpp, OpenRouter, OpenAI)
-
----
-
-## Core Features
-
-Understand Lynkr's capabilities:
-
-- **[Architecture & Features](features.md)** - System architecture, request flow, format conversion, and core capabilities
-- **[Routing & Model Tiering](routing.md)** - 4-tier model system, 15-dimension complexity scoring, agentic workflow detection, and cost optimization
-- **[Memory System](memory-system.md)** - Titans-inspired long-term memory with surprise-based filtering and decay
-- **[Token Optimization](token-optimization.md)** - Achieve 60-80% cost reduction through smart tool selection, prompt caching, and memory deduplication
-- **[Headroom Compression](headroom.md)** - 47-92% token reduction through intelligent context compression (Smart Crusher, CCR, LLMLingua)
-- **[Tools & Execution Modes](tools.md)** - Tool calling, server vs client execution, custom tool integration, MCP support
-
----
-
-## Deployment & Operations
-
-Production deployment guides:
-
-- **[Docker Deployment](docker.md)** - docker-compose setup with GPU support, volume management, and multi-service orchestration
-- **[Production Hardening](production.md)** - Circuit breakers, load shedding, Prometheus metrics, health checks, and observability
-- **[API Reference](api.md)** - Complete endpoint documentation, request/response formats, OpenAI compatibility layer
-
----
-
-## Support & Development
-
-Get help and contribute:
-
-- **[Troubleshooting Guide](troubleshooting.md)** - Common issues and solutions for all providers
-- **[FAQ](faq.md)** - Frequently asked questions about features, providers, and deployment
-- **[Testing Guide](testing.md)** - Running tests, writing new tests, CI/CD integration
-- **[Contributing Guide](contributing.md)** - How to contribute, code style, pull request process
-
----
-
-## External Resources
-
-- **[DeepWiki Documentation](https://deepwiki.com/vishalveerareddy123/Lynkr)** - AI-powered documentation search and Q&A
-- **[GitHub Repository](https://github.com/vishalveerareddy123/Lynkr)** - Source code and issue tracker
-- **[NPM Package](https://www.npmjs.com/package/lynkr)** - Official npm package
-- **[GitHub Discussions](https://github.com/vishalveerareddy123/Lynkr/discussions)** - Community Q&A and feature discussions
-
----
-
-## Quick Navigation by Topic
-
-### Setup & Configuration
-- [Installation](installation.md) | [Providers](providers.md) | [Claude Code](claude-code-cli.md) | [Codex CLI](codex-cli.md) | [Cursor](cursor-integration.md) | [Embeddings](embeddings.md)
-
-### Features & Optimization
-- [Features](features.md) | [Routing](routing.md) | [Memory System](memory-system.md) | [Token Optimization](token-optimization.md) | [Headroom](headroom.md) | [Tools](tools.md)
-
-### Deployment & Production
-- [Docker](docker.md) | [Production](production.md) | [API Reference](api.md)
-
-### Help & Development
-- [Troubleshooting](troubleshooting.md) | [FAQ](faq.md) | [Testing](testing.md) | [Contributing](contributing.md)
-
----
-
-## Documentation Structure
-
-This documentation is organized into focused guides:
-
-1. **Getting Started** - Installation and basic configuration
-2. **IDE & CLI Integration** - Connect to Claude Code, Codex CLI, and Cursor
-3. **Core Features** - Deep dives into capabilities
-4. **Deployment** - Production setup and operations
-5. **Support** - Troubleshooting and community resources
-
-Each guide is self-contained but cross-linked where relevant.
-
----
-
-**Need help?** Check [Troubleshooting](troubleshooting.md) or visit [GitHub Discussions](https://github.com/vishalveerareddy123/Lynkr/discussions).