Metadata-Version: 2.4
Name: thinking-lever
Version: 0.1.0
Summary: Structured thinking framework for LLMs — multi-layer levers for better reasoning
Author: Owz Consulting
License: MIT
Project-URL: Homepage, https://github.com/owz-consulting/thinking-lever
Project-URL: Repository, https://github.com/owz-consulting/thinking-lever
Keywords: llm,reasoning,thinking,framework,ai,prompt-engineering
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# thinking-lever 🧠🔧

**Structured thinking framework for LLMs** — a multi-layer architecture that enhances model reasoning through pure-rule preprocessing.

```
pip install thinking-lever
```

## Why?

LLMs think better when you give them a framework. But most "reasoning" systems are proprietary, model-specific, or over-engineered.

`thinking-lever` is **zero-dependency**, **model-agnostic**, and **runs in <5ms**. You can drop it into any LLM stack and immediately get better-structured reasoning.

## The 5 Levers

| Lever | Layer | What it does |
|:------|:------|:-------------|
| **L0 ContextLever** | Input restructuring | Extracts entities, actions, constraints; scans directories; walks import graphs |
| **L1 ThinkingLever** | Intent routing | Detects task type (diagnose/design/optimize/predict/execute) and recommends thinking methods |
| **L2 KnowledgeLever** | External knowledge | Retrieves relevant facts from your knowledge base |
| **L3 ExecutionLever** | Verification | Runs code checks, fact validation, config validation |
| **L4 ReflectionLever** | Self-check | Iterative quality refinement |

## Quick Start

### CLI

```bash
# Classify a task
thinking-lever classify "Why is my API returning 500 errors?"

# Scan context
thinking-lever scan "Audit the security of ~/myproject/"

# Verify a result
thinking-lever verify "Check syntax" "$(cat myfile.py)"

# Walk dependencies
thinking-lever deps ~/myproject/ --depth 3

# Problem mapping
thinking-lever map "Design a microservice architecture"

# Self-check
thinking-lever reflect "Here is my answer..."
```

### Python API

```python
from thinking_lever import classify_task, format_injection, context_scan

# L1: Classify
result = classify_task("Rewrite this module to be more efficient")
print(result["pattern"])         # "optimize"
print(result["method"])          # "constraint_analysis"

# L0: Scan
ctx = context_scan("Fix the bug in src/handler.py")
print(ctx["entities"])           # ["file:src/handler.py", ...]
print(ctx["actions"])            # ["repair"]
print(ctx["risk_zones"])         # ["Modification: backup first"]

# Inject into prompt
injection = format_injection(result)
enhanced_prompt = f"{injection}\n\n{user_message}"
```

### Middleware Integration

```python
from thinking_lever import LeverMiddleware

middleware = LeverMiddleware(
    enable_l0=True,
    enable_l1=True,
)

# In your kernel's pre_process:
def pre_process(user_message):
    enriched = middleware.process(user_message)
    return enriched  # Use this as your LLM input
```

## A/B Test Results

In a real-world code audit scenario across 4 tasks:

| Metric | Without | With Lever | Improvement |
|:-------|:-------:|:----------:|:-----------:|
| **Response time** | baseline | 4.7x faster | ⚡ structured prep avoids back-and-forth |
| **Tool utilization** | 0% | 91% | LLM uses available tools correctly |
| **Qualitative** | verbose, unfocused | concise, precise | focused on what matters |

## Design Philosophy

1. **Pure rules, no LLM overhead** — every lever is <5ms
2. **Zero external dependencies** — no numpy, no torch, no network calls
3. **Model-agnostic** — works with any LLM (GPT, Claude, open-source, local)
4. **Incremental adoption** — use 1 lever or all 5, middleware adapter or direct call
5. **Framework-independent** — use with LangChain, custom kernels, or CLI

## Requirements

- Python 3.8+

## License

MIT
