dev-double 0.1.0__py3-none-any.whl

dev_double/__init__.py

@@ -0,0 +1,3 @@
+"""dev-double: a local stand-in for fast decision-model and reranking APIs."""
+
+__version__ = "0.1.0"

dev_double/apps/__init__.py

@@ -0,0 +1 @@
+"""App layer: composition roots (server, cli, client). The only place that picks implementations."""

dev_double/apps/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command line entry point."""
+
+from .main import main
+
+__all__ = ["main"]

dev_double/apps/cli/main.py

@@ -0,0 +1,122 @@
+"""Command line: `dev-double serve` and `dev-double doctor`."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+from ... import __version__
+from ...core.decision.errors import EngineError
+from ...core.decision.t_answer import TBinaryAnswer, TChoiceAnswer
+from ...core.decision.t_question import TBinaryQuestion, TChoiceQuestion
+from ...core.decision.tracker import Tracker
+from ...providers.std.decision.clock_std_impl import ClockStdImpl
+from ..composition import build_decider
+from ..config import ENGINES, Settings
+
+
+def _add_engine_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--engine", choices=list(ENGINES), help="Backend engine (default: openai).")
+    p.add_argument("--base-url", help="OpenAI-compatible base URL (default: Ollama on localhost).")
+    p.add_argument("--model", help="Model name on that server (default: qwen2.5:7b).")
+    p.add_argument("--api-key", help="API key for the model server, if it needs one.")
+    p.add_argument("--max-concurrency", type=int, help="Parallel model calls (default: 4).")
+    p.add_argument(
+        "--systemone-url", help="Kev/Laya server for --engine systemone (default: http://localhost:8000)."
+    )
+
+
+def _settings(args: argparse.Namespace) -> Settings:
+    s = Settings.from_env()
+    for name in ("engine", "base_url", "model", "api_key", "max_concurrency", "record", "systemone_url"):
+        value = getattr(args, name, None)
+        if value is not None:
+            setattr(s, name, value)
+    return s
+
+
+def serve(args: argparse.Namespace) -> int:
+    import uvicorn
+
+    from ..server.app import create_app
+
+    settings = _settings(args)
+    print(f"dev-double {__version__}: engine={settings.engine} model={settings.model}")
+    if settings.engine == "openai":
+        print(f"  model server: {settings.base_url}")
+    if settings.engine == "systemone":
+        print(f"  System 1 server: {settings.systemone_url}")
+    if settings.record:
+        print(f"  recording calls to: {settings.record}")
+    uvicorn.run(create_app(settings), host=args.host, port=args.port, log_level="info")
+    return 0
+
+
+async def _doctor(settings: Settings) -> int:
+    settings.max_concurrency = 1
+    decider = build_decider(settings)
+    print(f"Checking engine={decider.name} model={decider.model} ...")
+    ok = True
+    t = Tracker(ClockStdImpl())
+    try:
+        yes = await decider.ask(
+            "The package arrived broken and I want my money back.",
+            TBinaryQuestion(question="Is the customer asking for a refund?"),
+            t,
+        )
+        pick = await decider.ask(
+            "My flight was cancelled, please put me on the next one.",
+            TChoiceQuestion(
+                question="What does the customer want?",
+                options={
+                    "refund": "Money returned.",
+                    "rebooking": "A replacement flight.",
+                    "information": "Only information.",
+                },
+            ),
+            t,
+        )
+    except EngineError as exc:
+        print(f"FAIL  {exc}")
+        return 1
+    finally:
+        await decider.aclose()
+
+    assert isinstance(yes, TBinaryAnswer) and isinstance(pick, TChoiceAnswer)
+    meta = t.meta(decider.name, decider.model)
+    print(f"  binary: refund? p(yes)={yes.probability}  (expected high)")
+    print(f"  choice: {pick.value}  {pick.probabilities}  (expected rebooking)")
+    print(f"  latency: {meta.latency_ms} ms for 2 questions")
+    for w in meta.warnings:
+        ok = False
+        print(f"WARN  {w}")
+    if yes.probability < 0.5 or pick.value != "rebooking":
+        ok = False
+        print("WARN  Answers look wrong; this model may be too small for your use case.")
+    print("OK" if ok else "Finished with warnings.")
+    return 0 if ok else 2
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="dev-double", description=__doc__)
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_serve = sub.add_parser("serve", help="Run the HTTP server.")
+    _add_engine_args(p_serve)
+    p_serve.add_argument("--host", default="127.0.0.1")
+    p_serve.add_argument("--port", type=int, default=8787)
+    p_serve.add_argument("--record", help="Append every call to this JSONL file.")
+    p_serve.set_defaults(func=serve)
+
+    p_doc = sub.add_parser("doctor", help="Check that the model server works and returns logprobs.")
+    _add_engine_args(p_doc)
+    p_doc.set_defaults(func=lambda a: asyncio.run(_doctor(_settings(a))))
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dev_double/apps/client/__init__.py

