apsimo 1.3.0__py3-none-any.whl

apsimo/proposals/__init__.py

@@ -0,0 +1,12 @@
+"""Proposals: well-formed findings/suggestions delivered to the owner via the
+guarded (shadow-gated, boundary-checked, rate-limited) reach-out path."""
+
+from apsimo.proposals.models import Proposal, ProposalStore
+from apsimo.proposals.engine import (
+    build_from_thinker, build_from_research, proposal_to_payload,
+)
+
+__all__ = [
+    "Proposal", "ProposalStore",
+    "build_from_thinker", "build_from_research", "proposal_to_payload",
+]

apsimo/proposals/engine.py

@@ -0,0 +1,114 @@
+"""Turn self-directed thoughts and research findings into Proposals."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from apsimo.proposals.models import Proposal
+
+_THINK_PREFIX = re.compile(r"^\[self-directed thinking\]\s*", re.IGNORECASE)
+
+# Ungrounded rationale text: empty, or a generic "worth doing" placeholder
+# that carries no evidence of WHY the work helps. Proposals whose only
+# justification is one of these do not ship (honest why_it_helps: item 4).
+_UNGROUNDED = re.compile(
+    r"^(i think this work is worth doing( now)?\.?"
+    r"|worth doing( now)?\.?"
+    r"|advances your priorities\.?"
+    r"|moves a piece of your work forward\.?)$",
+    re.IGNORECASE,
+)
+
+
+def _first_sentence(text: str, limit: int = 200) -> str:
+    text = (text or "").strip()
+    if not text:
+        return ""
+    m = re.search(r"[.!?](\s|$)", text)
+    sentence = text[: m.end()].strip() if m else text
+    return sentence[:limit].strip()
+
+
+def build_from_thinker(initiative: Any) -> Optional[Proposal]:
+    """Package one self-directed-thinking initiative as a Proposal.
+
+    Returns None (does NOT ship) when the initiative carries no grounded
+    reason: ``why_it_helps`` must come from the initiative's own evidence
+    (its rationale), never a per-type template. A thought whose rationale is
+    empty or a generic "worth doing" placeholder is not deliverable.
+    """
+    title = (getattr(initiative, "description", "") or "").strip()
+    itype = getattr(initiative, "type", None)
+    itype = getattr(itype, "value", None) or str(itype or "research")
+    rationale = _THINK_PREFIX.sub("", getattr(initiative, "rationale", "") or "").strip()
+
+    # Grounding gate: a real, evidence-bearing rationale is required.
+    if not rationale or _UNGROUNDED.match(rationale):
+        return None
+
+    try:
+        conf = float(getattr(initiative, "priority", 0.6) or 0.6)
+    except (TypeError, ValueError):
+        conf = 0.6
+    return Proposal(
+        title=title[:100] or "(proposal)",
+        finding=rationale,
+        # Grounded in the initiative's own evidence, not a template.
+        why_it_helps=_first_sentence(rationale),
+        suggested_action=title,
+        citations=[],
+        source="thinker",
+        initiative_type=itype,
+        confidence=conf,
+    )
+
+
+def build_from_research(goal: str, artifact_text: str, sources: list,
+                        confidence: float = 0.7) -> Optional[Proposal]:
+    """Package a research finding (with citations) as a Proposal.
+
+    Returns None (does NOT ship) without grounded evidence: a research
+    proposal needs an actual finding AND the question that motivated it (its
+    grounded ``why_it_helps``). An empty finding or a missing goal means there
+    is nothing honest to say about why it helps.
+    """
+    finding = (artifact_text or "").strip()
+    goal = (goal or "").strip()
+    if not finding or not goal:
+        return None
+    cites = []
+    for s in (sources or [])[:6]:
+        if isinstance(s, dict):
+            cites.append({"title": s.get("title", ""), "url": s.get("url", "")})
+        else:
+            cites.append({"title": str(getattr(s, "title", "") or ""),
+                          "url": str(getattr(s, "url", "") or "")})
+    return Proposal(
+        title=goal[:100],
+        finding=finding[:1200],
+        # Grounded in the actual question that prompted the research.
+        why_it_helps=f"answers a question you're working on: {goal}"[:200],
+        suggested_action="Review the finding and tell me if you want me to go deeper.",
+        citations=cites, source="research", initiative_type="research",
+        confidence=confidence,
+    )
+
+
+def proposal_to_payload(p: Proposal) -> Dict[str, Any]:
+    """Delivery payload for a Proposal (dedicated 'proposal' type)."""
+    return {
+        "id": p.id,
+        "type": "proposal",
+        "priority": p.confidence,
+        "title": p.title[:80],
+        "description": p.render(),
+        "rationale": p.finding,
+        "suggested_action": p.suggested_action,
+        "entity_id": None,          # proposals target the owner
+        "entity_type": "proposal",
+        "channel_hint": "dm",
+        "context": {},
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+    }

apsimo/proposals/models.py

@@ -0,0 +1,207 @@
+"""Proposal artifact + store.
+
+A Proposal is a well-formed thing Colony wants to put in front of the owner:
+a finding (what it noticed / learned), why it helps him, a concrete suggested
+action, and citations. It is a DEDICATED type, distinct from routine reach-out
+initiatives, delivered through the same guarded (shadow-gated, boundary-checked,
+rate-limited) path.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Proposal:
+    title: str
+    finding: str = ""                 # what Colony noticed / learned
+    why_it_helps: str = ""            # relevance to the owner
+    suggested_action: str = ""        # concrete next step
+    citations: List[Dict[str, str]] = field(default_factory=list)  # [{title,url}]
+    source: str = "thinker"           # thinker | research | <initiative_id>
+    initiative_type: str = "research"
+    confidence: float = 0.6
+    status: str = "shadow"            # shadow | delivered | dismissed | draft
+    id: str = field(default_factory=lambda: f"prop-{uuid.uuid4().hex[:12]}")
+    created_at: float = field(default_factory=time.time)
+    route_ref: str = ""
+    result_ref: str = ""
+    subject_person_id: str = ""
+    viewer_scope: str = "owner"
+    shareability: str = "owner_private"
+    scope_digest: str = ""
+
+    def render(self) -> str:
+        """Owner-facing text handed to the composing agent."""
+        lines = [self.title.strip()]
+        finding = self.finding.strip()
+        why = self.why_it_helps.strip()
+        if finding:
+            lines.append(f"What I found: {finding}")
+        # Skip the why-line when it merely restates the finding (the grounded
+        # why is often the finding's lead sentence) — no honest information is
+        # lost and the message stays tight.
+        if why and not (finding and finding.startswith(why)):
+            lines.append(f"Why it helps you: {why}")
+        if self.suggested_action:
+            lines.append(f"Suggested next step: {self.suggested_action.strip()}")
+        if self.citations:
+            cites = "; ".join(
+                (c.get("title") or c.get("url") or "").strip()
+                for c in self.citations if (c.get("title") or c.get("url"))
+            )
+            if cites:
+                lines.append(f"Sources: {cites}")
+        return "\n".join(lines)
+
+    def to_row(self) -> Dict[str, Any]:
+        return {
+            "id": self.id, "title": self.title, "finding": self.finding,
+            "why_it_helps": self.why_it_helps, "suggested_action": self.suggested_action,
+            "citations": json.dumps(self.citations), "source": self.source,
+            "initiative_type": self.initiative_type, "confidence": self.confidence,
+            "status": self.status, "created_at": self.created_at,
+            "route_ref": self.route_ref, "result_ref": self.result_ref,
+            "subject_person_id": self.subject_person_id,
+            "viewer_scope": self.viewer_scope,
+            "shareability": self.shareability,
+            "scope_digest": self.scope_digest,
+        }
+
+    def visible_to(
+        self,
+        *,
+        viewer_person_id: str,
+        owner_person_id: str,
+        audiences: set[str] | frozenset[str] = frozenset(),
+    ) -> bool:
+        viewer = str(viewer_person_id or "").strip()
+        if not viewer:
+            return False
+        if viewer == str(owner_person_id or "").strip():
+            return True
+        if self.shareability == "public":
+            return "global" in audiences
+        if self.shareability == "shared":
+            return "shared" in audiences
+        if self.shareability == "subject_private":
+            return viewer == self.subject_person_id
+        return False
+
+    @classmethod
+    def from_row(cls, r: Dict[str, Any]) -> "Proposal":
+        try:
+            cites = json.loads(r.get("citations") or "[]")
+        except Exception:
+            cites = []
+        return cls(
+            id=r["id"], title=r["title"], finding=r.get("finding", "") or "",
+            why_it_helps=r.get("why_it_helps", "") or "",
+            suggested_action=r.get("suggested_action", "") or "",
+            citations=cites, source=r.get("source", "thinker") or "thinker",
+            initiative_type=r.get("initiative_type", "research") or "research",
+            confidence=float(r.get("confidence", 0.6) or 0.6),
+            status=r.get("status", "shadow") or "shadow",
+            created_at=float(r.get("created_at") or time.time()),
+            route_ref=r.get("route_ref", "") or "",
+            result_ref=r.get("result_ref", "") or "",
+            subject_person_id=r.get("subject_person_id", "") or "",
+            viewer_scope=r.get("viewer_scope", "owner") or "owner",
+            shareability=r.get("shareability", "owner_private") or "owner_private",
+            scope_digest=r.get("scope_digest", "") or "",
+        )
+
+
+class ProposalStore:
+    def __init__(self, db_path: Optional[str] = None) -> None:
+        self._lock = threading.RLock()
+        self._conn = sqlite3.connect(str(db_path) if db_path else ":memory:",
+                                     check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        with self._lock:
+            self._conn.execute(
+                """CREATE TABLE IF NOT EXISTS proposals (
+                    id TEXT PRIMARY KEY, title TEXT NOT NULL, finding TEXT,
+                    why_it_helps TEXT, suggested_action TEXT, citations TEXT,
+                    source TEXT, initiative_type TEXT, confidence REAL,
+                    status TEXT, created_at REAL, route_ref TEXT,
+                    result_ref TEXT, subject_person_id TEXT,
+                    viewer_scope TEXT DEFAULT 'owner',
+                    shareability TEXT DEFAULT 'owner_private', scope_digest TEXT
+                )""")
+            columns = {
+                row[1] for row in self._conn.execute(
+                    "PRAGMA table_info(proposals)"
+                ).fetchall()
+            }
+            for name, declaration in (
+                ("route_ref", "TEXT"),
+                ("result_ref", "TEXT"),
+                ("subject_person_id", "TEXT"),
+                ("viewer_scope", "TEXT DEFAULT 'owner'"),
+                ("shareability", "TEXT DEFAULT 'owner_private'"),
+                ("scope_digest", "TEXT"),
+            ):
+                if name not in columns:
+                    self._conn.execute(
+                        f"ALTER TABLE proposals ADD COLUMN {name} {declaration}"
+                    )
+            self._conn.commit()
+
+    def add(self, p: Proposal) -> Proposal:
+        row = p.to_row()
+        with self._lock:
+            cols = ", ".join(row); ph = ", ".join(["?"] * len(row))
+            self._conn.execute(
+                f"INSERT OR REPLACE INTO proposals ({cols}) VALUES ({ph})",
+                list(row.values()))
+            self._conn.commit()
+        return p
+
+    def add_if_absent(self, p: Proposal) -> bool:
+        """Insert a stable proposal without overwriting operator state."""
+
+        row = p.to_row()
+        with self._lock:
+            cols = ", ".join(row)
+            ph = ", ".join(["?"] * len(row))
+            cursor = self._conn.execute(
+                f"INSERT OR IGNORE INTO proposals ({cols}) VALUES ({ph})",
+                list(row.values()),
+            )
+            self._conn.commit()
+            return cursor.rowcount == 1
+
+    def list(self, status: Optional[str] = None, limit: int = 50) -> List[Proposal]:
+        q = "SELECT * FROM proposals"
+        params: List[Any] = []
+        if status:
+            q += " WHERE status=?"; params.append(status)
+        q += " ORDER BY created_at DESC LIMIT ?"; params.append(limit)
+        with self._lock:
+            rows = self._conn.execute(q, params).fetchall()
+        return [Proposal.from_row(dict(r)) for r in rows]
+
+    def get(self, proposal_id: str) -> Optional[Proposal]:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT * FROM proposals WHERE id=?", (proposal_id,),
+            ).fetchone()
+        return Proposal.from_row(dict(row)) if row is not None else None
+
+    def set_status(self, proposal_id: str, status: str) -> bool:
+        with self._lock:
+            cur = self._conn.execute(
+                "UPDATE proposals SET status=? WHERE id=?", (status, proposal_id))
+            self._conn.commit()
+            return cur.rowcount > 0
+
+    def count(self, status: Optional[str] = None) -> int:
+        return len(self.list(status=status, limit=100000))

