SDKs

import type { AnswerContract } from "@taxorch/contract-types";

/**
 * The three states a caller has to render.
 *
 * Modelled as a discriminated union so the compiler refuses a client that
 * forgot one. That is the whole value of typing this contract: the outcomes
 * that are not a number are two thirds of the API.
 */
export type Outcome =
  | { kind: "answer"; contract: AnswerContract }
  | { kind: "ask"; contract: AnswerContract; questions: MissingFact[] }
  | { kind: "escalate"; contract: AnswerContract; reason: string };

export function toOutcome(contract: AnswerContract): Outcome {
  // Checked first: it is set alongside several statuses and always wins.
  if (contract.human_review_required) {
    return {
      kind: "escalate",
      contract,
      reason: contract.next_actions[0] ?? "Requires human review.",
    };
  }

  if (contract.verification_status === "verified") {
    return { kind: "answer", contract };
  }

  if (contract.verification_status === "needs_facts") {
    return { kind: "ask", contract, questions: contract.missing_facts };
  }

  return {
    kind: "escalate",
    contract,
    reason: contract.next_actions[0] ?? "Outside declared coverage.",
  };
}

/**
 * Whether a figure may be presented as exact.
 *
 * Separate from the outcome, because a verified answer at draft coverage is
 * still a real answer — it just must not be labelled exact.
 */
export function isExact(contract: AnswerContract): boolean {
  return (
    contract.verification_status === "verified" &&
    (contract.coverage_status === "covered" ||
      contract.coverage_status === "beta")
  );
}

from dataclasses import dataclass
from typing import Literal, Union

VERIFIED = "verified"
NEEDS_FACTS = "needs_facts"
EXACT_COVERAGE = {"covered", "beta"}


@dataclass(frozen=True)
class Answer:
    contract: dict


@dataclass(frozen=True)
class Ask:
    contract: dict
    questions: list[dict]


@dataclass(frozen=True)
class Escalate:
    contract: dict
    reason: str


Outcome = Union[Answer, Ask, Escalate]


def to_outcome(contract: dict) -> Outcome:
    """Three states, and no branch that renders a number by default."""
    if contract["human_review_required"]:
        return Escalate(contract, _first_action(contract, "Requires human review."))

    status = contract["verification_status"]

    if status == VERIFIED:
        return Answer(contract)

    if status == NEEDS_FACTS:
        return Ask(contract, contract["missing_facts"])

    return Escalate(contract, _first_action(contract, "Outside declared coverage."))


def is_exact(contract: dict) -> bool:
    """A verified answer at draft coverage is real, but must not be called exact."""
    return (
        contract["verification_status"] == VERIFIED
        and contract["coverage_status"] in EXACT_COVERAGE
    )


def _first_action(contract: dict, fallback: str) -> str:
    actions = contract.get("next_actions") or []
    return actions[0] if actions else fallback

// No Go library exists. This is the equivalent, and it is the
// whole of it — the contract is the interface.
package taxorch

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

type Client struct {
	BaseURL string
	APIKey  string
	HTTP    *http.Client
}

func (c *Client) Answer(question string, site int) (*AnswerContract, error) {
	body, err := json.Marshal(map[string]any{"question": question, "site": site})
	if err != nil {
		return nil, err
	}

	req, err := http.NewRequest("POST", c.BaseURL+"/api/v1/tax-assistant/answer", bytes.NewReader(body))
	if err != nil {
		return nil, err
	}
	req.Header.Set("Authorization", "Bearer "+c.APIKey)
	req.Header.Set("Content-Type", "application/json")

	res, err := c.HTTP.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()

	if res.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("taxorch: %d", res.StatusCode)
	}

	// A 200 may still be an abstention. Branch on VerificationStatus.
	var contract AnswerContract
	if err := json.NewDecoder(res.Body).Decode(&contract); err != nil {
		return nil, err
	}
	return &contract, nil
}