@@ -0,0 +1,5 @@
+"""The sync HTTP SDK client."""
+
+from .http_client import DevDouble
+
+__all__ = ["DevDouble"]

dev_double/apps/client/http_client.py

@@ -0,0 +1,102 @@
+"""A thin synchronous client for the dev-double server.
+
+Keep this client behind your own interface in your codebase. When the real
+decision engine is approved, write a second implementation of that interface
+against the vendor's SDK and switch over; the rest of your harness stays.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class DevDouble:
+    def __init__(self, base_url: str = "http://127.0.0.1:8787", timeout: float = 120.0) -> None:
+        self._http = httpx.Client(base_url=base_url.rstrip("/"), timeout=timeout)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "DevDouble":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        response = self._http.post(path, json={k: v for k, v in body.items() if v is not None})
+        response.raise_for_status()
+        return response.json()
+
+    def decide(self, input: Any, questions: dict[str, dict[str, Any]]) -> dict[str, Any]:
+        return self._post("/v1/decide", {"input": input, "questions": questions})
+
+    def route(self, input: Any, routes: dict[str, str] | None = None) -> dict[str, Any]:
+        return self._post("/v1/route", {"input": input, "routes": routes})
+
+    def guard(
+        self,
+        input: Any,
+        policies: dict[str, str] | None = None,
+        scope: str | None = None,
+        threshold: float | None = None,
+    ) -> dict[str, Any]:
+        return self._post(
+            "/v1/guard", {"input": input, "policies": policies, "scope": scope, "threshold": threshold}
+        )
+
+    def gate(
+        self,
+        tool: str,
+        arguments: dict[str, Any] | str | None = None,
+        context: Any = None,
+        policy: str | None = None,
+        outcomes: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        return self._post(
+            "/v1/gate",
+            {
+                "tool_call": {"name": tool, "arguments": arguments or {}},
+                "context": context,
+                "policy": policy,
+                "outcomes": outcomes,
+            },
+        )
+
+    def classify(
+        self,
+        labels: dict[str, str],
+        input: Any = None,
+        inputs: list[Any] | None = None,
+        question: str | None = None,
+    ) -> dict[str, Any]:
+        return self._post(
+            "/v1/classify", {"labels": labels, "input": input, "inputs": inputs, "question": question}
+        )
+
+    def judge(
+        self,
+        output: Any,
+        input: Any = None,
+        reference: Any = None,
+        criteria: str | None = None,
+        levels: list[str] | None = None,
+    ) -> dict[str, Any]:
+        return self._post(
+            "/v1/judge",
+            {"output": output, "input": input, "reference": reference, "criteria": criteria, "levels": levels},
+        )
+
+    def rerank(
+        self, query: str, documents: list[str], top_n: int | None = None, return_documents: bool = False
+    ) -> dict[str, Any]:
+        return self._post(
+            "/v1/rerank",
+            {"query": query, "documents": documents, "top_n": top_n, "return_documents": return_documents},
+        )
+
+    def extract(self, input: Any, fields: dict[str, dict[str, Any]]) -> dict[str, Any]:
+        """``fields``: name -> {"type": string|number|integer|boolean|enum, "description"?, "options"?}."""
+        return self._post("/v1/extract", {"input": input, "fields": fields})

dev_double/apps/composition.py

@@ -0,0 +1,71 @@
+"""The composition root: the only place that picks implementations.
+
+To add an engine: implement ``IEngine`` (a model that scores labels) or
+``IDecider`` (a model that answers typed questions natively) under
+``providers/<name>/decision/``, then add a branch here and to ``ENGINES``.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ..core.decision.decider_basic_impl import DeciderBasicImpl
+from ..core.decision.decision_service_basic_impl import DecisionServiceBasicImpl
+from ..core.decision.i_decider import IDecider
+from ..core.decision.i_engine import IEngine
+from ..providers.std.decision.clock_std_impl import ClockStdImpl
+from ..providers.std.decision.id_provider_std_impl import IdProviderStdImpl
+from .config import ENGINES, Settings
+
+
+def _unknown(engine: str) -> ValueError:
+    return ValueError(f"Unknown engine {engine!r}; expected one of: {', '.join(ENGINES)}.")
+
+
+def build_engine(settings: Settings) -> IEngine:
+    """The label-scoring engine for prompt-based engines (openai, mock)."""
+    if settings.engine == "mock":
+        from ..providers.mock.decision.engine_mock_impl import EngineMockImpl
+
+        return EngineMockImpl()
+    if settings.engine == "openai":
+        from ..providers.openai.decision.engine_openai_impl import EngineOpenAIImpl
+
+        return EngineOpenAIImpl(
+            base_url=settings.base_url,
+            model=settings.model,
+            api_key=settings.api_key,
+            timeout=settings.timeout,
+        )
+    raise _unknown(settings.engine)
+
+
+def build_decider(settings: Settings, engine: Optional[IEngine] = None) -> IDecider:
+    if engine is not None or settings.engine in ("openai", "mock"):
+        return DeciderBasicImpl(engine or build_engine(settings), settings.max_concurrency)
+    if settings.engine == "systemone":
+        from ..providers.systemone.decision.decider_system_one_impl import DeciderSystemOneImpl
+
+        return DeciderSystemOneImpl(
+            "systemone",
+            settings.systemone_url,
+            settings.api_key,
+            max_concurrency=settings.max_concurrency,
+            timeout=settings.timeout,
+        )
+    if settings.engine == "needle":
+        from ..providers.needle.decision.decider_needle_impl import DeciderNeedleImpl
+
+        return DeciderNeedleImpl()
+    raise _unknown(settings.engine)
+
+
+def build_service(
+    settings: Settings,
+    engine: Optional[IEngine] = None,
+    decider: Optional[IDecider] = None,
+) -> DecisionServiceBasicImpl:
+    """The use-case service. Pass ``engine`` or ``decider`` to override the configured one."""
+    return DecisionServiceBasicImpl(
+        decider or build_decider(settings, engine), ClockStdImpl(), IdProviderStdImpl()
+    )

