Feature/add cost tracking

.codecov.yml

@@ -1,31 +1,33 @@
 component_management:
   individual_components:
     - component_id: core_engine
-      name: Core Engine
+      name: Core Engine (Framework & Intent Graph)
       paths:
         - intent_kit/graph/**
-        - intent_kit/node/**
-        - intent_kit/builders/**
+        - intent_kit/nodes/**
+    - component_id: node_library
+      name: Node Library (Batteries Included)
+      paths:
+        - intent_kit/node_library/**
     - component_id: llm_services
-      name: LLM Services
+      name: LLM Services & Model Clients
       paths:
-        - intent_kit/services/**
+        - intent_kit/services/ai/**
+        - intent_kit/services/yaml_service.py
     - component_id: eval_framework
       name: Evaluation Framework
       paths:
         - intent_kit/evals/**
+    - component_id: context_management
+      name: Context Management
+      paths:
+        - intent_kit/context/**
     - component_id: utils
       name: Utilities & Shared Logic
       paths:
         - intent_kit/utils/**
         - intent_kit/types.py
-    - component_id: remediation
-      name: Remediation & Error Handling
+    - component_id: error_handling
+      name: Error Handling
       paths:
-        - intent_kit/node/actions/remediation.py
-        - intent_kit/node/actions/clarifier.py
         - intent_kit/exceptions/**
-    - component_id: testing
-      name: Testing
-      paths:
-        - tests/**

README.md

@@ -1,26 +1,20 @@
-<p align="center">
-  <img src="assets/logo.png" alt="Intent Kit Logo" height="100" style="border-radius: 16px;"/>
-</p>
+<div align="center">
+  <img src="https://raw.githubusercontent.com/Stephen-Collins-tech/intent-kit/main/assets/logo.png" alt="Intent Kit Logo" height="100" style="border-radius: 16px;"/>
+</div>
 
 <h1 align="center">Intent Kit</h1>
-<p align="center">Build intelligent workflows that understand what users want</p>
-
-<p align="center" >
-  <a style="text-decoration: none;" href="https://github.com/Stephen-Collins-tech/intent-kit/actions/workflows/ci.yml">
-    <img src="https://github.com/Stephen-Collins-tech/intent-kit/actions/workflows/ci.yml/badge.svg" alt="CI"/>
-  </a>
-  <a style="text-decoration: none;" href="https://codecov.io/gh/Stephen-Collins-tech/intent-kit">
-    <img src="https://codecov.io/gh/Stephen-Collins-tech/intent-kit/branch/main/graph/badge.svg" alt="Coverage Status"/>
-  </a>
-  <a style="text-decoration: none;" href="https://docs.intentkit.io">
-    <img src="https://img.shields.io/badge/docs-online-blue" alt="Documentation"/>
-  </a>
-  <a style="text-decoration: none;" href="https://pypi.org/project/intentkit-py">
-    <img src="https://img.shields.io/pypi/v/intentkit-py" alt="PyPI"/>
-  </a>
-  <a style="text-decoration: none;" href="https://pypi.org/project/intentkit-py">
-    <img src="https://img.shields.io/pypi/dm/intentkit-py" alt="PyPI Downloads"/>
-  </a>
+<p align="center">Build reliable, auditable AI applications that understand user intent and take intelligent actions</p>
+
+<div align="center" >
+  <img src="https://github.com/Stephen-Collins-tech/intent-kit/actions/workflows/ci.yml/badge.svg" alt="CI"/>
+  <img src="https://codecov.io/gh/Stephen-Collins-tech/intent-kit/branch/main/graph/badge.svg" alt="Coverage Status"/>
+  <img src="https://img.shields.io/pypi/v/intentkit-py" alt="PyPI"/>
+  <img src="https://img.shields.io/pypi/dm/intentkit-py" alt="PyPI Downloads"/>
+  <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"/>
+</div>
+
+<p align="center">
+  <a href="https://docs.intentkit.io">Docs</a>
 </p>
 
 ---
@@ -41,20 +35,20 @@ The best part? You stay in complete control. You define exactly what your app ca
 
 ## Why Intent Kit?
 
+### **Reliable & Auditable**
+Every decision is traceable. Test your workflows thoroughly and deploy with confidence knowing exactly how your AI will behave.
+
 ### **You're in Control**
-Define every possible action upfront. No surprises, no unexpected behavior.
+Define every possible action upfront. No black boxes, no unexpected behavior, no surprises.
 
 ### **Works with Any AI**
 Use OpenAI, Anthropic, Google, Ollama, or even simple rules. Mix and match as needed.
 
 ### **Easy to Build**
 Simple, clear API that feels natural to use. No complex abstractions to learn.
 
-### **Testable & Reliable**
-Built-in testing tools let you verify your workflows work correctly before deploying.
-
 ### **See What's Happening**
-Visualize your workflows and track exactly how decisions are made.
+Track exactly how decisions are made and debug with full transparency.
 
 ---
 
@@ -118,9 +112,9 @@ The magic happens when a user sends a message:
 
 ---
 
-## Real-World Testing
+## Reliable & Auditable AI
 
-Most AI frameworks are black boxes that are hard to test. Intent Kit is different.
+Most AI frameworks are black boxes that are hard to test and debug. Intent Kit is different - every decision is traceable and testable.
 
 ### Test Your Workflows Like Real Software
 
@@ -137,19 +131,27 @@ print(f"Accuracy: {result.accuracy():.1%}")
 result.save_report("test_results.md")
 ```
 
-### What You Can Test
+### What You Can Test & Audit
 
 - **Accuracy** - Does your workflow understand requests correctly?
 - **Performance** - How fast does it respond?
 - **Edge Cases** - What happens with unusual inputs?
 - **Regressions** - Catch when changes break existing functionality
+- **Decision Paths** - Trace exactly how each decision was made
+- **Bias Detection** - Identify potential biases in your workflows
 
-This means you can deploy with confidence, knowing your AI workflows work reliably.
+This means you can deploy with confidence, knowing your AI workflows work reliably and can be audited when needed.
 
 ---
 
 ## Key Features
 
+### **Reliable & Auditable**
+- Every decision is traceable and testable
+- Comprehensive testing framework
+- Full transparency into AI decision-making
+- Bias detection and mitigation tools
+
 ### **Smart Understanding**
 - Works with any AI model (OpenAI, Anthropic, Google, Ollama)
 - Extracts parameters automatically (names, dates, preferences)
@@ -160,10 +162,10 @@ This means you can deploy with confidence, knowing your AI workflows work reliab
 - Handle "do X and Y" requests
 - Remember context across conversations
 
-### **Visualization**
-- See your workflows as interactive diagrams
+### **Debugging & Transparency**
 - Track how decisions are made
-- Debug complex flows easily
+- Debug complex flows with full transparency
+- Audit decision paths when needed
 
 ### **Developer Friendly**
 - Simple, clear API
@@ -175,6 +177,7 @@ This means you can deploy with confidence, knowing your AI workflows work reliab
 - Test against real datasets
 - Measure accuracy and performance
 - Catch regressions automatically
+- Validate reliability before deployment
 
 ---
 

docs/concepts/intent-graphs.md

@@ -14,14 +14,21 @@ An intent graph is a directed acyclic graph (DAG) where:
 ## Graph Structure
 
 ```text
-User Input → Root Classifier → Intent Classifier → Action → Output
+User Input → Root Classifier → Action → Output
 ```
 
 ### Node Types
 
-1. **Classifier Nodes** - Route input to appropriate child nodes
-2. **Action Nodes** - Execute actions and produce outputs
-3. **Splitter Nodes** - Handle multiple nodes in single input
+1. **Classifier Nodes** - Route input to appropriate child nodes (must be root nodes)
+2. **Action Nodes** - Execute actions and produce outputs (leaf nodes)
+
+### Single Intent Architecture
+
+All root nodes must be classifier nodes. This ensures focused, single-intent handling:
+
+- **Root Classifiers** - Entry points that classify user input and route to actions
+- **Action Nodes** - Leaf nodes that execute specific actions
+- **No Splitters** - Multi-intent splitting is not supported in this architecture
 
 ## Building Intent Graphs
 
@@ -53,7 +60,7 @@ main_classifier = llm_classifier(
     llm_config={"provider": "openai", "model": "gpt-4"}
 )
 
-# Build graph with LLM configuration for chunk classification
+# Build graph with LLM configuration
 graph = IntentGraphBuilder().root(main_classifier).with_default_llm_config({
     "provider": "openai",
     "model": "gpt-4"

docs/concepts/nodes-and-actions.md

@@ -2,6 +2,15 @@
 
 Nodes and actions are the fundamental building blocks of intent graphs. They define how user input is processed, classified, and acted upon.
 
+## Architecture Overview
+
+Intent graphs use a **single intent architecture** where:
+- **Root nodes must be classifiers** - They classify user input and route to actions
+- **Action nodes are leaf nodes** - They execute specific actions and produce outputs
+- **No multi-intent splitting** - Each input is handled as a single, focused intent
+
+This architecture ensures deterministic, focused intent processing without the complexity of multi-intent handling.
+
 ## Node Types
 
 ### Action Nodes
@@ -74,56 +83,7 @@ main_classifier = keyword_classifier(
 )
 ```
 
-#### Chunk Classifier
-
-Classifies text chunks for processing:
-
-```python
-from intent_kit import chunk_classifier
-
-content_classifier = chunk_classifier(
-    name="content",
-    description="Classify content types",
-    children=[text_action, image_action, audio_action],
-    chunk_size=1000
-)
-```
-
-### Splitter Nodes
-
-Splitter nodes handle multiple nodes in a single input by splitting the input into parts.
-
-#### Rule Splitter
-
-Uses rule-based splitting:
-
-```python
-from intent_kit import rule_splitter_node
-
-multi_splitter = rule_splitter_node(
-    name="multi_split",
-    children=[greet_action, weather_action, calculator_action],
-    rules={
-        "greet": ["hello", "hi", "greetings"],
-        "weather": ["weather", "temperature", "forecast"],
-        "calculator": ["add", "subtract", "multiply", "divide"]
-    }
-)
-```
-
-#### LLM Splitter
 
-Uses LLM for intelligent splitting:
-
-```python
-from intent_kit import llm_splitter
-
-smart_splitter = llm_splitter(
-    name="smart_split",
-    children=[greet_action, weather_action],
-    llm_config={"provider": "openai", "model": "gpt-4"}
-)
-```
 
 ## Parameter Extraction
 

docs/configuration/json-serialization.md

@@ -63,7 +63,7 @@ graph = IntentGraphBuilder().with_functions(function_registry).with_json(json_gr
   "root_nodes": [
     {
       "name": "node_name",
-      "type": "action|classifier|splitter",
+      "type": "action|classifier",
       "description": "Optional description",
       "function_name": "registry_function_name",
       "param_schema": {
@@ -82,7 +82,7 @@ graph = IntentGraphBuilder().with_functions(function_registry).with_json(json_gr
       ]
     }
   ],
-  "splitter": "optional_splitter_function_name",
+
   "visualize": false,
   "debug_context": false,
   "context_trace": false
@@ -118,18 +118,7 @@ graph = IntentGraphBuilder().with_functions(function_registry).with_json(json_gr
 }
 ```
 
-#### Splitter Node
-```json
-{
-  "name": "content_splitter",
-  "type": "splitter",
-  "splitter_function": "text_splitter",
-  "description": "Splits content into chunks",
-  "children": [
-    // Child nodes to process each chunk
-  ]
-}
-```
+
 
 ## LLM-Powered Argument Extraction
 

docs/development/evaluation.md

@@ -49,7 +49,7 @@ test_cases:
     expected_intent: "greet"
     expected_params:
       name: "Alice"
-  
+
   - input: "Hi Bob"
     expected_output: "Hello Bob!"
     expected_intent: "greet"
@@ -227,4 +227,4 @@ jobs:
           from intent_kit.evals import check_regressions
           check_regressions('baseline.json', 'results.json')
           "
-```
+```

docs/development/testing.md

@@ -61,10 +61,10 @@ def test_simple_action():
         action_func=lambda name: f"Hello {name}!",
         param_schema={"name": str}
     )
-    
+
     graph = IntentGraphBuilder().root(greet_action).build()
     result = graph.route("Hello Alice")
-    
+
     assert result.success
     assert result.output == "Hello Alice!"
 ```
@@ -111,4 +111,4 @@ result = run_eval(dataset, your_graph)
 # Check performance metrics
 print(f"Average response time: {result.avg_response_time()}ms")
 print(f"Throughput: {result.throughput()} requests/second")
-```
+```