jevzilla 0.1.0__tar.gz

jevzilla-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ujjwalkumar Soni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jevzilla-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: jevzilla
+Version: 0.1.0
+Summary: A tiny, fearless client for the JEV evaluation API
+Requires-Python: >=3.8
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Dynamic: license-file

jevzilla-0.1.0/README.md

@@ -0,0 +1,424 @@
+# JEVzilla 🦖
+
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI](https://img.shields.io/badge/pypi-jevzilla-brightgreen.svg)](https://pypi.org/project/jevzilla/)
+
+A fearless, lightweight Python client for the JEV decision evaluation API with **150+ production-ready business decision examples** across 30 sectors.
+
+Write decision payloads exactly like the [official JEV API docs](https://jevplayground.com/jev-api), and JEVzilla handles the translation automatically. Perfect for operational decisions, compliance automation, and AI-driven business logic.
+
+## 🤔 What is JEV?
+
+**JEV** is a **decision layer for software applications** — not a chatbot or text generator, but a system designed to make **structured, typed decisions** that your code can consume and act on.
+
+Given a piece of context (called **state**), JEV answers **typed questions** and returns **structured answers with probability signals**. Your application then branches on these decisions to automate workflows, route requests, or flag for human review.
+
+### Why JEV is Different
+
+| Traditional LLM | JEV |
+|---|---|
+| Open-ended text responses | **Bounded, typed decisions** |
+| Requires parsing output | **Structured JSON answers** |
+| May hallucinate or ramble | **Focused yes/no, choice, or score** |
+| Hard to integrate into workflows | **Built for programmatic consumption** |
+
+**JEV is best for:**
+- ✅ Operational triage & routing (which team owns this?)
+- ✅ Risk/severity scoring (how critical is this?)
+- ✅ Yes/no classification (should this be escalated?)
+- ✅ Conditional business logic (decide what happens next)
+
+**JEV is NOT for:**
+- ❌ Open-ended explanations
+- ❌ Creative content generation
+- ❌ Long conversational responses
+- → Use a generative LLM for those
+
+## ✨ What Makes JEVzilla Special
+
+- **Production-Ready Examples**: 150+ real-world business decision scripts, fully runnable
+- **Multi-Sector Coverage**: 30 sectors including HR, Finance, Healthcare, Legal, Banking, Insurance, Cybersecurity, Retail, Supply Chain, Construction, Agriculture, Transportation, Food & Beverage, Pharmaceutical, Government, Aviation, Tourism, Environmental, Sports, and more
+- **Simple, Intuitive API**: Just `noul()` (yes/no), `choice()` (select one), and `score()` (prioritize)
+- **Flexible Backends**: Playground, Official API, or OpenRouter
+- **Zero Boilerplate**: Auto-translates payloads — no manual wire format needed
+- **Battle-Tested**: Retry logic, exponential backoff, comprehensive error handling
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install jevzilla
+```
+
+### Basic Usage
+
+```python
+from jevzilla import JEVzilla, noul, choice, score
+
+# Initialize the client
+jev = JEVzilla()
+
+# Ask a decision
+response = jev.evaluate({
+    "state": "Customer charged twice, cannot access account.",
+    "questions": {
+        "refund_review": noul("Does this need refund review?"),
+        "team": choice("Which team?", {
+            "billing": "Payment issues",
+            "technical": "Access problems"
+        }),
+        "urgency": score("How urgent?", ["Routine", "Time-sensitive", "Blocked"]),
+    },
+})
+
+print(response.status_code, response.answers)
+# Output: 200 {'refund_review': {...}, 'team': {...}, 'urgency': {...}}
+```
+
+### Inspecting the Payload
+
+```python
+# See the exact payload that gets sent
+jev = JEVzilla()
+payload = jev.build({
+    "state": "High CPU usage detected",
+    "questions": {
+        "urgent": noul("Is this critical?"),
+    }
+})
+print(payload)
+```
+
+## 🎯 The Three Question Types
+
+JEV supports three core question types for making decisions:
+
+### **Noul** — Yes/No Judgment
+A **focused, proposition-based question** that returns a probability between 0 and 1.
+
+**When to use:** Single yes/no decisions, risk flags, human review gates
+```python
+noul("Does this request contain an urgent deadline?")
+# Returns: {"noul": 0.87}  (87% confidence it's urgent)
+```
+
+**Real examples:**
+- "Should this order be flagged for manual review?"
+- "Does the customer have churn risk?"
+- "Is this transaction fraudulent?"
+
+---
+
+### **Choice** — Classification & Routing
+Select **one option from a predefined set** of categories, plus confidence scores.
+
+**When to use:** Routing decisions, ticket classification, routing to teams
+```python
+choice("Which team should handle this?", {
+    "billing": "Payments & billing issues",
+    "technical": "Technical problems",
+    "support": "General support requests"
+})
+# Returns: {"choice": "billing", "confidence": 0.92}
+```
+
+**Real examples:**
+- "Route this ticket to: Sales, Support, or Technical?"
+- "Classify this transaction: Normal, Suspicious, or Blocked?"
+- "Which priority bucket: Low, Medium, High, or Critical?"
+
+---
+
+### **Score** — Severity, Priority, or Quality Ranking
+Rank context on an **ordered scale** with confidence signals (e.g., Low → Medium → High → Critical).
+
+**When to use:** Risk/severity scoring, priority ranking, quality assessment
+```python
+score("How urgent is this incident?", ["Routine", "Time-sensitive", "Blocked"])
+# Returns: {"score": 2, "legend": ["Routine", "Time-sensitive", "Blocked"]}
+```
+
+**Real examples:**
+- "Incident severity: Info, Warning, or Critical?"
+- "Churn risk: Low, Medium, or High?"
+- "Loan approval score: 1–5?"
+
+---
+
+### Summary Table
+
+| Type | Question | Answer | Use Case |
+|------|----------|--------|----------|
+| **noul** | Yes/no proposition | 0.0–1.0 probability | Gate decisions, flags |
+| **choice** | Pick one category | One option + confidence | Routing, classification |
+| **score** | Rank on ordered scale | Position + probability | Risk/severity scoring |
+
+## 🔧 Advanced Features
+
+### Convenience Shortcuts
+
+```python
+# Single-question shortcuts
+response = jev.ask_noul(
+    state="Server down for 2 hours",
+    instructions="Is this a P1 incident?",
+)
+
+response = jev.ask_choice(
+    state="New customer inquiry",
+    instructions="Which team should handle this?",
+    criteria={"sales": "Enterprise Sales", "support": "Support"},
+)
+
+response = jev.ask_score(
+    state="Database backup failed",
+    instructions="How critical?",
+    levels=["Informational", "Warning", "Critical"],
+)
+```
+
+### Custom Backends
+
+```python
+# Official TypeSafe API (requires TYPESAFE_API_KEY env var)
+jev = JEVzilla(backend="typesafe")
+
+# OpenRouter API (requires OPENROUTER_API_KEY env var)
+jev = JEVzilla(backend="openrouter")
+
+# Custom URL or API key
+jev = JEVzilla(backend="typesafe", api_key="your-api-key-here")
+```
+
+### Retry & Timeout Control
+
+```python
+jev = JEVzilla(
+    timeout=45.0,           # Request timeout in seconds
+    retries=4,              # Max retry attempts
+    backoff=1.0,            # Initial backoff multiplier
+    max_backoff=30.0,       # Maximum backoff cap
+)
+```
+
+### Batch Processing
+
+```python
+# Process multiple decisions
+decisions = [
+    {"state": "...", "questions": {...}},
+    {"state": "...", "questions": {...}},
+]
+
+for decision in decisions:
+    response = jev.evaluate(decision)
+    if response.ok:
+        print(f"Answer: {response.answers}")
+```
+
+## 📚 150+ Real-World Examples Across 30 Sectors
+
+JEVzilla includes **150+ production-ready business decision scripts** organized by sector:
+
+### Original 20 Sectors (100 examples)
+
+| Sector | Scripts | Use Cases |
+|--------|---------|-----------|
+| **HR** | 5 | Resume screening, Interview feedback, Grievance triage, Performance calibration, Offer risk |
+| **Finance** | 5 | Invoice review, Expense audit, Budget variance, Credit applications, Anomaly detection |
+| **Healthcare** | 5 | Patient intake, Pre-auth review, No-show risk, Billing disputes, Feedback analysis |
+| **Legal** | 5 | Contract review, NDA analysis, Compliance gaps, Litigation holds, Trademark disputes |
+| **Banking** | 5 | Loan applications, Fraud detection, Account opening, Disputes, AML alerts |
+| **Insurance** | 5 | Claims triage, Renewal risk, Underwriting, Subrogation, Complaints |
+| **IT/DevOps** | 5 | Incident severity, Change risk, Code review, Access requests, Vendor security |
+| **Manufacturing** | 5 | Defect triage, Supplier audit, Safety incidents, Maintenance, Change requests |
+| **Logistics** | 5 | Shipment exceptions, Supplier delays, Customs review, Carrier performance, Warehouse |
+| **Retail** | 5 | Return fraud, Review moderation, Reorder priority, Complaint routing, Price matching |
+| **Real Estate** | 5 | Tenant screening, Maintenance, Lease renewal, Inspections, Offers |
+| **Education** | 5 | Submission review, Admissions, Financial aid, Integrity checks, Feedback |
+| **Cybersecurity** | 5 | Phishing triage, Vulnerability review, Access anomalies, Incident response, Vendor risk |
+| **Marketing** | 5 | Content review, Influencer vetting, Ad compliance, Survey sentiment, Brand mentions |
+| **Customer Support** | 5 | Ticket triage, Refund decisions, Churn flags, Escalation, CSAT follow-up |
+| **Energy/Utilities** | 5 | Outage triage, Meter anomalies, Safety incidents, Assistance review, Maintenance |
+| **Hospitality** | 5 | Guest complaints, Booking fraud, Overbooking, Travel refunds, Review responses |
+| **Media/Entertainment** | 5 | Content moderation, Copyright claims, Brand safety, Comments, Licensing |
+| **Telecom** | 5 | Outage triage, SIM swap review, Churn risk, Billing disputes, Upgrade eligibility |
+| **Sales** | 5 | Lead qualification, Deal risk, Churn prediction, Proposals, Discount approvals |
+
+### NEW 10 Sectors (50 examples)
+
+| Sector | Scripts | Use Cases |
+|--------|---------|-----------|
+| **Construction** | 5 | Site safety triage, Contractor vetting, Project delay risk, Equipment maintenance, Permit compliance |
+| **Agriculture** | 5 | Crop health assessment, Equipment maintenance, Pest/disease triage, Supplier quality, Harvest readiness |
+| **Transportation** | 5 | Vehicle maintenance scheduling, Accident damage assessment, Warranty claims, Fuel efficiency, Recall prioritization |
+| **Food & Beverage** | 5 | Health inspection escalation, Food safety incidents, Supplier quality, Customer complaints, Menu performance |
+| **Pharmaceutical** | 5 | Clinical trial eligibility, Adverse event severity, Drug compound quality, Regulatory compliance gaps, Research proposals |
+| **Government** | 5 | Permit applications, Public assistance eligibility, Compliance violations, Budget allocation, FOIA requests |
+| **Aviation** | 5 | Maintenance scheduling, Safety incidents, Pilot incidents, Regulatory compliance, Crew scheduling |
+| **Tourism** | 5 | Booking fraud detection, Travel insurance claims, Destination safety, Customer complaints, Tour guide vetting |
+| **Environmental** | 5 | Environmental incidents, Compliance violations, Carbon footprint, Waste management, Green certification |
+| **Sports & Fitness** | 5 | Gym membership eligibility, Training injury assessment, Equipment maintenance, Member complaints, Program recommendations |
+
+### Running Examples
+
+```bash
+# Install the package
+pip install -e .
+
+# Set your API key
+export OPENROUTER_API_KEY=your-key-here
+
+# Run any example
+cd examples/hr
+python resume_screening.py
+
+# Or run from any sector
+cd examples/banking
+python fraud_transaction_flag.py
+```
+
+Every script follows the same **gate + route + priority** pattern:
+- **Gate** (`noul`): Should this be escalated/flagged?
+- **Route** (`choice`): Which team owns this?
+- **Priority** (`score`): How urgent/severe?
+
+This consistency makes it easy to adapt examples to your own workflows.
+
+## 🔐 Security & Compliance
+
+- **No hardcoded keys**: All API keys via environment variables
+- **Regulated data guidance**: Examples for Healthcare, Banking, Legal include compliance notes
+- **Safe by default**: Demos use invented data — swap in yours with compliance approval
+- **Transparent**: Source available, audit-ready
+
+## 📊 Error Handling
+
+```python
+from jevzilla import JEVError, JEVValidationError, JEVHTTPError
+
+try:
+    response = jev.evaluate({"state": "...", "questions": {...}})
+except JEVValidationError as e:
+    print(f"Invalid payload: {e}")
+except JEVHTTPError as e:
+    print(f"API error {e.status_code}: {e.body}")
+except JEVError as e:
+    print(f"Other error: {e}")
+```
+
+## 🛠️ API Reference
+
+### `JEVzilla` Class
+
+```python
+jev = JEVzilla(
+    backend: str = "playground",        # "playground", "typesafe", or "openrouter"
+    api_key: Optional[str] = None,      # API key (or use env vars)
+    model: str = "jev-latest",          # Model version
+    url: Optional[str] = None,          # Custom endpoint URL
+    timeout: float = 30.0,              # Request timeout (seconds)
+    retries: int = 4,                   # Max retry attempts
+    backoff: float = 1.0,               # Initial backoff multiplier
+    max_backoff: float = 30.0,          # Maximum backoff (seconds)
+    session: Optional[requests.Session] = None,  # Custom session
+    extra_headers: Optional[Dict] = None,       # Extra HTTP headers
+)
+```
+
+### Methods
+
+| Method | Purpose |
+|--------|---------|
+| `evaluate(payload, raise_for_status=True)` | Send a decision request |
+| `build(payload)` | Get the exact body without sending |
+| `ask_noul(state, instructions, ...)` | Quick yes/no question |
+| `ask_choice(state, instructions, criteria, ...)` | Quick choice question |
+| `ask_score(state, instructions, levels, ...)` | Quick score question |
+
+### Response Object
+
+```python
+response.ok                    # bool: status in 200-299
+response.status_code           # int: HTTP status
+response.text                  # str: raw response body
+response.data                  # dict: parsed JSON response
+response.answers               # dict or list: the answers
+response.noul(key, threshold)  # Extract boolean answer (0-1 probability)
+response.choice(key)           # Extract choice answer
+response.score_label(key)      # Extract score label
+```
+
+## 📦 Dependencies
+
+- **Python**: 3.8+
+- **requests**: 2.28+
+
+## 📄 License
+
+MIT License — see LICENSE file for details.
+
+## 👨‍💻 Author
+
+**Ujjwalkumar Soni**
+
+## 🤝 Contributing
+
+Contributions welcome! Submit issues, feature requests, or pull requests on GitHub.
+
+## 🎓 Use Cases & Patterns
+
+### Gate + Route + Priority Pattern
+
+Every JEVzilla example follows the same battle-tested pattern:
+
+1. **Gate** (`noul`): **Should this be escalated/flagged?**
+   - "Does this need manual review?"
+   - "Is this a fraud risk?"
+
+2. **Route** (`choice`): **Which team owns this?**
+   - "Route to: Billing, Technical, or Support?"
+   - "Assign to: Team A, Team B, or Team C?"
+
+3. **Priority** (`score`): **How urgent/severe is it?**
+   - "Severity: Low, Medium, High, or Critical?"
+   - "Priority: Routine, Standard, or Urgent?"
+
+This consistency makes decisions **predictable, auditable, and easy to act on**.
+
+### Real-World Applications
+
+- **Compliance & Automation**: Flag risky applications, contracts, or transactions
+- **Operational Triage**: Route tickets, incidents, and requests to the right team
+- **Risk Assessment**: Score vendors, customers, transactions for underwriting/approval
+- **Quality Control**: Review content, code, or documentation
+- **Decision Support**: Augment human judgment with structured, consistent reasoning
+- **Fraud Detection**: Identify suspicious patterns and route for investigation
+- **Customer Support**: Triage complaints, determine response level, route to specialists
+- **HR & Recruiting**: Screen resumes, assess candidates, route for interviews
+- **Incident Response**: Classify severity, route to on-call engineer, set SLA
+
+## ⚠️ Important Notes
+
+- These **examples use invented data** — adapt to your own workflows
+- For regulated data (PHI, financial account info, legal docs), ensure **organizational compliance approval** before sending to third-party APIs
+- Always **rotate API keys** before committing or sharing
+- This library translates payloads but doesn't replace human oversight for critical decisions
+
+## 🔗 Resources
+
+- [JEV API Playground](https://jevplayground.com/jev-api)
+- [TypeSafe Official API](https://api.typesafe.ai/)
+- [OpenRouter API](https://openrouter.ai/api/alpha/decisions)
+
+## 📞 Support
+
+- Found a bug? Open an issue
+- Have a question? Check the examples first
+- Want to share a use case? We'd love to hear it!
+
+---
+
+**Star this repo if JEVzilla saves you time or helps you build smarter business decisions!** ⭐

jevzilla-0.1.0/jevzilla/__init__.py

@@ -0,0 +1,294 @@
+"""
+JEVzilla - a tiny, fearless client for JEV.
+
+You write payloads exactly like the JEV API docs (https://jevplayground.com/jev-api):
+
+    {"state": "...", "questions": {"urgent": {"type": "noul", "instructions": "..."}}}
+
+Question types follow the docs: noul (alias: boolean), choice, score.
+Before sending, JEVzilla translates the payload to the wire format the
+playground endpoint (/api/evaluate) expects:
+
+    noul, no criteria   -> {"instructions", "type": "boolean"}
+    noul, with criteria -> {"instructions", "type": "choice", "criteria": {"true": ..., "false": ...}}
+    choice              -> {"instructions", "type": "choice", "criteria": {label: description}}
+    score               -> {"instructions", "type": "score",  "criteria": [level, ...]}
+
+    state (str / dict / list) -> always a string on the playground wire.
+
+backend="typesafe" instead sends the docs format as-is to the official
+endpoint (POST https://api.typesafe.ai/v1/systemone) with a Bearer API key.
+"""
+from __future__ import annotations
+
+import copy
+import json
+import os
+import random
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional, Sequence, Tuple
+
+import requests
+
+__all__ = [
+    "JEVzilla", "JEVResponse", "JEVError", "JEVValidationError", "JEVHTTPError",
+    "to_playground_payload", "to_typesafe_payload",
+    "noul", "choice", "score", "Noul", "Choice", "Score",
+]
+__version__ = "0.3.0"
+
+PLAYGROUND_URL = "https://jevplayground.com/api/evaluate"
+TYPESAFE_URL = "https://api.typesafe.ai/v1/systemone"
+OPENROUTER_URL = "https://openrouter.ai/api/alpha/decisions"
+_ORIGIN = "https://jevplayground.com"
+_RETRY_STATUSES = {429, 502, 503, 504, 529}
+
+# docs-style type names accepted on input -> canonical
+_TYPE_ALIASES = {
+    "noul": "noul", "boolean": "noul", "bool": "noul",
+    "choice": "choice",
+    "score": "score",
+}
+
+
+class JEVError(Exception):
+    """Base error for JEVzilla."""
+
+
+class JEVValidationError(JEVError, ValueError):
+    """Payload could not be translated into a valid JEV request."""
+
+
+class JEVHTTPError(JEVError):
+    def __init__(self, status_code: int, body: str):
+        super().__init__(f"JEV API returned HTTP {status_code}: {body[:300]}")
+        self.status_code = status_code
+        self.body = body
+
+
+# ------------------------------------------------- docs-style builders
+def noul(instructions: str, criteria: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
+    q: Dict[str, Any] = {"type": "noul", "instructions": instructions}
+    if criteria is not None:
+        q["criteria"] = criteria
+    return q
+
+
+def choice(instructions: str, criteria: Dict[str, str]) -> Dict[str, Any]:
+    return {"type": "choice", "instructions": instructions, "criteria": criteria}
+
+
+def score(instructions: str, criteria: Sequence[str]) -> Dict[str, Any]:
+    return {"type": "score", "instructions": instructions, "criteria": list(criteria)}
+
+
+Noul, Choice, Score = noul, choice, score  # mirror the SDK's capitalized names
+
+
+# ------------------------------------------------------ parsing (docs style)
+def _parse_question(name: str, q: Any) -> Tuple[str, str, Any]:
+    """Validate one docs-style question -> (canonical type, instructions, criteria)."""
+    where = f"questions[{name!r}]"
+    if not isinstance(q, dict):
+        raise JEVValidationError(f"{where} must be an object")
+
+    instructions = q.get("instructions")
+    if not isinstance(instructions, str) or not instructions.strip():
+        raise JEVValidationError(f"{where}.instructions must be a non-empty string")
+
+    raw = q.get("type")
+    qtype = _TYPE_ALIASES.get(str(raw).strip().lower()) if raw is not None else None
+    if qtype is None:
+        raise JEVValidationError(f"{where}.type must be one of noul | boolean | choice | score (got {raw!r})")
+
+    criteria = q.get("criteria")
+
+    if qtype == "noul":
+        if criteria in (None, {}, []):
+            return qtype, instructions, None
+        if not isinstance(criteria, dict):
+            raise JEVValidationError(f"{where}.criteria for 'noul' must be an object like {{'true': ..., 'false': ...}}")
+        return qtype, instructions, {str(k): str(v) for k, v in criteria.items()}
+
+    if qtype == "choice":
+        if isinstance(criteria, dict) and criteria:
+            return qtype, instructions, {str(k): str(v) for k, v in criteria.items()}
+        if isinstance(criteria, (list, tuple)) and criteria:   # lenient: ["a","b"] -> {"a":"a","b":"b"}
+            return qtype, instructions, {str(c): str(c) for c in criteria}
+        raise JEVValidationError(f"{where}.criteria must be a non-empty object for 'choice'")
+
+    # score
+    if isinstance(criteria, (list, tuple)) and criteria:
+        return qtype, instructions, [str(c) for c in criteria]
+    raise JEVValidationError(f"{where}.criteria must be a non-empty list of levels for 'score'")
+
+
+def _parse_payload(payload: Dict[str, Any]) -> Tuple[Any, Dict[str, Tuple[str, str, Any]]]:
+    if not isinstance(payload, dict):
+        raise JEVValidationError("payload must be a dict")
+    state = payload.get("state")
+    if state is None or (isinstance(state, str) and not state.strip()) or state in ({}, []):
+        raise JEVValidationError("payload.state must be a non-empty string, object or array")
+    if not isinstance(state, (str, dict, list)):
+        raise JEVValidationError("payload.state must be a string, object or array")
+    questions = payload.get("questions")
+    if not isinstance(questions, dict) or not questions:
+        raise JEVValidationError("payload.questions must be a non-empty dict")
+    parsed = {str(n): _parse_question(str(n), copy.deepcopy(q)) for n, q in questions.items()}
+    return state, parsed
+
+
+# ------------------------------------------------------------- translators
+def to_playground_payload(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """docs-style payload -> the exact shape /api/evaluate expects."""
+    state, parsed = _parse_payload(payload)
+    if not isinstance(state, str):
+        state = json.dumps(state, ensure_ascii=False, indent=2)
+
+    questions: Dict[str, Any] = {}
+    for name, (qtype, instructions, criteria) in parsed.items():
+        if qtype == "noul":
+            if criteria is None:
+                questions[name] = {"instructions": instructions, "type": "boolean"}
+            else:  # true/false criteria -> the "choice" shape from the working example
+                questions[name] = {"instructions": instructions, "type": "choice", "criteria": criteria}
+        else:  # choice / score pass through
+            questions[name] = {"instructions": instructions, "type": qtype, "criteria": criteria}
+    return {"state": state, "questions": questions}
+
+
+def to_typesafe_payload(payload: Dict[str, Any], model: str = "jev-latest") -> Dict[str, Any]:
+    """docs-style payload -> validated body for the official /v1/systemone endpoint."""
+    state, parsed = _parse_payload(payload)
+    questions: Dict[str, Any] = {}
+    for name, (qtype, instructions, criteria) in parsed.items():
+        q = {"type": qtype, "instructions": instructions}
+        if criteria is not None:
+            q["criteria"] = criteria
+        questions[name] = q
+    return {"model": model, "state": state, "questions": questions}
+
+
+# ------------------------------------------------------------------ client
+@dataclass
+class JEVResponse:
+    status_code: int
+    text: str
+    data: Any = None
+    request: Dict[str, Any] = field(default_factory=dict)  # the body actually sent
+
+    @property
+    def ok(self) -> bool:
+        return 200 <= self.status_code < 300
+
+    @property
+    def answers(self) -> Any:
+        """`data["answers"]` when present (official shape), else the raw parsed body."""
+        if isinstance(self.data, dict) and "answers" in self.data:
+            return self.data["answers"]
+        return self.data
+
+    def __getitem__(self, key):
+        return self.answers[key]
+
+    # ---- convenience readers for the real answer shapes ----
+    def noul(self, key: str, threshold: float = 0.5) -> bool:
+        """True/False reading of a noul answer (backend returns a 0-1 probability)."""
+        return self.answers[key]["noul"] >= threshold
+
+    def choice(self, key: str) -> str:
+        return self.answers[key]["choice"]
+
+    def score_label(self, key: str) -> str:
+        a = self.answers[key]
+        return a["legend"][str(round(a["score"]))]
+
+
+class JEVzilla:
+    """
+    >>> jev = JEVzilla()                          # playground endpoint
+    >>> jev.evaluate({
+    ...     "state": "The customer says their production service is down.",
+    ...     "questions": {"urgent": {"type": "noul", "instructions": "Is this request urgent?"}},
+    ... })
+
+    >>> jev = JEVzilla(backend="typesafe")        # official API, reads TYPESAFE_API_KEY
+    """
+
+    def __init__(self, backend: str = "playground", api_key: Optional[str] = None,
+                 model: str = "jev-latest", url: Optional[str] = None, timeout: float = 30.0,
+                 retries: int = 4, backoff: float = 1.0, max_backoff: float = 30.0,
+                 session: Optional[requests.Session] = None,
+                 extra_headers: Optional[Dict[str, str]] = None):
+        if backend not in ("playground", "typesafe", "openrouter"):
+            raise ValueError("backend must be 'playground', 'typesafe' or 'openrouter'")
+        self.backend, self.model, self.timeout = backend, model, timeout
+        self.retries, self.backoff, self.max_backoff = max(0, retries), backoff, max_backoff
+        self.session = session or requests.Session()
+        if backend == "playground":
+            self.url = url or PLAYGROUND_URL
+            self.headers = {"Content-Type": "application/json", "Origin": _ORIGIN, "Referer": _ORIGIN + "/"}
+        elif backend == "typesafe":
+            key = api_key or os.environ.get("TYPESAFE_API_KEY")
+            if not key:
+                raise JEVError("backend='typesafe' needs api_key= or the TYPESAFE_API_KEY env var")
+            self.url = url or TYPESAFE_URL
+            self.headers = {"Content-Type": "application/json", "Authorization": f"Bearer {key}"}
+        else:  # openrouter
+            key = api_key or os.environ.get("OPENROUTER_API_KEY")
+            if not key:
+                raise JEVError("backend='openrouter' needs api_key= or the OPENROUTER_API_KEY env var")
+            self.url = url or OPENROUTER_URL
+            self.model = model if model != "jev-latest" else "typesafe/jev-1.13"
+            self.headers = {"Content-Type": "application/json", "Authorization": f"Bearer {key}"}
+        self.headers.update(extra_headers or {})
+
+    def build(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """The exact body that would be sent, without sending it."""
+        if self.backend == "playground":
+            return to_playground_payload(payload)
+        return to_typesafe_payload(payload, self.model)
+
+    def _sleep_time(self, attempt: int, resp: Optional[requests.Response]) -> float:
+        if resp is not None:
+            ra = resp.headers.get("Retry-After")
+            if ra and ra.replace(".", "", 1).isdigit():
+                return min(float(ra), self.max_backoff)
+        return min(self.backoff * (2 ** attempt), self.max_backoff) * random.uniform(0.75, 1.25)
+
+    def evaluate(self, payload: Dict[str, Any], raise_for_status: bool = True) -> JEVResponse:
+        """POST the translated payload. Retries transient failures (429/502/503/504/529,
+        timeouts, connection errors) with exponential backoff; 4xx like 401/422 are not retried."""
+        body = self.build(payload)
+        r: Optional[requests.Response] = None
+        for attempt in range(self.retries + 1):
+            try:
+                r = self.session.post(self.url, json=body, headers=self.headers, timeout=self.timeout)
+            except (requests.ConnectionError, requests.Timeout):
+                if attempt == self.retries:
+                    raise
+                time.sleep(self._sleep_time(attempt, None))
+                continue
+            if r.status_code in _RETRY_STATUSES and attempt < self.retries:
+                time.sleep(self._sleep_time(attempt, r))
+                continue
+            break
+        try:
+            data = r.json()
+        except ValueError:
+            data = None
+        res = JEVResponse(r.status_code, r.text, data, body)
+        if raise_for_status and not res.ok:
+            raise JEVHTTPError(r.status_code, r.text)
+        return res
+
+    # single-question shortcuts (answer key defaults to "decision")
+    def ask_noul(self, state, instructions, criteria=None, key="decision", **kw) -> JEVResponse:
+        return self.evaluate({"state": state, "questions": {key: noul(instructions, criteria)}}, **kw)
+
+    def ask_choice(self, state, instructions, criteria, key="decision", **kw) -> JEVResponse:
+        return self.evaluate({"state": state, "questions": {key: choice(instructions, criteria)}}, **kw)
+
+    def ask_score(self, state, instructions, levels, key="decision", **kw) -> JEVResponse:
+        return self.evaluate({"state": state, "questions": {key: score(instructions, levels)}}, **kw)

jevzilla-0.1.0/jevzilla.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: jevzilla
+Version: 0.1.0
+Summary: A tiny, fearless client for the JEV evaluation API
+Requires-Python: >=3.8
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Dynamic: license-file

jevzilla-0.1.0/jevzilla.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+jevzilla/__init__.py
+jevzilla.egg-info/PKG-INFO
+jevzilla.egg-info/SOURCES.txt
+jevzilla.egg-info/dependency_links.txt
+jevzilla.egg-info/requires.txt
+jevzilla.egg-info/top_level.txt

jevzilla-0.1.0/jevzilla.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

jevzilla-0.1.0/jevzilla.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.28

jevzilla-0.1.0/jevzilla.egg-info/top_level.txt

@@ -0,0 +1 @@
+jevzilla

jevzilla-0.1.0/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jevzilla"
+version = "0.1.0"
+description = "A tiny, fearless client for the JEV evaluation API"
+requires-python = ">=3.8"
+dependencies = ["requests>=2.28"]
+
+[tool.setuptools]
+packages = ["jevzilla"]

jevzilla-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+