dev_double/apps/config.py

@@ -0,0 +1,36 @@
+"""Settings from environment variables (CLI flags override them)."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+ENV_PREFIX = "DEV_DOUBLE_"
+ENGINES = ("openai", "mock", "systemone", "needle")
+
+
+@dataclass
+class Settings:
+    engine: str = "openai"  # one of ENGINES
+    base_url: str = "http://localhost:11434/v1"  # OpenAI-compatible server (engine=openai)
+    model: str = "qwen2.5:7b"
+    api_key: Optional[str] = None
+    max_concurrency: int = 4
+    timeout: float = 120.0
+    record: Optional[str] = None
+    systemone_url: str = "http://localhost:8000"  # Kev / Laya server (engine=systemone)
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        s = cls()
+        env = os.environ
+        s.engine = env.get(ENV_PREFIX + "ENGINE", s.engine)
+        s.base_url = env.get(ENV_PREFIX + "BASE_URL", s.base_url)
+        s.model = env.get(ENV_PREFIX + "MODEL", s.model)
+        s.api_key = env.get(ENV_PREFIX + "API_KEY", s.api_key)
+        s.max_concurrency = int(env.get(ENV_PREFIX + "MAX_CONCURRENCY", s.max_concurrency))
+        s.timeout = float(env.get(ENV_PREFIX + "TIMEOUT", s.timeout))
+        s.record = env.get(ENV_PREFIX + "RECORD", s.record)
+        s.systemone_url = env.get(ENV_PREFIX + "SYSTEMONE_URL", s.systemone_url)
+        return s

dev_double/apps/server/__init__.py

@@ -0,0 +1,5 @@
+"""The HTTP server."""
+
+from .app import create_app
+
+__all__ = ["create_app"]

dev_double/apps/server/app.py

@@ -0,0 +1,122 @@
+"""The HTTP server: maps transport schemas to the core use-case service."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import Optional
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from ... import __version__
+from ...core.decision.errors import EngineError
+from ...core.decision.i_decider import IDecider
+from ...core.decision.i_decision_service import IDecisionService
+from ...core.decision.i_engine import IEngine
+from ..composition import build_service
+from ..config import Settings
+from .recorder import install_recorder
+from .transport import (
+    ClassifyRequest,
+    ClassifyResponse,
+    DecideRequest,
+    DecideResponse,
+    ExtractRequest,
+    ExtractResponse,
+    GateRequest,
+    GateResponse,
+    GuardRequest,
+    GuardResponse,
+    JudgeRequest,
+    JudgeResponse,
+    RerankRequest,
+    RerankResponse,
+    RouteRequest,
+    RouteResponse,
+)
+
+
+def create_app(
+    settings: Optional[Settings] = None,
+    engine: Optional[IEngine] = None,
+    decider: Optional[IDecider] = None,
+) -> FastAPI:
+    """``engine`` / ``decider`` override the one ``settings`` would build."""
+    settings = settings or Settings.from_env()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):  # type: ignore[no-untyped-def]
+        svc = build_service(settings, engine=engine, decider=decider)
+        app.state.service = svc
+        try:
+            yield
+        finally:
+            await svc.aclose()
+
+    app = FastAPI(
+        title="dev-double",
+        version=__version__,
+        description=(
+            "A local stand-in for fast decision-model and reranking APIs. "
+            "Build against it now; point your client at the real engine later."
+        ),
+        lifespan=lifespan,
+    )
+
+    @app.exception_handler(EngineError)
+    async def _engine_error(_: Request, exc: EngineError) -> JSONResponse:
+        return JSONResponse(status_code=502, content={"error": "engine_error", "detail": str(exc)})
+
+    if settings.record:
+        install_recorder(app, settings.record)
+
+    def service(request: Request) -> IDecisionService:
+        return request.app.state.service
+
+    @app.get("/health")
+    async def health(request: Request) -> dict:
+        svc = service(request)
+        return {"status": "ok", "engine": svc.name, "model": svc.model}
+
+    @app.post("/v1/decide", response_model=DecideResponse, response_model_exclude_none=True)
+    async def decide(req: DecideRequest, request: Request):  # type: ignore[no-untyped-def]
+        """Generic decision: binary, choice, and scale questions about one input."""
+        return DecideResponse.from_core(await service(request).decide(req.to_core()))
+
+    @app.post("/v1/route", response_model=RouteResponse)
+    async def route(req: RouteRequest, request: Request):  # type: ignore[no-untyped-def]
+        """Pick which model (or handler) should take a request."""
+        return RouteResponse.from_core(await service(request).route(req.to_core()))
+
+    @app.post("/v1/guard", response_model=GuardResponse)
+    async def guard(req: GuardRequest, request: Request):  # type: ignore[no-untyped-def]
+        """Screen input for injection, abuse, or off-topic use before it reaches an LLM."""
+        return GuardResponse.from_core(await service(request).guard(req.to_core()))
+
+    @app.post("/v1/gate", response_model=GateResponse)
+    async def gate(req: GateRequest, request: Request):  # type: ignore[no-untyped-def]
+        """Decide whether an agent's tool call is allowed, needs confirmation, or is denied."""
+        return GateResponse.from_core(await service(request).gate(req.to_core()))
+
+    @app.post("/v1/classify", response_model=ClassifyResponse)
+    async def classify(req: ClassifyRequest, request: Request):  # type: ignore[no-untyped-def]
+        """Label one item or a batch: inbox triage, intent detection, bulk labeling."""
+        return ClassifyResponse.from_core(await service(request).classify(req.to_core()))
+
+    @app.post("/v1/judge", response_model=JudgeResponse)
+    async def judge(req: JudgeRequest, request: Request):  # type: ignore[no-untyped-def]
+        """Score an LLM output against a rubric."""
+        return JudgeResponse.from_core(await service(request).judge(req.to_core()))
+
+    @app.post("/v1/extract", response_model=ExtractResponse, response_model_exclude_none=True)
+    async def extract(req: ExtractRequest, request: Request):  # type: ignore[no-untyped-def]
+        """Pull typed fields out of text: invoices, tickets, bookings, tool-call arguments."""
+        return ExtractResponse.from_core(await service(request).extract(req.to_core()))
+
+    @app.post("/v1/rerank", response_model=RerankResponse, response_model_exclude_none=True)
+    @app.post("/v2/rerank", response_model=RerankResponse, response_model_exclude_none=True)
+    async def rerank(req: RerankRequest, request: Request):  # type: ignore[no-untyped-def]
+        """Order documents by relevance to a query. Cohere-style wire format."""
+        return RerankResponse.from_core(await service(request).rerank(req.to_core()))
+
+    return app

