task: update docs, add .codecov config validation script

.codecov.yml

@@ -1,108 +1,41 @@
 component_management:
-  default_rules:
-    paths:
-      - "intent_kit/**"
-    statuses:
-      project:
-        target: auto
-        threshold: 5%
-        base: auto
-      patch:
-        target: auto
-        threshold: 5%
-        base: auto
   individual_components:
-    - component_id: core_engine
-      name: Core Engine (Framework & Intent Graph)
+    - component_id: "core_engine"
+      name: "Core Engine"
       paths:
         - "intent_kit/graph/**"
         - "intent_kit/nodes/**"
-      statuses:
-        project:
-          target: auto
-          threshold: 5%
-          base: auto
-        patch:
-          target: auto
-          threshold: 5%
-          base: auto
-    - component_id: node_library
-      name: Node Library (Batteries Included)
+    - component_id: "llm_services"
+      name: "LLM Services"
       paths:
-        - "intent_kit/node_library/**"
-      statuses:
-        project:
-          target: auto
-          threshold: 5%
-          base: auto
-        patch:
-          target: auto
-          threshold: 5%
-          base: auto
-    - component_id: llm_services
-      name: LLM Services & Model Clients
-      paths:
-        - "intent_kit/services/ai/**"
-        - "intent_kit/services/yaml_service.py"
-      statuses:
-        project:
-          target: auto
-          threshold: 5%
-          base: auto
-        patch:
-          target: auto
-          threshold: 5%
-          base: auto
-    - component_id: eval_framework
-      name: Evaluation Framework
+        - "intent_kit/services/**"
+    - component_id: "eval_framework"
+      name: "Evaluation Framework"
       paths:
         - "intent_kit/evals/**"
-      statuses:
-        project:
-          target: auto
-          threshold: 5%
-          base: auto
-        patch:
-          target: auto
-          threshold: 5%
-          base: auto
-    - component_id: context_management
-      name: Context Management
-      paths:
-        - "intent_kit/context/**"
-      statuses:
-        project:
-          target: auto
-          threshold: 5%
-          base: auto
-        patch:
-          target: auto
-          threshold: 5%
-          base: auto
-    - component_id: utils
-      name: Utilities & Shared Logic
+    - component_id: "utils"
+      name: "Utilities & Shared Logic"
       paths:
         - "intent_kit/utils/**"
         - "intent_kit/types.py"
-      statuses:
-        project:
-          target: auto
-          threshold: 5%
-          base: auto
-        patch:
-          target: auto
-          threshold: 5%
-          base: auto
-    - component_id: error_handling
-      name: Error Handling
+    - component_id: "context"
+      name: "Context Management"
+      paths:
+        - "intent_kit/context/**"
+    - component_id: "node_library"
+      name: "Node Library"
+      paths:
+        - "intent_kit/node_library/**"
+    - component_id: "exceptions"
+      name: "Exceptions & Error Handling"
       paths:
         - "intent_kit/exceptions/**"
-      statuses:
-        project:
-          target: auto
-          threshold: 5%
-          base: auto
-        patch:
-          target: auto
-          threshold: 5%
-          base: auto
+    - component_id: "remediation"
+      name: "Remediation & Error Handling"
+      paths:
+        - "intent_kit/nodes/actions/remediation.py"
+        - "intent_kit/nodes/actions/argument_extractor.py"
+    - component_id: "testing"
+      name: "Testing"
+      paths:
+        - "tests/**"

.pre-commit-config.yaml

@@ -40,6 +40,12 @@ repos:
         language: system
         files: pyproject.toml
         pass_filenames: false
+      - id: validate-codecov
+        name: Validate codecov.yml
+        entry: uv run scripts/validate_codecov.py
+        language: system
+        files: .codecov.yml
+        pass_filenames: false
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.5.0
     hooks:

README.md

@@ -5,25 +5,28 @@
 <h1 align="center">Intent Kit</h1>
 <p align="center">Build reliable, auditable AI applications that understand user intent and take intelligent actions</p>
 
-<p align="center">
-  <a 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 Status"/>
+<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 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"/>
+  <a style="text-decoration: none;" href="https://docs.intentkit.io">
+    <img src="https://img.shields.io/badge/docs-online-blue" alt="Documentation"/>
   </a>
-  <a href="https://pypi.org/project/intentkit-py/">
-    <img src="https://img.shields.io/pypi/v/intentkit-py" alt="PyPI Version"/>
+  <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>
-  <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="MIT License"/>
 </p>
 
 <p align="center">
   <a href="https://docs.intentkit.io">Docs</a>
 </p>
 
-
 ---
 
 ## What is Intent Kit?
@@ -90,6 +93,7 @@ greet = action(
 # Create a classifier to understand requests
 classifier = llm_classifier(
     name="main",
+    description="Route to appropriate action",
     children=[greet],
     llm_config={"provider": "openai", "model": "gpt-3.5-turbo"}
 )
@@ -100,6 +104,76 @@ result = graph.route("Hello Alice")
 print(result.output)  # → "Hello Alice!"
 ```
 
+### 3. Using JSON Configuration
+
+For more complex workflows, use JSON configuration:
+
+```python
+from intent_kit import IntentGraphBuilder
+
+# Define your functions
+def greet(name, context=None):
+    return f"Hello {name}!"
+
+def calculate(operation, a, b, context=None):
+    if operation == "add":
+        return a + b
+    return None
+
+# Create function registry
+function_registry = {
+    "greet": greet,
+    "calculate": calculate,
+}
+
+# Define your graph in JSON
+graph_config = {
+    "root": "main_classifier",
+    "nodes": {
+        "main_classifier": {
+            "id": "main_classifier",
+            "type": "classifier",
+            "classifier_type": "llm",
+            "name": "main_classifier",
+            "description": "Main intent classifier",
+            "llm_config": {
+                "provider": "openai",
+                "model": "gpt-3.5-turbo",
+            },
+            "children": ["greet_action", "calculate_action"],
+        },
+        "greet_action": {
+            "id": "greet_action",
+            "type": "action",
+            "name": "greet_action",
+            "description": "Greet the user",
+            "function": "greet",
+            "param_schema": {"name": "str"},
+        },
+        "calculate_action": {
+            "id": "calculate_action",
+            "type": "action",
+            "name": "calculate_action",
+            "description": "Perform a calculation",
+            "function": "calculate",
+            "param_schema": {"operation": "str", "a": "float", "b": "float"},
+        },
+    },
+}
+
+# Build your graph
+graph = (
+    IntentGraphBuilder()
+    .with_json(graph_config)
+    .with_functions(function_registry)
+    .build()
+)
+
+# Test it!
+result = graph.route("Hello Alice")
+print(result.output)  # → "Hello Alice!"
+```
+
 ---
 
 ## How It Works