Metadata-Version: 2.4
Name: peircean-abduction
Version: 1.2.2
Summary: A Logic Harness for abductive inference. Anomaly in → Hypothesis out.
Project-URL: Homepage, https://github.com/Hmbown/peircean-abduction
Project-URL: Documentation, https://github.com/Hmbown/peircean-abduction/blob/main/docs/PEIRCEAN_SPEC.md
Project-URL: Repository, https://github.com/Hmbown/peircean-abduction
Project-URL: Issues, https://github.com/Hmbown/peircean-abduction/issues
Author-email: Hunter Bown <hunter@shannonlabs.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: abduction,ai-agents,anomaly-detection,explanation,inference,llm,mcp,peirce,reasoning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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.10
Requires-Dist: httpx>=0.24
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0
Requires-Dist: tenacity>=8.0
Provides-Extra: all
Requires-Dist: anthropic>=0.18; extra == 'all'
Requires-Dist: google-generativeai>=0.3.0; extra == 'all'
Requires-Dist: mcp>=1.0.0; extra == 'all'
Requires-Dist: ollama>=0.1.0; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.3.0; extra == 'gemini'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: ollama
Requires-Dist: ollama>=0.1.0; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Description-Content-Type: text/markdown

# Peircean Abduction

**A Logic Harness for Abductive Inference.**

> "Abduction is the process of forming an explanatory hypothesis. It is the only logical operation which introduces any new idea." — Charles Sanders Peirce

Peircean Abduction is a **Model Context Protocol (MCP)** server that gives LLMs the ability to perform rigorous abductive reasoning. It forces models to generate multiple competing hypotheses for an observation and evaluate them using **Inference to the Best Explanation (IBE)**.

## ✨ Features

*   **MCP-First Design:** Built to be used directly within Claude Desktop, Cursor, or any MCP-compliant client.
*   **Provider Agnostic:** Works with **Anthropic**, **OpenAI**, **Gemini**, and **Ollama**.
*   **No API Key Required (Default):** By default, it generates *prompts* for you to run. You only need an API key if you want the tool to execute the reasoning loop autonomously.
*   **Council of Critics:** Simulates a debate between a Logician, Empiricist, and Scientist to refine hypotheses.

## 🚀 Quick Start

### 1. Install

```bash
pip install peircean-abduction
```

### 2. Connect to Claude Desktop

Run the installer to automatically configure Claude Desktop:

```bash
peircean --install
```

### 3. Use it!

Open Claude and ask:

> "Use the `peircean_observe_anomaly` tool to analyze why my server latency spiked but CPU usage is flat."

## 🛠️ Configuration

You can configure the provider and other settings via the interactive wizard:

```bash
peircean config wizard
```

Or by setting environment variables in a `.env` file:

```bash
# Provider Selection
PEIRCEAN_PROVIDER=anthropic  # anthropic, openai, gemini, ollama
PEIRCEAN_MODEL=claude-3-5-sonnet-20241022

# API Keys (Only needed for interactive/autonomous mode)
ANTHROPIC_API_KEY=sk-...
OPENAI_API_KEY=sk-...

# Feature Toggles
PEIRCEAN_ENABLE_COUNCIL=true
PEIRCEAN_INTERACTIVE_MODE=false # Set to true to let the tool call the LLM directly
```

## 📦 Supported Models

*   **Anthropic:** Claude 3.5 Sonnet (Recommended), Claude 3 Opus, Claude 3 Haiku
*   **OpenAI:** GPT-4o, GPT-4 Turbo
*   **Gemini:** Gemini 1.5 Pro
*   **Ollama:** Llama 3, Mistral

## 📚 Documentation

*   [Installation Guide](docs/getting-started/installation.md)
*   [Configuration Guide](docs/guides/configuration.md)
*   [API Reference](docs/reference/api.md)

## 📄 License

MIT
