OpenDecision 0.1.1__py3-none-any.whl

opendecision/__init__.py

@@ -0,0 +1,24 @@
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    from opendecision.engine import OpenDecisionEngine
+
+
+try:
+    __version__ = version("OpenDecision")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+
+__all__ = ["OpenDecisionEngine", "__version__"]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "OpenDecisionEngine":
+        from opendecision.engine import OpenDecisionEngine
+
+        return OpenDecisionEngine
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

opendecision/__main__.py

@@ -0,0 +1,4 @@
+from opendecision.cli import main
+
+
+raise SystemExit(main())

opendecision/api/app.py

@@ -0,0 +1,231 @@
+import json
+import os
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException, Request
+
+from opendecision import __version__
+from opendecision.api.schemas import (
+    ChoiceQuestion,
+    DocumentDecisionRequest,
+    DocumentDecisionResponse,
+    NoulQuestion,
+    RelationQuestion,
+    ScoreQuestion,
+    SystemOneRequest,
+    SystemOneResponse,
+    Usage,
+)
+from opendecision.engine import (
+    DEFAULT_MODEL,
+    OpenDecisionEngine,
+)
+from opendecision.documents import DocumentDecisionService
+
+
+API_MODEL_NAME = "modernbert-large-zeroshot-v2"
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    print("Starting OpenDecision...")
+
+    # Load once when the server starts.
+    model = os.environ.get("OPENDECISION_MODEL", DEFAULT_MODEL)
+    app.state.engine = OpenDecisionEngine(
+        model=model,
+    )
+    app.state.model_name = model
+
+    print("OpenDecision ready.")
+
+    yield
+
+    print("Stopping OpenDecision...")
+
+
+app = FastAPI(
+    title="OpenDecision",
+    description="Open-source semantic decision engine.",
+    version=__version__,
+    lifespan=lifespan,
+)
+
+
+@app.get("/health")
+def health():
+    return {
+        "status": "ok",
+        "service": "OpenDecision",
+    }
+
+
+def estimate_input_tokens(
+    engine: OpenDecisionEngine,
+    payload: SystemOneRequest,
+) -> int:
+    """
+    Approximate logical API input size.
+
+    This is NOT currently intended to represent actual transformer
+    compute, because zero-shot classification may evaluate the same
+    state against multiple candidate hypotheses.
+    """
+
+    serialized = json.dumps(
+        payload.model_dump(),
+        ensure_ascii=False,
+        sort_keys=True,
+    )
+
+    tokens = engine.classifier.tokenizer(
+        serialized,
+        add_special_tokens=False,
+    )
+
+    return len(tokens["input_ids"])
+
+
+@app.post(
+    "/v1/systemone",
+    response_model=SystemOneResponse,
+)
+def system_one(
+    payload: SystemOneRequest,
+    request: Request,
+):
+    engine: OpenDecisionEngine = request.app.state.engine
+
+    answers = {}
+
+    for question_name, question in payload.questions.items():
+
+        if isinstance(question, ChoiceQuestion):
+
+            result = engine.choice(
+                state=payload.state,
+                instructions=question.instructions,
+                criteria=question.criteria,
+            )
+
+        elif isinstance(question, NoulQuestion):
+
+            criteria = None
+
+            if question.criteria is not None:
+                criteria = question.criteria.model_dump()
+
+            result = engine.noul(
+                state=payload.state,
+                instructions=question.instructions,
+                criteria=criteria,
+            )
+
+        elif isinstance(question, RelationQuestion):
+
+            result = engine.relation(
+                state=payload.state,
+                proposition=question.proposition,
+                contradiction=question.contradiction,
+                threshold=question.threshold,
+            )
+
+        elif isinstance(question, ScoreQuestion):
+
+            result = engine.score(
+                state=payload.state,
+                instructions=question.instructions,
+                criteria=question.criteria,
+            )
+
+        else:
+            raise HTTPException(
+                status_code=422,
+                detail=f"Unsupported question type for {question_name}",
+            )
+
+        answers[question_name] = result
+
+    return SystemOneResponse(
+        model=getattr(request.app.state, "model_name", API_MODEL_NAME),
+        answers=answers,
+        usage=Usage(
+            input_tokens=estimate_input_tokens(engine, payload),
+            output_tokens=0,
+        ),
+    )
+
+
+@app.post(
+    "/v1/documents/decide",
+    response_model=DocumentDecisionResponse,
+)
+def decide_document(
+    payload: DocumentDecisionRequest,
+    request: Request,
+):
+    engine: OpenDecisionEngine = request.app.state.engine
+    service = DocumentDecisionService(
+        engine,
+        top_k=payload.top_k,
+        chunk_tokens=payload.chunk_tokens,
+    )
+    try:
+        chunks = service.chunks(payload.document)
+    except ValueError as error:
+        raise HTTPException(status_code=422, detail=str(error)) from error
+    answers = {}
+
+    for question_name, question in payload.questions.items():
+        if isinstance(question, ChoiceQuestion):
+            result = service.choice(
+                chunks=chunks,
+                instructions=question.instructions,
+                criteria=question.criteria,
+            )
+        elif isinstance(question, NoulQuestion):
+            criteria = (
+                question.criteria.model_dump()
+                if question.criteria is not None
+                else None
+            )
+            result = service.noul(
+                chunks=chunks,
+                instructions=question.instructions,
+                criteria=criteria,
+                mode=payload.noul_mode,
+            )
+        elif isinstance(question, RelationQuestion):
+            result = service.relation(
+                chunks=chunks,
+                proposition=question.proposition,
+                contradiction=question.contradiction,
+                threshold=question.threshold,
+            )
+        elif isinstance(question, ScoreQuestion):
+            result = service.score(
+                chunks=chunks,
+                instructions=question.instructions,
+                criteria=question.criteria,
+            )
+        else:
+            raise HTTPException(
+                status_code=422,
+                detail=f"Unsupported question type for {question_name}",
+            )
+
+        answers[question_name] = result
+
+    token_payload = SystemOneRequest(
+        state=payload.document,
+        questions=payload.questions,
+    )
+    return DocumentDecisionResponse(
+        model=getattr(request.app.state, "model_name", API_MODEL_NAME),
+        chunks=len(chunks),
+        answers=answers,
+        usage=Usage(
+            input_tokens=estimate_input_tokens(engine, token_payload),
+            output_tokens=0,
+        ),
+    )

