cikkan-ops 1.0.1

A lightweight utility library to flatten tool JSONs and semantically optimize LLM prompt histories.

CikkanOps (cikkan-ops) 📉

CikkanOps (derived from the Tamil word Cikkaṉam, meaning thriftiness/eliminating waste) is a lightweight, production-grade input optimization library for LLM pipelines.

Passing raw, deeply nested JSON objects or unmanaged chat histories directly to LLM context windows causes severe token bloat and escalates API costs. CikkanOps serves as a lightweight optimization middleware to intercept your inputs, flatten structured data, and isolate semantic context vectors using TF-IDF similarity math—saving up to 40%+ on input tokens without dropping vital details.

---

✨ Features

• 📊 Data Gateway Compression: Dynamically flattens deeply nested tool/API outputs into space-efficient CSV string matrices.
• 🧠 Prompt Gateway Optimization: Routes historical logs into distinct runtime context zones (Hot / Cold), keeping semantic historical context while filtering out chat noise.
• 🏷️ Tiktoken Native Tracking: Precise byte-pair encoding (BPE) counts matching OpenAI GPT-3.5/GPT-4 specifications to provide accurate analytics on total cost reductions.

---

⚙️ Installation

Install the library directly from your GitHub repository using pip:

🚀 How To Use: Step-by-Step IntegrationTo optimize your costs, insert CikkanOps as an intermediary interceptor step directly before making calls to an LLM provider (e.g., OpenAI, Anthropic, or LangChain).

Step 1: Intercept Complex Tool JSON ResultsWhen a custom tool or external API returns a heavy JSON object, call compress_tool_output() to transform it into a compact format before appending it to your LLM system prompt context.

Step 2: Intercept Long Chat History BuffersRight before routing your active query to an LLM, pass your query along with your structural history array into optimize_prompt(). This pulls out semantic matches and reference tokens while purging text noise.

Complete Orchestration ExampleHere is a complete script demonstrating both optimization interception stages:Python

    import os
    from openai import OpenAI
    from cikkan_ops import AICostOptimizer

    # 1. Initialize the CikkanOps Client
    # top_k=2 specifies how many relevant semantic background records to retrieve
    optimizer = AICostOptimizer(top_k=2)

    # 2. Instantiate your standard LLM Client
    client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))


    print("--- STEP 1: INTERCEPTING BLOATED TOOL JSON ---")
    # Example response from a data mining tool or system database query
    raw_tool_json = {
        "status": "fetched",
        "metadata": {"cluster": "aws-east", "latency_ms": 140},
        "records": [
            {"id": "USR-8819", "profile": {"name": "Alice", "tier": "enterprise"}, "logs": ["login", "export"]},
            {"id": "USR-3021", "profile": {"name": "Bob", "tier": "standard"}, "logs": ["password_reset"]},
            {"id": "USR-4409", "profile": {"name": "Charlie", "tier": "premium"}, "logs": ["create_workspace"]}
        ]
    }

    # INTERCEPTION STEP: Convert messy multi-line JSON payload to tight CSV row streams
    optimized_tool_context = optimizer.compress_tool_output(raw_tool_json)

    print("Optimized Context Ready for LLM:")
    print(optimized_tool_context)


    print("\n--- STEP 2: INTERCEPTING & ROUTING PROMPT HISTORY ---")
    # Heavily padded developer operation history containing critical tokens mixed with noise
    chat_history = [
        "System cluster validation token established: SEC-X8839-KEY.", # <-- Regex Rule Match
        "Developer checked in raw production deployment scripts.",
        "Discussed setting up automated cron jobs for server backups.",
        "Team lead mentioned that we need to order pizza for the hackathon.", # <-- Structural Noise (Dropped)
        "Let's make sure we order at least 3 vegan options for the design team.", # <-- Structural Noise (Dropped)
        "Ran initial database migration schema successfully creating 14 tables.", # <-- Semantic Query Match
        "The weather index outside is quite warm and comfortable today.", # <-- Preserved via Hot Zone
        "User started modifying configuration setup specifications.",       # <-- Preserved via Hot Zone
        "Bot replied acknowledging incoming session updates."              # <-- Preserved via Hot Zone
    ]

    user_query = "What is the token assigned for the cluster validation check?"

    # INTERCEPTION STEP: Extract critical data indices and drop context noise
    optimization_payload = optimizer.optimize_prompt(prompt=user_query, chat_history=chat_history)

    # This returns a cleanly structured prompt framework string
    final_llm_input_string = optimization_payload["optimized_prompt"]


    print("\n--- STEP 3: DISPATCHING OPTIMIZED STRINGS TO LLM ---")
    # The final string is passed straight to the LLM completion API
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": f"You are a helpful systems assistant. Current data references:\n{optimized_tool_context}"},
            {"role": "user", "content": final_llm_input_string}
        ]
    )

    print(f"LLM Response: {response.choices[0].message.content}")


    print("\n--- STEP 4: VERIFY COST SAVINGS METRICS ---")
    metrics = optimizer.get_metrics()
    print(f"Total Raw Tokens Processed:  {metrics['total_tokens_processed']}")
    print(f"Total Input Tokens Saved:    {metrics['total_tokens_saved']}")
    print(f"Total Context Reduction:     {metrics['savings_percentage']}")

📊 Performance MatrixIn baseline evaluations involving large production data streams mixed with standard chat logs, CikkanOps delivers the following performance optimizations:

Metric Component,Unoptimized Input,CikkanOps Optimized,Token Savings (%) Tool Payload Parsing,312 Tokens (JSON),148 Tokens (CSV),~52.5% Context History Logs,130 Tokens (Padded),75 Tokens (Sifted),~42.3%

📜 License

Distributed under the Apache License 2.0. See LICENSE for more information.