mixle.scientist module¶
Optional local scientific-assistant workflow.
Scientist assembles several Mixle surfaces into one offline-oriented object:
modality encoders for images and text, loaded from the local Hugging Face cache when available;
certified heads over encoder latents through
study;a substrate-backed
askworkflow using local evidence, skills, and an optional local language model;factuality and provenance checks for produced answers.
The module is intentionally optional. Heavy assets such as CLIP, MiniLM, and SmolLM2 are lazy-loaded and shared per process, and the package sets offline Hugging Face defaults at import time.
- encode_images(images, *, batch=32)[source]
CLIP ViT-B/32 image features,
(n, 512)– the real image leaf. Accepts PIL images/arrays.
- encode_texts(texts)[source]
MiniLM sentence embeddings
(n, 384)– the real text leaf.
- generate(prompt, *, max_new_tokens=96, temperature=0.0)[source]
One completion from the local LLM (SmolLM2-360M-Instruct) – the 99%-local answerer.
- class StudiedModel(head, classes, certificate, qhat, alpha, class_priors, train_seconds, provenance=<factory>)[source]
Bases:
objectA certified cross-modal predictor: encoder latents -> closed-form head, with its receipts.
- Parameters:
- head: Any
- certificate: Any
- qhat: float
- alpha: float
- class_priors: ndarray
- train_seconds: float
- prediction_sets(z)[source]
Conformal label sets at level 1-alpha: possibly >1 label (honest ambiguity), never empty lies.
- study(latents, labels, *, alpha=0.1, cal_frac=0.25, seed=0)[source]
Fit a CERTIFIED classifier over encoder latents: closed-form Gaussian class-conditionals + a split-conformal abstention rail. No gradient descent anywhere – the certificate proves it.
- class EdgeArtifact(model, bytes, torch_free, family, teacher_accuracy, student_accuracy, agreement, provenance=<factory>)[source]
Bases:
objectA capability compressed to run on a constrained device: the student + its footprint + retention.
- Parameters:
- model: Any
- bytes: int
- torch_free: bool
- family: str
- teacher_accuracy: float
- student_accuracy: float
- agreement: float
- property retention: float
The share of the teacher’s accuracy the edge student keeps – the compression’s honest cost.
- distill_to_edge(teacher_predict, train_inputs, val_inputs, val_truth, *, max_bytes=500_000, torch_free=True, n_init=3, n_iter=3, seed=0)[source]
Compress a foundation capability into a torch-free edge artifact, with a retention receipt.
teacher_predictis the capability (a raw_input -> label callable – e.g. CLIP zero-shot, or a MiniLM + certified head). Its labels ontrain_inputsare the distillation target; the student learns them from the RAW inputs under a device byte budget, so the deployed artifact needs neither torch nor the foundation model. The receipt measures what survives: student accuracy vs the teacher’s, and their agreement. Honest boundary: this works only when the student’s own features carry the signal (text n-grams do; raw pooled pixels do NOT recover a vision foundation model).
- class ResearchProposal(question, missing, nearest_knowledge=<factory>, options=<factory>, note='')[source]
Bases:
objectAn honest gap, made actionable: what is missing and the ranked ways to acquire it.
- Parameters:
- question: str
- missing: str
- note: str = ''
- class Conjecture(question, sources=<factory>, status='conjecture', proposal=None)[source]
Bases:
objectA curiosity-generated question: explicitly NOT knowledge – a hypothesis with a proposed test.
- question: str
- status: str = 'conjecture'
- proposal: ResearchProposal | None = None
- class Scientist(knowledge=None, *, max_entropy=0.9)[source]
Bases:
objectThe laptop cross-modal scientific reasoner (see module docstring).
- Parameters:
knowledge (Any) – a
Substrateof what it may cite (built if omitted).max_entropy (float) – the local LLM’s semantic-entropy gate – above it, the model may not answer from its own weights (it must ground in the substrate or abstain).
- learn(docs, *, source='user')[source]
Ingest documents into the citable knowledge (secrets redacted before indexing).
- add_action(action)[source]
Mount a capability (a physics solver, a simulator, a fitted skill) as a reasoner action.
- Parameters:
action (Any)
- Return type:
Scientist
- ask(question, *, min_confidence=0.2)[source]
Answer with citations or abstain. The local LLM composes ONLY from retrieved evidence, and its own uncertainty is measured: an answer it cannot ground or is not confident of is withheld.
- propose(question, investigation=None)[source]
Turn an abstention into a research plan: what is missing, and ranked ways to acquire it.
This is the difference between a dead end and a scientist: an honest “I don’t know” comes back with the acquisition options – add knowledge, run a mounted capability, fit a model to data, simulate, or delegate outward – each with what it would take and what it would settle. The ranking is EIG-per-cost over the mounted actions plus the generic acquisition strategies.
- investigate(question, **kw)[source]
ask, but an abstention comes back WITH its research proposal attached – never a bare no.
- wonder(topic=None, *, n=3, seed=0)[source]
Generate testable conjectures from what it knows – curiosity with receipts attached.
Pairs of knowledge items (optionally biased toward
topic) are handed to the local LLM with the instruction to propose a QUESTION or HYPOTHESIS connecting them. Every output is labeled a CONJECTURE and carries a proposed test (the research-proposal machinery), and is checked NOT to already be answerable from the substrate – curiosity about what it does not know, not rediscovery of what it does.
- static study(latents, labels, **kw)[source]
- static distill_to_edge(teacher_predict, train_inputs, val_inputs, val_truth, **kw)[source]
Compress a foundation capability into a torch-free edge artifact (see
distill_to_edge()).