opendecision/api/schemas.py

@@ -0,0 +1,107 @@
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class ChoiceQuestion(BaseModel):
+    type: Literal["choice"]
+    instructions: str
+    criteria: dict[str, str | None]
+
+    @field_validator("criteria")
+    @classmethod
+    def validate_criteria(cls, value):
+        if len(value) < 2:
+            raise ValueError("Choice requires at least two criteria.")
+        return value
+
+
+class NoulCriteria(BaseModel):
+    true: str
+    false: str
+
+
+class NoulQuestion(BaseModel):
+    type: Literal["noul"]
+    instructions: str
+    criteria: NoulCriteria | None = None
+
+
+class RelationQuestion(BaseModel):
+    type: Literal["relation"]
+    proposition: str
+    contradiction: str
+    threshold: float = Field(default=0.5, gt=0.0, lt=1.0)
+
+
+class ScoreQuestion(BaseModel):
+    type: Literal["score"]
+    instructions: str
+    criteria: list[str]
+
+    @field_validator("criteria")
+    @classmethod
+    def validate_criteria(cls, value):
+        if len(value) < 2:
+            raise ValueError("Score requires at least two levels.")
+
+        if len(set(value)) != len(value):
+            raise ValueError("Score criteria must be unique.")
+
+        return value
+
+
+Question = Annotated[
+    ChoiceQuestion | NoulQuestion | RelationQuestion | ScoreQuestion,
+    Field(discriminator="type"),
+]
+
+
+class SystemOneRequest(BaseModel):
+    state: Any
+
+    # Optional for now.
+    # This will help later when we point the official SDK at OpenDecision.
+    model: str | None = None
+
+    questions: dict[str, Question]
+
+    @field_validator("questions")
+    @classmethod
+    def validate_questions(cls, value):
+        if not value:
+            raise ValueError("At least one question is required.")
+        return value
+
+
+class Usage(BaseModel):
+    input_tokens: int
+    output_tokens: int
+
+
+class SystemOneResponse(BaseModel):
+    model: str
+    answers: dict[str, dict[str, Any]]
+    usage: Usage
+
+
+class DocumentDecisionRequest(BaseModel):
+    document: Any
+    questions: dict[str, Question]
+    noul_mode: Literal["binary", "three_way", "both"] = "both"
+    top_k: int = Field(default=4, ge=1, le=20)
+    chunk_tokens: int = Field(default=384, ge=32, le=4096)
+
+    @field_validator("questions")
+    @classmethod
+    def validate_document_questions(cls, value):
+        if not value:
+            raise ValueError("At least one question is required.")
+        return value
+
+
+class DocumentDecisionResponse(BaseModel):
+    model: str
+    chunks: int
+    answers: dict[str, dict[str, Any]]
+    usage: Usage

opendecision/cli.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import argparse
+import os
+from collections.abc import Sequence
+
+import uvicorn
+
+from opendecision import __version__
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="opendecision",
+        description="Run the OpenDecision API server.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    commands = parser.add_subparsers(dest="command")
+    serve = commands.add_parser("serve", help="Start the API server.")
+    serve.add_argument("--host", default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=8000)
+    serve.add_argument(
+        "--model",
+        help="Hugging Face model name or local model path.",
+    )
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    if args.model:
+        os.environ["OPENDECISION_MODEL"] = args.model
+
+    uvicorn.run(
+        "opendecision.api.app:app",
+        host=args.host,
+        port=args.port,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())