apsimo/qualification/__init__.py

@@ -0,0 +1 @@
+"""Opt-in, finite qualification through existing model consumers."""

apsimo/qualification/cases.py

@@ -0,0 +1,75 @@
+"""Small neutral cases. A role completion is not native agent qualification."""
+import json
+
+from .records import CaseSpec
+
+
+async def role_completion(inputs, context):
+    response = await context.router.complete(inputs['messages'], context={
+        'function_role': inputs['role'], 'allow_fallback': False,
+        'max_output_tokens': inputs.get('max_output_tokens', 512)})
+    return {'output': response.content, 'effects': {}}
+
+
+def json_fields(observed, oracle):
+    """Exact independently specified fields, not a model judging itself."""
+    output = observed.get('output')
+    if isinstance(output, str):
+        try:
+            output = json.loads(output)
+        except (ValueError, TypeError):
+            return {'output_is_json': False}
+    root = {**observed, 'output': output}
+    checks = {}
+    for item in oracle['fields']:
+        current = root
+        try:
+            for part in item['path']:
+                current = current[part]
+        except (KeyError, IndexError, TypeError):
+            checks[item['name']] = False
+        else:
+            checks[item['name']] = type(current) is type(item['equals']) and current == item['equals']
+    return checks
+
+
+STANDARD = [
+    CaseSpec(id='chat.grounded-note', version='1', role='chat', boundary='role_completion',
+        consumer='role_completion', evaluator='json_fields',
+        inputs={'role': 'chat', 'messages': [
+            {'role': 'system', 'content': 'Answer from the supplied note only. Return a JSON object; use null for information absent from the note.'},
+            {'role': 'user', 'content': 'Note: The blue sample case is in drawer 4. The silver case was moved, but its new location is unknown. Where is each case? Use keys blue and silver.'}]},
+        oracle={'fields': [
+            {'name': 'known_location', 'path': ['output', 'blue'], 'equals': 'drawer 4'},
+            {'name': 'unknown_preserved', 'path': ['output', 'silver'], 'equals': None}]}),
+    CaseSpec(id='extraction.conditions', version='1', role='extraction', boundary='role_completion',
+        consumer='role_completion', evaluator='json_fields',
+        inputs={'role': 'extraction', 'messages': [
+            {'role': 'system', 'content': 'Extract only explicit information. Return JSON with keys item, location, valid_day, requires_wet_shelf (boolean), owner. Use null for absent information.'},
+            {'role': 'user', 'content': 'For tomorrow only, put the blue sample case in drawer 4 if the shelf is wet. Nobody has identified its owner.'}]},
+        oracle={'fields': [
+            {'name': 'item', 'path': ['output', 'item'], 'equals': 'blue sample case'},
+            {'name': 'location', 'path': ['output', 'location'], 'equals': 'drawer 4'},
+            {'name': 'time_condition', 'path': ['output', 'valid_day'], 'equals': 'tomorrow'},
+            {'name': 'wet_shelf_condition', 'path': ['output', 'requires_wet_shelf'], 'equals': True},
+            {'name': 'unknown_owner', 'path': ['output', 'owner'], 'equals': None}]}),
+]
+
+CONSUMERS = {'role_completion': role_completion}
+EVALUATORS = {'json_fields': json_fields}
+
+from .memory_cases import CASES as MEMORY_CASES, CONSUMERS as MEMORY_CONSUMERS, EVALUATORS as MEMORY_EVALUATORS
+STANDARD.extend(MEMORY_CASES)
+CONSUMERS.update(MEMORY_CONSUMERS)
+EVALUATORS.update(MEMORY_EVALUATORS)
+
+from .structured_cases import CASES as STRUCTURED_CASES
+STANDARD.extend(STRUCTURED_CASES)
+
+
+def select_cases(roles):
+    cases = [case for case in STANDARD if case.role in roles]
+    uncovered = set(roles) - {case.role for case in cases}
+    if uncovered:
+        raise ValueError('No installed standard cases for roles: ' + ', '.join(sorted(uncovered)))
+    return cases

