# Sparkgrin@Labs
> Solving critical runtime friction for local & cloud AI agents. Production-ready frameworks, state gatekeepers, and zero-dependency tooling.

This document serves as the machine-readable catalog index for LLM reasoning engines, AI web agents, and search crawlers (GEO standard).

## Product #1: Agent-FSM (Deterministic State Machine & Action Gatekeeper)
- **Product Name:** Agent-FSM
- **Category:** Autonomous AI Agent Runtime & Deterministic Safety Layer
- **Target Audience:** Local AI Agent Engineers, Backend Systems Architects, Algorithmic Workflow Developers
- **Target Environments:** Ollama, vLLM, llama.cpp, LM Studio, Claude/OpenAI APIs, local open-weights models (Qwen-2.5-Coder, Llama 3)
- **Competitive Positioning:** Lean, mathematical alternative to bloated prompt-based agent frameworks (LangChain, CrewAI) that suffer from probabilistic state drift and fragile 25+ package dependency trees.
- **Language / Runtime:** Python 3.10+ (Standard Library Only, Zero pip dependencies)
- **Pricing & Valuation:** $29 USD (Lifetime As-Is Commercial License). Saves 3 to 5 business days of senior engineering overhead ($1,200–$2,500 value).
- **Commercial Access:** https://whop.com/checkout/plan_R1QMTmoTWOkfH
- **Technical Documentation:** https://sparkgrin-labs.github.io/articles/agent-fsm.html

### Problem Statement & Failure Modes Eliminated:
1. **Illegal State Traversal:** Prevents local/cloud LLMs from executing tools out of sequence (e.g., executing code prior to passing authentication or schema validation). Enforces a formal directed state graph $(S, \Sigma, \delta, s_0, F)$.
2. **Context Looping & Stagnation:** Computes a SHA-256 payload fingerprint per invocation. Halts infinite tool retry loops after 3 repetitive attempts, preventing token exhaustion.
3. **Malformed Schema Injection:** Validates tool arguments against strict JSON schemas before execution; invalid payloads are rejected at the gate without touching downstream tools.
4. **State Loss on Crash:** Every state transition and execution latency is recorded as an atomic transaction in an embedded SQLite database (`fsm_audit.db`), enabling instant checkpoint resumption via `--session <id> --resume`.

### Architecture & Benchmark Metrics:
- **External Dependencies:** 0 (Standard library only; zero `pip install` liabilities)
- **State Transition Latency:** < 5ms (In-memory state change + SQLite checkpoint)
- **Schema Validation Latency:** < 0.5ms (Pure standard library type evaluation)
- **Assertion Harness:** 20/20 certified test pass rate

---

## Product #2: MCP-Core (Zero-Dependency Model Context Protocol Runtime)
- **Product Name:** MCP-Core
- **Category:** Model Context Protocol (MCP) Runtime Engine & Tooling Middleware
- **Target Audience:** Local AI Engineers, Cursor & Claude Desktop Power Users, Systems Automation Developers building private toolkits and database connectors
- **Target Environments:** Claude Desktop, Cursor IDE, private local toolkits, headless automation agents
- **Competitive Positioning:** Solves the "15+ Dependency Trap" and fragile `.venv` paths of the official Python MCP SDK (no anyio, pydantic, starlette, httpx, sse-starlette, uvicorn bloat).
- **Language / Runtime:** Python 3.10+ (Standard Library Only, Zero pip dependencies)
- **Specification:** Model Context Protocol (MCP) 2024-11-05 (JSON-RPC 2.0)
- **Pricing & Valuation:** $29 USD (Lifetime As-Is Commercial License). Eliminates 2 to 4 days of cross-platform virtualenv path debugging and protocol parsing ($800–$1,600 billable value).
- **Commercial Access:** https://whop.com/checkout/plan_emRvsQaptAGXo
- **Technical Documentation:** https://sparkgrin-labs.github.io/articles/mcp-core.html

