reasoning.advisors

{
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty",
  "type": "object"
}

{
  "$defs": {
    "AdvisorCapacity": {
      "description": "One advisory capability and who can provide it now: a row of the capacity table\n`reasoning.advisors` reports. An empty `available` is answered by the local review.\n\n```\nuse majordomus_cli::capability::builtin::reasoning::AdvisorCapacity;\n\nlet row: AdvisorCapacity = serde_json::from_value(serde_json::json!({\n    \"capability\": \"code_review\", \"description\": \"Critique of a change.\", \"available\": [],\n})).unwrap();\nassert_eq!(row.capability, \"code_review\");\nassert!(row.available.is_empty());\n```",
      "properties": {
        "available": {
          "description": "Available advisors offering it, in preference order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "capability": {
          "description": "The capability word.",
          "type": "string"
        },
        "description": {
          "description": "What it means.",
          "type": "string"
        }
      },
      "required": [
        "capability",
        "description",
        "available"
      ],
      "type": "object"
    },
    "AdvisorCircuit": {
      "description": "An open circuit: the consultation that opened it, the failures behind it, and when it\ncloses. Derived from the records and the clock, never stored.\n\n```\nuse majordomus_cli::reasoning::availability::*;\nuse majordomus_cli::reasoning::catalogue::{AdvisorCatalogue, References};\nuse majordomus_cli::reasoning::record::ConsultationStatus;\n\nstruct All;\nimpl Presence for All {\n    fn executable(&self, _: &str) -> bool { true }\n    fn variable(&self, _: &str) -> bool { true }\n}\nlet c: AdvisorCatalogue = majordomus_cli::metadata::yaml::parse_into(\n    \"version: 1\\ncapabilities:\\n  - id: code_review\\n    description: x\\nadvisors:\\n  - id: a\\n    title: A\\n    transport: cli\\n    adapter: a-cli\\n    executable: a\\n    capabilities: [code_review]\\n\",\n).unwrap();\nlet limited = [Outcome {\n    id: \"consultation-1\".into(), advisor: \"a\".into(),\n    status: ConsultationStatus::RateLimited, at: 0, retry_after: Some(60),\n}];\nlet refs = References::default();\nlet states = derive_availability(&c, &Inputs {\n    refs: &refs, presence: &All, mode: ReasoningMode::Standard, disabled: &[],\n    history: &limited, peers: &[], now: 10, cooldown: None,\n});\nlet circuit: &AdvisorCircuit = states[0].circuit.as_ref().unwrap();\nassert_eq!(circuit.opened_by, \"consultation-1\");\nassert_eq!(circuit.until, \"1970-01-01T00:01:00Z\");\n```",
      "properties": {
        "failures": {
          "description": "The consecutive failures behind it.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "opened_by": {
          "description": "The consultation outcome that opened it.",
          "type": "string"
        },
        "until": {
          "description": "When it closes again, RFC 3339.",
          "type": "string"
        }
      },
      "required": [
        "opened_by",
        "failures",
        "until"
      ],
      "type": "object"
    },
    "AdvisorState": {
      "description": "One advisor as it stands now: what the catalogue declares of it, its status, the one\nmachine word saying why, and what was probed. The row `reasoning.advisors` reports and\nthe policy plans over.\n\n```\nuse majordomus_cli::reasoning::availability::*;\nuse majordomus_cli::reasoning::catalogue::{AdvisorCatalogue, References};\n\nstruct Nothing;\nimpl Presence for Nothing {\n    fn executable(&self, _: &str) -> bool { false }\n    fn variable(&self, _: &str) -> bool { false }\n}\nlet c: AdvisorCatalogue = majordomus_cli::metadata::yaml::parse_into(\n    \"version: 1\\ncapabilities:\\n  - id: code_review\\n    description: x\\nadvisors:\\n  - id: a\\n    title: A\\n    transport: local_runtime\\n    adapter: a-rt\\n    executable: rt\\n    capabilities: [code_review]\\n\",\n).unwrap();\nlet refs = References::default();\nlet state: AdvisorState = derive_availability(&c, &Inputs {\n    refs: &refs, presence: &Nothing, mode: ReasoningMode::Standard, disabled: &[],\n    history: &[], peers: &[], now: 0, cooldown: None,\n})\n.remove(0);\nassert_eq!((state.id.as_str(), state.status), (\"a\", AdvisorStatus::Unavailable));\nassert_eq!(state.probe, \"executable rt on PATH\");\nassert!(state.circuit.is_none() && !state.recovering);\n```",
      "properties": {
        "adapter": {
          "description": "The adapter that speaks to it.",
          "type": "string"
        },
        "capabilities": {
          "description": "The advisory capabilities it offers.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "circuit": {
          "anyOf": [
            {
              "$ref": "#/$defs/AdvisorCircuit"
            },
            {
              "type": "null"
            }
          ],
          "description": "The open circuit, when there is one."
        },
        "credential": {
          "description": "The name of the credential variable its adapter reads — a name, never a value.",
          "type": [
            "string",
            "null"
          ]
        },
        "executable": {
          "description": "The executable its adapter runs, when it runs one.",
          "type": [
            "string",
            "null"
          ]
        },
        "id": {
          "description": "The advisor id (a peer is `peer:<runtime>`).",
          "type": "string"
        },
        "model": {
          "description": "The model it asks, when the catalogue names one: what its adapter sends.",
          "type": [
            "string",
            "null"
          ]
        },
        "probe": {
          "description": "What was observed, for a person: which executable, which variable (never a value).",
          "type": "string"
        },
        "reason": {
          "description": "Why, as one machine word: `present`, `executable_not_found`, `credential_absent`,\n`mode_ci`, `mode_offline`, `disabled_by_configuration`, `consecutive_failures`,\n`rate_limited`, `authentication_failed`, `peer_linked`.",
          "type": "string"
        },
        "recovering": {
          "default": false,
          "description": "Available again after an open circuit's cooldown: the next consultation is its test.",
          "type": "boolean"
        },
        "status": {
          "$ref": "#/$defs/AdvisorStatus",
          "description": "Its standing."
        },
        "title": {
          "description": "The human name.",
          "type": "string"
        },
        "transport": {
          "$ref": "#/$defs/AdvisorTransport",
          "description": "How it is reached."
        }
      },
      "required": [
        "id",
        "title",
        "transport",
        "adapter",
        "capabilities",
        "status",
        "reason",
        "probe"
      ],
      "type": "object"
    },
    "AdvisorStatus": {
      "description": "An advisor's standing: whether it may be asked now and, when not, which kind of\nreason keeps it out. Only `available` advisors enter a plan.\n\n```\nuse majordomus_cli::reasoning::availability::AdvisorStatus;\n\nassert_eq!(serde_json::to_value(AdvisorStatus::NotConfigured).unwrap(), \"not_configured\");\nlet s: AdvisorStatus = serde_json::from_str(\"\\\"rate_limited\\\"\").unwrap();\nassert_eq!(s, AdvisorStatus::RateLimited);\n```",
      "oneOf": [
        {
          "const": "available",
          "description": "It may be asked. Presence was observed; whether it answers is learned by asking.",
          "type": "string"
        },
        {
          "const": "unavailable",
          "description": "Not installed: its executable is not on `PATH`.",
          "type": "string"
        },
        {
          "const": "not_configured",
          "description": "Installed or reachable in principle, but its credential is not configured.",
          "type": "string"
        },
        {
          "const": "disabled",
          "description": "Left out by the mode or by an explicit disable.",
          "type": "string"
        },
        {
          "const": "temporarily_failed",
          "description": "Its recent consultations failed; its circuit is open until the cooldown passes.",
          "type": "string"
        },
        {
          "const": "rate_limited",
          "description": "It answered with a rate limit; not asked again until the limit passes.",
          "type": "string"
        }
      ]
    },
    "AdvisorTransport": {
      "description": "How an advisor is reached. The transport decides how its presence is probed (a\ncredential variable, an executable, a mesh link) and whether `offline` mode admits it.\n\n```\nuse majordomus_cli::reasoning::catalogue::AdvisorTransport;\n\nlet t: AdvisorTransport = serde_json::from_str(\"\\\"local_runtime\\\"\").unwrap();\nassert_eq!(t, AdvisorTransport::LocalRuntime);\nassert!(!t.is_remote());\n```",
      "oneOf": [
        {
          "const": "api",
          "description": "A remote API; present when its vendor's credential variable is set.",
          "type": "string"
        },
        {
          "const": "cli",
          "description": "A client tool run as a process; present when its executable is on `PATH`.",
          "type": "string"
        },
        {
          "const": "local_runtime",
          "description": "A model runtime on this machine; present when its executable is on `PATH`.",
          "type": "string"
        },
        {
          "const": "peer",
          "description": "A linked mesh runtime carrying the review feature; present while linked.",
          "type": "string"
        }
      ]
    },
    "ModeResolution": {
      "description": "The mode in force and what decided it, as `resolve_mode` returns it. A plan and a\nreport carry the source beside the mode, so a reader learns why the mode is what it is.\n\n```\nuse majordomus_cli::reasoning::availability::{resolve_mode, ModeResolution, ReasoningMode};\n\nlet r: ModeResolution = resolve_mode(None, true, None);\nassert_eq!(r, ModeResolution { mode: ReasoningMode::Ci, source: \"CI\".into() });\n```",
      "properties": {
        "mode": {
          "$ref": "#/$defs/ReasoningMode",
          "description": "The mode."
        },
        "source": {
          "description": "What decided it: `MAJORDOMUS_REASONING_MODE`, `CI`, `profile <name>`, or `default`.",
          "type": "string"
        }
      },
      "required": [
        "mode",
        "source"
      ],
      "type": "object"
    },
    "ReasoningMode": {
      "description": "How much independent review a session may use, and where from. The policy reads it\nfor the review budget; availability reads it to leave advisors out (`ci` all of them,\n`offline` every one that leaves the machine). `standard` is the default.\n\n```\nuse majordomus_cli::reasoning::availability::ReasoningMode;\n\nassert_eq!(ReasoningMode::default(), ReasoningMode::Standard);\nassert_eq!(serde_json::to_value(ReasoningMode::Offline).unwrap(), \"offline\");\nlet m: ReasoningMode = serde_json::from_str(\"\\\"strict\\\"\").unwrap();\nassert_eq!(m, ReasoningMode::Strict);\n```",
      "oneOf": [
        {
          "const": "offline",
          "description": "No network: only advisors that stay on this machine.",
          "type": "string"
        },
        {
          "const": "ci",
          "description": "Deterministic: no advisor at all, whatever is installed.",
          "type": "string"
        },
        {
          "const": "fast",
          "description": "Review only where the blast radius is high.",
          "type": "string"
        },
        {
          "const": "standard",
          "description": "Review where uncertainty is material.",
          "type": "string"
        },
        {
          "const": "strict",
          "description": "Review wider, and complementary review where the stakes are highest.",
          "type": "string"
        }
      ]
    }
  },
  "description": "The answer of `reasoning.advisors`: the mode in force, how many advisors may and may\nnot be asked, every advisor's state, the capacity per advisory capability, and the\ncatalogue's own findings. `operational` is `true` whatever the counts.\n\n```\nuse majordomus_cli::capability::builtin::reasoning::AdvisorsReport;\n\nlet report: AdvisorsReport = serde_json::from_value(serde_json::json!({\n    \"operational\": true,\n    \"mode\": { \"mode\": \"ci\", \"source\": \"CI\" },\n    \"available\": 0, \"unavailable\": 0, \"advisors\": [], \"capacity\": [],\n})).unwrap();\nassert!(report.operational && report.advisors.is_empty());\nassert_eq!(report.mode.source, \"CI\");\nassert!(report.diagnostics.is_empty(), \"absent findings are the ordinary case\");\n```",
  "properties": {
    "advisors": {
      "description": "Every advisor, declared ones in preference order, then linked peers.",
      "items": {
        "$ref": "#/$defs/AdvisorState"
      },
      "type": "array"
    },
    "available": {
      "description": "Advisors that may be asked now.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "capacity": {
      "description": "Per advisory capability, who can provide it now. A row with nobody is answered by\nthe local review path.",
      "items": {
        "$ref": "#/$defs/AdvisorCapacity"
      },
      "type": "array"
    },
    "diagnostics": {
      "description": "The catalogue's own findings.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "mode": {
      "$ref": "#/$defs/ModeResolution",
      "description": "The mode in force and what decided it."
    },
    "operational": {
      "description": "Reasoning works whatever the advisors: always `true`, stated so a reader need not\ninfer it from a count.",
      "type": "boolean"
    },
    "unavailable": {
      "description": "Advisors that may not, each optional.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operational",
    "mode",
    "available",
    "unavailable",
    "advisors",
    "capacity"
  ],
  "title": "AdvisorsReport",
  "type": "object"
}