apsimo/qualification/cli.py

@@ -0,0 +1,51 @@
+"""Opt-in CLI. Inspect/compare are offline; evaluate invokes selected consumers."""
+import asyncio
+import json
+from pathlib import Path
+
+
+def add_parser(sub):
+    parser = sub.add_parser('models', help='Inspect and qualify model bindings without selecting a deployment')
+    commands = parser.add_subparsers(dest='models_command', required=True)
+    for command in ('inspect', 'evaluate'):
+        item = commands.add_parser(command)
+        item.add_argument('binding', help='Existing modelPool or named tier binding')
+        item.add_argument('--config', required=True, type=Path, help='Existing private host model configuration JSON')
+        if command == 'evaluate':
+            item.add_argument('--roles', default='chat,extraction')
+            item.add_argument('--suite', choices=['standard'], default='standard')
+            item.add_argument('--evidence-mode', choices=['actual_inference', 'controlled'], default='actual_inference',
+                              help='Label controlled fixtures separately; neither label attests serving weights')
+            item.add_argument('--output', required=True, type=Path, help='New private result directory')
+            item.add_argument('--resume', action='store_true', help='Continue untouched cases; interrupted attempts are never rerun')
+    item = commands.add_parser('compare')
+    item.add_argument('incumbent', type=Path)
+    item.add_argument('candidate', type=Path)
+    item.add_argument('--json', action='store_true')
+
+
+def run(args):
+    from .records import read, write_once, publish
+    from .report import compare, summarize, markdown
+    if args.models_command == 'compare':
+        report = compare(args.incumbent, args.candidate)
+        print(json.dumps(report, indent=2) if args.json else markdown(report))
+        return 0
+    from .runner import inspect_binding, router_for, evaluate
+    config = read(args.config)
+    recipe = inspect_binding(config, args.binding)
+    if args.models_command == 'inspect':
+        print(json.dumps(recipe, indent=2))
+        return 0
+    from .cases import select_cases, CONSUMERS, EVALUATORS
+    cases = select_cases([r.strip() for r in args.roles.split(',') if r.strip()])
+    asyncio.run(evaluate(args.output, recipe, cases, CONSUMERS, EVALUATORS,
+        lambda case: router_for(config, args.binding, [case]), resume=args.resume, evidence_mode=args.evidence_mode))
+    report = summarize(args.output)
+    # Reports are new immutable views. Earlier reports remain useful when a run resumes.
+    index = len(list(args.output.glob('report-*.json'))) + 1
+    write_once(args.output / f'report-{index:03d}.json', report)
+    text = markdown(report)
+    publish(args.output / f'report-{index:03d}.md', text.encode())
+    print(text)
+    return 0 if all(row['outcome'] == 'pass' for row in report['cases']) else 1