Metadata-Version: 2.5
Name: openinstinct
Version: 0.0.1
Summary: Open-weight models for fast, calibrated decisions you can run on your own machine.
Project-URL: Homepage, https://github.com/openinstinct
Project-URL: Repository, https://github.com/openinstinct
Project-URL: Hugging Face, https://huggingface.co/openinstinct
Author: OpenInstinct contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: calibration,classification,decision-making,machine-learning,open-weights,uzbek
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# OpenInstinct

**Open-weight models for fast, calibrated decisions — that you can run on your own machine.**

![Status](https://img.shields.io/badge/status-early%20development-orange)
![License](https://img.shields.io/badge/license-Apache%202.0-blue)
![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen)

> 🚧 **OpenInstinct is at a very early stage.** There is no released model yet. This page describes what we are building and how you can help. Everything is developed in the open, from the first line of code.

---

## What is OpenInstinct?

Most AI models are built to *write*: they generate answers token by token. But a lot of real software doesn't need prose — it needs a **decision**:

- Which team should handle this support ticket?
- Is this message asking for a refund?
- How urgent is this request, on a scale from 0 to 2?

OpenInstinct models don't generate text. You give them some **text (the state)** and a set of **typed questions**, and they return **answers with probabilities** in a single forward pass. Your code stays in control: it reads the answers, checks the confidence, and decides what to do next.

The idea is inspired by "System 1" thinking from Daniel Kahneman's *Thinking, Fast and Slow* — fast, intuitive judgments rather than slow, step-by-step reasoning. Recently, closed commercial models following this approach (such as TypeSafe's Jev) have appeared. OpenInstinct aims to be an **open-weight, self-hostable** alternative.

## Why open?

- **Your data stays with you.** Run the model locally, on-premises, or in your own cloud. Nothing has to leave your network.
- **Transparent.** Weights, training code, datasets, and evaluation results are all public.
- **Small and cheap.** Decision models don't need to be huge. The goal is models that run well on a single consumer GPU, and eventually on CPU.
- **Multilingual from the start.** We care about languages that big labs often underserve — including **Uzbek** (Latin and Cyrillic) — alongside English.

## Question types

| Type | Example question | Example answer |
|---|---|---|
| **choice** | Which team should handle this ticket? `billing` / `technical` / `account` | `billing` (0.91) |
| **binary** | Does this message request a refund? | `yes` (0.95) |
| **score** | How frustrated is the customer? 0 = calm, 1 = frustrated, 2 = very frustrated | `1.4` |

Every answer comes with calibrated probabilities, so you can decide when to act automatically and when to escalate to a human.

## Planned usage

> ⚠️ This API is a **draft** and does not work yet. It shows the direction we are heading.

```python
from openinstinct import Instinct

model = Instinct.load("openinstinct/instinct-0.5b")

result = model.decide(
    state="Customer: I was charged twice for order #4812. Please return my money.",
    questions={
        "team": {"type": "choice", "options": ["billing", "technical", "account"]},
        "refund_requested": {"type": "binary"},
        "frustration": {
            "type": "score",
            "levels": {0: "calm", 1: "frustrated", 2: "very frustrated"},
        },
    },
)

print(result["team"].answer)           # "billing"
print(result["team"].probabilities)    # {"billing": 0.91, "technical": 0.06, "account": 0.03}
print(result["refund_requested"].p)    # 0.95
print(result["frustration"].value)     # 1.4
```

## Roadmap

- [ ] Baseline: zero-shot decisions from small open LLMs by reading option logits
- [ ] Unified training data format: `{state, question, options, answer}`
- [ ] Training dataset built from open classification / NLI / QA datasets
- [ ] Uzbek evaluation benchmark built from real (not synthetic) data
- [ ] First fine-tuned model (LoRA on a small open model)
- [ ] Calibration: ECE, Brier score, reliability diagrams, temperature scaling
- [ ] Public evaluation against baselines (accuracy, calibration, latency)
- [ ] Python package on PyPI (`pip install openinstinct`)
- [ ] Interactive demo on Hugging Face Spaces
- [ ] Simple HTTP server for self-hosting
- [ ] Faster inference: shared state across many questions, CPU / ONNX / llama.cpp

## How you can help

You don't need to be an ML expert to contribute. We need help with:

- **Data** — finding, cleaning, and converting open datasets; writing and checking examples, especially in Uzbek and other underserved languages.
- **Evaluation** — designing realistic test sets and measuring calibration honestly.
- **Training & research** — fine-tuning experiments, calibration methods, model architectures.
- **Engineering** — the Python library, the inference server, performance work.
- **Docs & translation** — tutorials, examples, and translations of this documentation.

Open an issue, start a discussion, or pick an issue labeled `good first issue` once they appear. Questions and ideas are welcome too — including "this won't work because…".

## Links

- GitHub: [github.com/openinstinct](https://github.com/openinstinct)
- Hugging Face: [huggingface.co/openinstinct](https://huggingface.co/openinstinct)

## License

Code will be released under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). Model weights and datasets will use open licenses stated on each release.

---

<sub>OpenInstinct is an independent open-source project. It is not affiliated with, endorsed by, or connected to TypeSafe or any other company. Product names are mentioned only for comparison.</sub>