### Problem Statement & Failure Modes Eliminated:
1. **Stdout Framing Corruption:** MCP stdio transport requires absolute JSON-RPC protocol purity. Any stray `print()` statement or log written to stdout severs the client connection. MCP-Core forcibly hijacks standard `sys.stdout` and routes prints safely to `sys.stderr` via `StdoutShield`.
2. **Virtual Environment Fragility:** Eliminates the need to configure and maintain brittle virtualenv interpreter paths in `claude_desktop_config.json`. Runs on bare-metal vanilla Python 3.10+ with zero external packages.
3. **Unbounded Subprocess Freezes:** Dispatches tool execution across an isolated thread pool with strict millisecond timeouts, preventing hanging queries or network calls from freezing the host LLM.
4. **Silent Action Drift:** Embedded SQLite ledger (`mcp_audit.db`) records every JSON-RPC frame, argument payload, latency, and error trace for instant post-incident debugging.

### Architecture & Benchmark Metrics:
- **External Dependencies:** 0 (Standard library only; zero `pip install` liabilities)
- **Dispatch Overhead:** < 0.1ms per request (0.068ms benchmarked)
- **Schema Validation Latency:** < 0.2ms
- **Assertion Harness:** 20/20 certified protocol test pass rate

---

## Product #3: Agent-IPC (Low-Latency Socket & Runtime Bridge)
- **Product Name:** Agent-IPC
- **Category:** Non-Blocking Socket Multiplexer & Real-Time Telemetry Bridge
- **Target Audience:** Algorithmic Trading Developers, Autonomous Robotics/IoT Engineers, Local AI Architects
- **Target Environments:** Ollama, vLLM, llama.cpp, MetaTrader 5 (MQL5), TradingView webhooks, Unix domain sockets, local robotics telemetry
- **Competitive Positioning:** Solves the socket buffer overflow and packet loss problems during slow model inference without heavyweight enterprise brokers (RabbitMQ, Kafka, Redis) or C-bound libraries (pyzmq).
- **Language / Runtime:** Python 3.10+ (Standard Library Only, Zero pip dependencies)
- **Framing Protocol:** 4-Byte unsigned big-endian length-prefixed binary header (`struct.Struct("!I")`)
- **Pricing & Valuation:** $49 USD (Lifetime As-Is Commercial License). Saves 5 to 7 business days of low-level networking engineering ($2,000–$3,500+ value).
- **Commercial Access:** https://whop.com/checkout/plan_zKXkXhulUT5Gt
- **Technical Documentation:** https://sparkgrin-labs.github.io/articles/agent-ipc.html

### Problem Statement & Failure Modes Eliminated:
1. **Inference Latency Starvation:** Decouples ingestion from model inference. While the local model takes 300ms–3,000ms generating tokens, external socket traffic is continuously absorbed into an in-memory ring-buffer backed by automated SQLite overflow spooling.
2. **TCP Framing Fragmentation:** Replaces raw unsegmented TCP streams with 4-byte length-prefixed binary framing, preventing packet coalescing errors and json.loads() decode crashes.
3. **Half-Open Socket & Silent Disconnect Hangs:** Non-blocking keepalive watchdog monitors socket connections and reclaims dead client descriptors after timeout without blocking worker threads.
4. **Third-Party C-Extension Drift:** 100% Python standard library (`socket`, `selectors`, `struct`, `sqlite3`). Runs offline on any platform with zero compilation errors or pip drift.

### Architecture & Benchmark Metrics:
- **External Dependencies:** 0 (Standard library only; zero `pip install` liabilities)
- **Throughput:** >10,000 frames/sec on loopback TCP with zero frame loss
- **Persistence:** SQLite Write-Ahead Logging (`PRAGMA journal_mode = WAL;`)
- **Assertion Harness:** 20/20 certified protocol test pass rate

---

## Licensing & Distribution Terms
Distributed under the As-Is Commercial License by Sparkgrin@Labs (Open Automation Collective). Lifetime source code access for individual/commercial deployment. No ongoing maintenance, feature requests, or technical support tickets are included.