dev_double/apps/server/recorder.py

@@ -0,0 +1,62 @@
+"""Appends every API call to a JSONL file, so you can replay the same
+traffic against the real engine later and compare."""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import Response
+
+
+class Recorder:
+    def __init__(self, path: str) -> None:
+        self._path = path
+        self._lock = threading.Lock()
+
+    def write(self, entry: dict) -> None:
+        line = json.dumps(entry, ensure_ascii=False)
+        with self._lock, open(self._path, "a", encoding="utf-8") as f:
+            f.write(line + "\n")
+
+
+def install_recorder(app: FastAPI, path: str) -> None:
+    """Record every POST: request, response, status, and latency."""
+    recorder = Recorder(path)
+
+    @app.middleware("http")
+    async def _record(request: Request, call_next):  # type: ignore[no-untyped-def]
+        if request.method != "POST":
+            return await call_next(request)
+        started = time.perf_counter()
+        body = await request.body()
+        response = await call_next(request)
+        chunks = [chunk async for chunk in response.body_iterator]
+        raw = b"".join(chunks)
+        recorder.write(
+            {
+                "ts": datetime.now(timezone.utc).isoformat(),
+                "path": request.url.path,
+                "status": response.status_code,
+                "latency_ms": round((time.perf_counter() - started) * 1000),
+                "request": _json_or_text(body),
+                "response": _json_or_text(raw),
+            }
+        )
+        return Response(
+            content=raw,
+            status_code=response.status_code,
+            headers=dict(response.headers),
+            media_type=response.media_type,
+        )
+
+
+def _json_or_text(raw: bytes) -> Any:
+    try:
+        return json.loads(raw)
+    except ValueError:
+        return raw.decode("utf-8", errors="replace")

