IntentC (intent-c)

Python Version License

IntentC is an ultra-lightweight, high-performance asynchronous micro-framework designed to compile human language intentions into deterministic, production-ready execution flows.

By replacing expensive, multi-turn token generation loops with an elegant Single-Pass Semantic Pipeline backed by NumPy linear algebra, IntentC eliminates runtime latency overhead, providing near-instantaneous execution speeds for local automation cores, smart environments, and embedded AI ecosystems.

💎 Core Architectural Philosophy

IntentC operates on the principle of Zero-Gravity Runtime AI. Traditional multi-agent or step-by-step reasoning patterns introduce heavy latency and unpredictability by forcing the Large Language Model to evaluate conditions, route tasks, and observe states through successive, blocking inference cycles.

IntentC decouples intelligence from execution:

1. The Single-Pass LLM Hit: The language model is utilized exactly once—at the very boundary of the system—acting strictly as a structured compiler that translates user prompts into a deterministic task graph via rigid Pydantic models.
2. Nanosecond Matrix Task Routing: Once the task list is generated, the LLM is disengaged. Plugin matching and action discovery are handled directly in system RAM using raw NumPy normalized vector dot-products (np.dot). Routing speed is constant and unaffected by the size of your codebase.
3. Reactive State Resolution: System conditions, branching logic (if/else), and state checks are evaluated natively in pure Python using live, isolated context snapshots exposed by the plugins—completely bypassing the LLM.
4. Asynchronous Stream Execution: Independent non-blocking execution nodes are bundled into concurrent streams and dispatched simultaneously using asyncio.gather with robust error isolation.

🧠 The AIRAGMemory Subsystem: Dynamic Self-Stabilization

The framework features a built-in, non-blocking long-term memory store (AIRAGMemory) running over an asynchronous SQLite WAL (Write-Ahead Logging) backend.

• Cold Start Phase: When an abstract or complex prompt is first encountered, the system compiler maps the intention to structural nodes. The compiled experience is indexed, converted into float32 vector embeddings, and committed to the database.
• Warm Cache Acceleration: For subsequent interactions sharing semantic proximity, the NumPy router automatically intercepts the prompt using a cosine similarity threshold check (score >= 0.4). The LLM is completely bypassed for decomposition, pulling the optimal execution plan from RAM in under 2 milliseconds.
• Infant Model Stability: This mathematical shield ensures that even ultra-lightweight local models (e.g., 0.5B to 3B parameters) perform with the stability of frontier models over time, as they inherit verified, pre-compiled structural templates.

📦 Installation

IntentC maintains a sterile dependency footprint. It is completely independent of heavy frameworks like PyTorch or CUDA, enabling native, blazing-fast execution directly on consumer-grade CPUs.

pip install intent-c

🚀 Developer Experience (DX)

Say goodbye to manual JSON-Schema authoring or prompt engineering for function calling. IntentC maps your codebase to semantic passports using native Python type hinting and runtime reflection.

import asyncio
from pathlib import Path
from intent_c.engine import AIEngine
from intent_c.sdk import BasePlugin, describe

# 1. Define your domain capability as a clean, isolated plugin
class HomeAutomationPlugin(BasePlugin):
    def __init__(self) -> None:
        super().__init__()
        self.plugin_name = "climate"
        self.target_temperature = 19.0

    @describe("Changes the target room temperature of the climate controller")
    async def set_temperature(self, target_value: float) -> str:
        self.target_temperature = target_value
        return f"Climate target updated to {target_value}°C"

    def get_live_context(self) -> dict:
        """Exposes real-time system state for reactive conditional branching"""
        return {
            "current_temp": self.target_temperature,
            "heater_active": self.target_temperature < 22.0
        }

async def main():
    # 2. Instantiate the zero-overhead engine
    engine = AIEngine(ai_model="gemma4-e4b", routing_model="vector")
    await engine.initialize()
    
    # 3. Register your capabilities into RAM cached metadata
    engine.register_plugin(HomeAutomationPlugin())

    # 4. Compile and dispatch complex commands smoothly
    prompt = "If the heater is active (climate.heater_active), then turn the temperature to 23.5 degrees"
    results = await engine.run_engine(prompt)
    print(f"Execution Output: {results}")
    
    await engine.delete_engine()

if __name__ == "__main__":
    asyncio.run(main())

🏛️ Package Architecture & Components

The codebase is built on an enterprise-grade, asynchronous foundation:

• log_config.py — Non-blocking, thread-safe asynchronous logging layer leveraging memory queues via QueueHandler and QueueListener to prevent I/O blocking during execution spikes.
• memory.py — The NumPy-powered vector memory layer, managing float32 matrix caching, online L2-normalization, and persistence layers.
• orchestrator.py — The core multi-mode scheduling compiler supporting structural string parsing (text), vector dot-product algebra (vector), and abstract BLM mappings.
• engine.py — The top-level system facade and fault-tolerant execution runtime. It isolates individual user-space plugin failures using explicit continue blocks, keeping your automation runtime alive under all conditions.

📊 Stress-Test Benchmarks

In deep enterprise infrastructure scenarios handling a dense registry of 30 concurrent methods in RAM using local models running on standard consumer hardware, IntentC delivers unmatched throughput profiles:

• Sequential ReAct Agents: 919.26 seconds (Suffering from cascade inference degradation)
• IntentC Engine (Cold-Start Generation): 65.17 seconds (Single LLM forward-pass)
• IntentC Engine (AIRAG Cache hit): 0.002 seconds (Instant linear algebra translation)

📝 License

IntentC is open-source software licensed under the MIT License. Build lightweight, bulletproof local automation runtimes without structural limits!