simjecture 0.1.0__py3-none-any.whl

conjecture_solver/llm.py

@@ -0,0 +1,228 @@
+"""OpenAI-compatible provider client with explicit cheap/escalation routing."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+import httpx
+
+DEFAULT_BASE_URL = "https://cp.compshare.cn/v1"
+DEFAULT_MODEL = "deepseek-v4-flash-0731"
+ESCALATION_MODEL = "glm-5.2"
+DEEPSEEK_BASE_URL = "https://api.deepseek.com"
+DEEPSEEK_DEFAULT_MODEL = "deepseek-v4-flash"
+DEEPSEEK_ESCALATION_MODEL = "deepseek-v4-pro"
+
+
+class ModelRoute(StrEnum):
+    DEFAULT = "default"
+    ESCALATION = "escalation"
+
+
+class MissingCredential(RuntimeError):
+    pass
+
+
+class EscalationReasonRequired(ValueError):
+    pass
+
+
+class IncompleteCompletion(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class ModelSelection:
+    model: str
+    route: ModelRoute
+    reason: str
+
+
+@dataclass(frozen=True)
+class CompletionResult:
+    request_id: str
+    model: str
+    content: str
+    finish_reason: str
+    usage: dict[str, Any]
+    route: ModelRoute
+    route_reason: str
+
+
+class ModelPolicy:
+    def __init__(
+        self,
+        *,
+        default_model: str = DEFAULT_MODEL,
+        escalation_model: str = ESCALATION_MODEL,
+    ) -> None:
+        self.default_model = default_model
+        self.escalation_model = escalation_model
+
+    @classmethod
+    def from_environment(cls) -> ModelPolicy:
+        return cls(
+            default_model=os.getenv("ACS_DEFAULT_MODEL", DEFAULT_MODEL),
+            escalation_model=os.getenv("ACS_ESCALATION_MODEL", ESCALATION_MODEL),
+        )
+
+    def select(
+        self,
+        route: ModelRoute = ModelRoute.DEFAULT,
+        *,
+        escalation_reason: str | None = None,
+    ) -> ModelSelection:
+        if route is ModelRoute.ESCALATION:
+            if not escalation_reason or not escalation_reason.strip():
+                raise EscalationReasonRequired(
+                    "escalation routing requires a recorded escalation reason"
+                )
+            return ModelSelection(
+                model=self.escalation_model,
+                route=route,
+                reason=escalation_reason.strip(),
+            )
+        return ModelSelection(
+            model=self.default_model,
+            route=route,
+            reason="default low-cost reasoning route",
+        )
+
+
+class OpenAICompatibleClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_seconds: float = 120.0,
+        policy: ModelPolicy | None = None,
+        provider_name: str = "openai-compatible",
+        credential_source: str | None = None,
+    ) -> None:
+        if not api_key:
+            raise MissingCredential("API key is empty")
+        self._api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout_seconds = timeout_seconds
+        self.policy = policy or ModelPolicy.from_environment()
+        self.provider_name = provider_name
+        self.credential_source = credential_source
+
+    @classmethod
+    def from_environment(
+        cls,
+        *,
+        timeout_seconds: float | None = None,
+    ) -> OpenAICompatibleClient:
+        configured_provider = os.getenv("ACS_MODEL_PROVIDER", "").strip().casefold()
+        if configured_provider not in {"", "deepseek", "compshare"}:
+            raise ValueError(
+                "ACS_MODEL_PROVIDER must be 'deepseek' or 'compshare'"
+            )
+        deepseek_key = os.getenv("DEEPSEEK_API_KEY")
+        compshare_key = os.getenv("CP_API_KEY")
+        use_deepseek = configured_provider == "deepseek" or (
+            not configured_provider and bool(deepseek_key)
+        )
+        if use_deepseek:
+            if not deepseek_key:
+                raise MissingCredential(
+                    "ACS_MODEL_PROVIDER=deepseek requires DEEPSEEK_API_KEY"
+                )
+            api_key = deepseek_key
+            base_url = os.getenv("DEEPSEEK_API_BASE_URL", DEEPSEEK_BASE_URL)
+            default_model = DEEPSEEK_DEFAULT_MODEL
+            escalation_model = DEEPSEEK_ESCALATION_MODEL
+            provider_name = "deepseek"
+            credential_source = "DEEPSEEK_API_KEY"
+        else:
+            if not compshare_key:
+                raise MissingCredential(
+                    "set DEEPSEEK_API_KEY for the official DeepSeek API or "
+                    "CP_API_KEY for the legacy CompShare route"
+                )
+            api_key = compshare_key
+            base_url = os.getenv("CP_API_BASE_URL", DEFAULT_BASE_URL)
+            default_model = DEFAULT_MODEL
+            escalation_model = ESCALATION_MODEL
+            provider_name = "compshare"
+            credential_source = "CP_API_KEY"
+        configured_timeout = float(os.getenv("ACS_MODEL_TIMEOUT_SECONDS", "300"))
+        return cls(
+            api_key=api_key,
+            base_url=base_url,
+            timeout_seconds=(
+                configured_timeout if timeout_seconds is None else timeout_seconds
+            ),
+            policy=ModelPolicy(
+                default_model=os.getenv("ACS_DEFAULT_MODEL", default_model),
+                escalation_model=os.getenv(
+                    "ACS_ESCALATION_MODEL", escalation_model
+                ),
+            ),
+            provider_name=provider_name,
+            credential_source=credential_source,
+        )
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def list_models(self) -> tuple[str, ...]:
+        with httpx.Client(timeout=self.timeout_seconds) as client:
+            response = client.get(f"{self.base_url}/models", headers=self._headers())
+            response.raise_for_status()
+        payload = response.json()
+        return tuple(item["id"] for item in payload.get("data", ()) if "id" in item)
+
+    def complete(
+        self,
+        messages: list[dict[str, str]],
+        *,
+        route: ModelRoute = ModelRoute.DEFAULT,
+        escalation_reason: str | None = None,
+        max_tokens: int | None = None,
+        temperature: float = 0.0,
+    ) -> CompletionResult:
+        selection = self.policy.select(route, escalation_reason=escalation_reason)
+        request = {
+            "model": selection.model,
+            "messages": messages,
+            "temperature": temperature,
+            "stream": False,
+        }
+        if max_tokens is not None:
+            request["max_tokens"] = max_tokens
+        with httpx.Client(timeout=self.timeout_seconds) as client:
+            response = client.post(
+                f"{self.base_url}/chat/completions",
+                headers=self._headers(),
+                json=request,
+            )
+            response.raise_for_status()
+        payload = response.json()
+        choices = payload.get("choices") or []
+        if not choices:
+            raise IncompleteCompletion("provider returned no completion choice")
+        choice = choices[0]
+        content = (choice.get("message") or {}).get("content") or ""
+        if not content.strip():
+            raise IncompleteCompletion(
+                "provider returned no usable completion content"
+            )
+        finish_reason = choice.get("finish_reason") or "unknown"
+        return CompletionResult(
+            request_id=str(payload.get("id", "")),
+            model=str(payload.get("model", selection.model)),
+            content=content,
+            finish_reason=finish_reason,
+            usage=dict(payload.get("usage") or {}),
+            route=selection.route,
+            route_reason=selection.reason,
+        )

conjecture_solver/models.py

@@ -0,0 +1,279 @@
+"""Versioned scientific records shared by reasoning and deterministic tools."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any, Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+def new_id(prefix: str) -> str:
+    return f"{prefix}_{uuid4().hex}"
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=True,
+        str_strip_whitespace=True,
+        allow_inf_nan=False,
+    )
+
+
+class PropositionClass(StrEnum):
+    EXISTENTIAL_CONTRIBUTION = "existential_contribution"
+    UNIVERSAL_NON_CONTRIBUTION = "universal_non_contribution"
+    PREDICTIVE_SUFFICIENCY = "predictive_sufficiency"
+    CAUSAL_EXHAUSTIVENESS = "causal_exhaustiveness"
+    INVARIANCE = "invariance"
+    THRESHOLD = "threshold"
+    PATH_DEPENDENCE = "path_dependence"
+
+
+class HypothesisOrigin(StrEnum):
+    HUMAN = "human"
+    AI = "ai"
+    MIXED = "mixed"
+
+
+class EvidenceRole(StrEnum):
+    DISCOVERY = "discovery"
+    CONFIRMATION = "confirmation"
+    QUALIFICATION = "qualification"
+
+
+class AttemptOutcome(StrEnum):
+    SUCCESS = "success"
+    INFRASTRUCTURE_FAILURE = "infrastructure_failure"
+    SPECIFICATION_FAILURE = "specification_failure"
+    NUMERICAL_FAILURE = "numerical_failure"
+    VALIDITY_FAILURE = "validity_failure"
+    INTERRUPTED = "interrupted"
+
+
+class ClaimDisposition(StrEnum):
+    SUPPORTED_WITHIN_MODEL = "supported_within_model"
+    REFUTED_WITHIN_MODEL = "refuted_within_model"
+    UNRESOLVED = "unresolved"
+
+
+class CampaignStatus(StrEnum):
+    ACTIVE = "active"
+    PAUSE_REQUESTED = "pause_requested"
+    QUIESCING = "quiescing"
+    PAUSED = "paused"
+    RESUMING = "resuming"
+    RECOVERING = "recovering"
+    EMERGENCY_STOPPED = "emergency_stopped"
+    HUMAN_REVIEW = "human_review"
+    COMPLETED = "completed"
+    TERMINATED = "terminated"
+
+
+class InterventionType(StrEnum):
+    PAUSE = "pause"
+    RESUME = "resume"
+    EMERGENCY_STOP = "emergency_stop"
+    ACTION_VETO = "action_veto"
+    PRIORITY_UPDATE = "priority_update"
+    TACTICAL_SUGGESTION = "tactical_suggestion"
+    REVIEWER_CHALLENGE = "reviewer_challenge"
+    EVIDENCE_INJECTION = "evidence_injection"
+    CONTRACT_AMENDMENT = "contract_amendment"
+    CAMPAIGN_BRANCH = "campaign_branch"
+
+
+class DomainSpec(StrictModel):
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    id: str = Field(default_factory=lambda: new_id("domain"))
+    description: str = Field(min_length=1)
+    model_family: str = Field(min_length=1)
+    assumptions: tuple[str, ...] = ()
+    fixed_parameters: dict[str, float | int | str] = Field(default_factory=dict)
+
+
+class ObservableSpec(StrictModel):
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    id: str = Field(default_factory=lambda: new_id("observable"))
+    name: str = Field(min_length=1)
+    semantic_kind: str = Field(min_length=1)
+    mathematical_definition: str = Field(min_length=1)
+    estimator: str = Field(min_length=1)
+    units: str = "dimensionless"
+    tolerance: float = Field(gt=0)
+
+
+class EvidenceContract(StrictModel):
+    primary_observable_id: str
+    falsifying_witness: str = Field(min_length=1)
+    primary_tolerance: float = Field(gt=0)
+    minimum_independent_confirmation_attempts: int = Field(default=1, ge=1)
+
+
+class MatchedPairFormalPredicate(StrictModel):
+    """Executable semantics for a finite predictive-sufficiency witness."""
+
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    predicate_type: Literal["matched_pair_predictive_sufficiency"] = (
+        "matched_pair_predictive_sufficiency"
+    )
+    matched_coordinates: tuple[str, ...] = Field(min_length=1)
+    outcome_observable_id: str = Field(min_length=1)
+    coordinate_tolerance: float = Field(default=1e-10, ge=0)
+    maximum_outcome_difference: float = Field(gt=0)
+
+
+class HypothesisNode(StrictModel):
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    id: str = Field(default_factory=lambda: new_id("hypothesis"))
+    statement: str = Field(min_length=1)
+    machine_predicate: str = Field(min_length=1)
+    formal_predicate: MatchedPairFormalPredicate | None = None
+    proposition_class: PropositionClass
+    domain: DomainSpec
+    coordinates: tuple[str, ...]
+    evidence_contract: EvidenceContract
+    origin: HypothesisOrigin
+    parent_ids: tuple[str, ...] = ()
+    motivating_evidence_ids: tuple[str, ...] = ()
+
+    @model_validator(mode="after")
+    def require_declarative_statement(self) -> HypothesisNode:
+        if self.statement.endswith("?"):
+            raise ValueError("a hypothesis must be declarative, not a research question")
+        if not self.coordinates:
+            raise ValueError("a hypothesis must declare its tested coordinates")
+        if self.formal_predicate is not None:
+            if self.proposition_class is not PropositionClass.PREDICTIVE_SUFFICIENCY:
+                raise ValueError(
+                    "the matched-pair predicate is only valid for predictive sufficiency"
+                )
+            if self.formal_predicate.matched_coordinates != self.coordinates:
+                raise ValueError("formal predicate coordinates must match hypothesis coordinates")
+            if (
+                self.formal_predicate.outcome_observable_id
+                != self.evidence_contract.primary_observable_id
+            ):
+                raise ValueError("formal predicate observable must match the evidence contract")
+            if (
+                abs(
+                    self.formal_predicate.maximum_outcome_difference
+                    - self.evidence_contract.primary_tolerance
+                )
+                > 1e-15
+            ):
+                raise ValueError("formal predicate tolerance must match the evidence contract")
+        return self
+
+
+class ExperimentSpec(StrictModel):
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    id: str = Field(default_factory=lambda: new_id("experiment"))
+    hypothesis_ids: tuple[str, ...]
+    action_type: str
+    physical_parameters: dict[str, float | int | str]
+    numerical_parameters: dict[str, float | int | str] = Field(default_factory=dict)
+    required_diagnostics: tuple[str, ...]
+    predictions: dict[str, str]
+    falsification_condition: str
+
+
+class AttemptRecord(StrictModel):
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    id: str = Field(default_factory=lambda: new_id("attempt"))
+    experiment_id: str
+    idempotency_key: str = Field(min_length=1)
+    outcome: AttemptOutcome | None = None
+    started_at: datetime = Field(default_factory=utc_now)
+    completed_at: datetime | None = None
+    external_job_id: str | None = None
+    failure_detail: str | None = None
+
+    @model_validator(mode="after")
+    def outcome_fields_are_consistent(self) -> AttemptRecord:
+        if self.outcome is None:
+            if self.completed_at or self.failure_detail:
+                raise ValueError("a pending attempt cannot be completed or failed")
+            return self
+        if self.completed_at is None:
+            raise ValueError("an attempt with an outcome requires completed_at")
+        failed = self.outcome is not AttemptOutcome.SUCCESS
+        if failed and not self.failure_detail:
+            raise ValueError("a non-successful attempt requires failure_detail")
+        if not failed and self.failure_detail:
+            raise ValueError("a successful attempt cannot carry failure_detail")
+        return self
+
+
+class RunEvidence(StrictModel):
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    id: str = Field(default_factory=lambda: new_id("evidence"))
+    source_attempt_id: str
+    role: EvidenceRole
+    eligible: bool
+    eligibility_reason: str
+    observable_values: dict[str, float]
+    uncertainties: dict[str, float] = Field(default_factory=dict)
+    independence_group: str
+    artifact_hashes: tuple[str, ...] = ()
+
+
+class Claim(StrictModel):
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    id: str = Field(default_factory=lambda: new_id("claim"))
+    hypothesis_id: str
+    statement: str
+    disposition: ClaimDisposition
+    scope: str
+    evidence_ids: tuple[str, ...] = Field(min_length=1)
+    limitations: tuple[str, ...] = ()
+    created_at: datetime = Field(default_factory=utc_now)
+
+
+class DecisionRecord(StrictModel):
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    id: str = Field(default_factory=lambda: new_id("decision"))
+    campaign_id: str
+    checkpoint_id: str
+    candidate_action_ids: tuple[str, ...]
+    selected_action_id: str
+    predicted_outcomes: dict[str, str]
+    validator_report: dict[str, Any]
+    model_id: str | None = None
+    model_route_reason: str | None = None
+    created_at: datetime = Field(default_factory=utc_now)
+
+
+class CampaignCheckpoint(StrictModel):
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    id: str = Field(default_factory=lambda: new_id("checkpoint"))
+    campaign_id: str
+    status: CampaignStatus
+    last_event_sequence: int = Field(ge=0)
+    state_hash: str
+    pending_action_ids: tuple[str, ...] = ()
+    external_job_ids: tuple[str, ...] = ()
+    budget_reserved: float = Field(default=0.0, ge=0)
+    component_versions: dict[str, str] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=utc_now)
+
+
+class HumanIntervention(StrictModel):
+    schema_version: Literal["0.1.0"] = "0.1.0"
+    id: str = Field(default_factory=lambda: new_id("intervention"))
+    actor: str
+    intervention_type: InterventionType
+    scope: str
+    reason: str
+    checkpoint_before: str
+    payload: dict[str, Any] = Field(default_factory=dict)
+    impact: dict[str, Any] = Field(default_factory=dict)
+    checkpoint_after: str | None = None
+    created_at: datetime = Field(default_factory=utc_now)