dev_double/apps/server/transport/__init__.py

@@ -0,0 +1,39 @@
+"""HTTP transport schemas: pydantic models that validate requests, describe the
+OpenAPI schema, and map to and from the core T-types. All serialization lives here."""
+
+from .choice_use_cases import (
+    Classification,
+    ClassifyRequest,
+    ClassifyResponse,
+    GateRequest,
+    GateResponse,
+    RouteRequest,
+    RouteResponse,
+    ToolCall,
+)
+from .common import InputValue, Meta, Usage
+from .decide import (
+    Answer,
+    BinaryAnswer,
+    BinaryQuestion,
+    ChoiceAnswer,
+    ChoiceQuestion,
+    DecideRequest,
+    DecideResponse,
+    Question,
+    ScaleAnswer,
+    ScaleQuestion,
+)
+from .extract import ExtractField, ExtractRequest, ExtractResponse, FieldValue
+from .guard_judge import GuardCheck, GuardRequest, GuardResponse, JudgeRequest, JudgeResponse
+from .rerank import RerankDocument, RerankRequest, RerankResponse, RerankResult
+
+__all__ = [
+    "Answer", "BinaryAnswer", "BinaryQuestion", "ChoiceAnswer", "ChoiceQuestion",
+    "Classification", "ClassifyRequest", "ClassifyResponse", "DecideRequest", "DecideResponse",
+    "ExtractField", "ExtractRequest", "ExtractResponse", "FieldValue",
+    "GateRequest", "GateResponse", "GuardCheck", "GuardRequest", "GuardResponse", "InputValue",
+    "JudgeRequest", "JudgeResponse", "Meta", "Question", "RerankDocument", "RerankRequest",
+    "RerankResponse", "RerankResult", "RouteRequest", "RouteResponse", "ScaleAnswer",
+    "ScaleQuestion", "ToolCall", "Usage",
+]