experienceos 0.7.2__py3-none-any.whl

experienceos/__init__.py

@@ -0,0 +1,36 @@
+"""ExperienceOS - an open-source personal experience operating system.
+
+> Never forget what you have built.
+
+ExperienceOS helps developers record, organize, understand and preserve
+every project and creative experience they have taken part in. It turns
+fragmented traces (code, repositories, GitHub activity, resumes, and
+conversations) into structured, evidence-backed Experience Assets.
+"""
+
+from experienceos.core.models import (
+    SCHEMA_VERSION,
+    Evidence,
+    EvidenceKind,
+    Experience,
+    ExperienceType,
+    Period,
+    Source,
+    SourceOrigin,
+    Status,
+)
+
+__version__ = "0.7.2"
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "Evidence",
+    "EvidenceKind",
+    "Experience",
+    "ExperienceType",
+    "Period",
+    "Source",
+    "SourceOrigin",
+    "Status",
+    "__version__",
+]

experienceos/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m experienceos``."""
+
+from experienceos.cli.app import main
+
+if __name__ == "__main__":
+    main()

experienceos/ai/__init__.py

@@ -0,0 +1,52 @@
+"""AI layer: providers, tools, structured outputs, and durable workflows.
+
+M0 shipped the contracts; #010 wired OpenAI-compatible endpoints; the
+checkpointed evidence-brief workflow, its read-only tool registry, the
+evaluation harness, and the provider factory make the layer a testable
+system — "AI propose, human decide" throughout.
+"""
+
+from experienceos.ai.factory import create_provider
+from experienceos.ai.mock import MockProvider
+from experienceos.ai.prompts import (
+    ALL_PROMPTS,
+    EXTRACTION_PROMPT_V1,
+    INTAKE_INTERVIEW_PROMPT_V1,
+    render_prompt,
+)
+from experienceos.ai.provider import (
+    LLMProvider,
+    Message,
+    ModelResponse,
+    OpenAICompatibleProvider,
+    RecordedProvider,
+    ToolCall,
+    complete_structured,
+)
+from experienceos.ai.responses import OpenAIResponsesProvider
+from experienceos.ai.schemas import BriefCitation, EvidenceBrief, ProviderHealth
+from experienceos.ai.tools import ExperienceToolRegistry
+from experienceos.ai.workflow import EvidenceBriefWorkflow, WorkflowCheckpointStore
+
+__all__ = [
+    "ALL_PROMPTS",
+    "EXTRACTION_PROMPT_V1",
+    "INTAKE_INTERVIEW_PROMPT_V1",
+    "BriefCitation",
+    "EvidenceBrief",
+    "EvidenceBriefWorkflow",
+    "ExperienceToolRegistry",
+    "LLMProvider",
+    "Message",
+    "MockProvider",
+    "ModelResponse",
+    "OpenAICompatibleProvider",
+    "OpenAIResponsesProvider",
+    "ProviderHealth",
+    "RecordedProvider",
+    "ToolCall",
+    "WorkflowCheckpointStore",
+    "complete_structured",
+    "create_provider",
+    "render_prompt",
+]

experienceos/ai/demo.py

@@ -0,0 +1,60 @@
+# ruff: noqa: RUF001
+"""Recorded model turns for the offline demo.
+
+The model responses are deterministic, but all three tool calls, argument
+validation, store reads, checkpoints, grounding checks, and structured-output
+validation run through the same production path as a live model.
+"""
+
+from __future__ import annotations
+
+from experienceos.ai.provider import ModelResponse, RecordedProvider, ToolCall
+from experienceos.ai.schemas import BriefCitation, EvidenceBrief
+from experienceos.core.errors import WorkflowError
+from experienceos.storage import ExperienceStore
+
+
+def build_recorded_demo_provider(store: ExperienceStore) -> RecordedProvider:
+    experiences = store.list_all()
+    if not experiences:
+        raise WorkflowError("离线演示至少需要一条经历，请先新增或导入经历")
+    experience = experiences[0]
+    locations = [evidence.location for evidence in experience.evidence]
+    gap = (
+        []
+        if locations
+        else [f"{experience.title} 尚未关联证据，请补充仓库、提交、PR 或文档。"]
+    )
+    output = EvidenceBrief(
+        answer=f"本地经历库中最近录入的项目是“{experience.title}”。",
+        highlights=[
+            experience.description or f"已记录项目“{experience.title}”。",
+            *experience.result[:2],
+        ],
+        citations=[
+            BriefCitation(
+                experience_id=experience.id,
+                claim=f"本地经历库包含项目“{experience.title}”。",
+                evidence_locations=locations,
+            )
+        ],
+        evidence_gaps=gap,
+        next_actions=["核对引用记录，并为尚无证据支撑的成果补充材料。"],
+    )
+    return RecordedProvider(
+        responses=[
+            ModelResponse(
+                tool_calls=(
+                    ToolCall("demo_search", "search_experiences", {"query": "", "limit": 5}),
+                    ToolCall(
+                        "demo_get",
+                        "get_experience",
+                        {"id_or_prefix": experience.id},
+                    ),
+                    ToolCall("demo_stats", "get_evidence_stats", {}),
+                )
+            ),
+            ModelResponse(content=output.model_dump_json()),
+        ],
+        name="recorded-demo",
+    )

experienceos/ai/enrich.py

@@ -0,0 +1,137 @@
+"""Enrich pipeline (#012): AI proposals for one existing record.
+
+The model returns a proposal list; this module is the *server-side
+gatekeeper*: proposals targeting anything outside
+{contribution, challenge, solution, result, technology} are dropped
+outright — title, period, evidence and factual numbers can never be
+touched through enrich, no matter what the model says. Accepted
+proposals mutate the record in memory; the CLI's confirmation loop and
+``ExperienceStore.save`` (which bumps ``updated_at``) do the rest.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from experienceos.ai.prompts import ENRICH_PROMPT_V1
+from experienceos.ai.provider import Message
+from experienceos.core.models import Experience
+
+ALLOWED_FIELDS = ("contribution", "challenge", "solution", "result", "technology")
+_FENCE_RE = re.compile(r"```(?:json)?\s*(.*?)\s*```", re.DOTALL)
+
+
+@dataclass(frozen=True)
+class EnrichProposal:
+    """One in-scope, normalized proposal ready for confirmation."""
+
+    field: str
+    current: str
+    suggested_items: tuple[str, ...]
+    reason: str
+
+    @property
+    def suggested_display(self) -> str:
+        return " | ".join(self.suggested_items)
+
+
+def build_enrich_messages(experience: Experience) -> list[Message]:
+    """System enrich prompt + the record JSON as material."""
+    material = json.dumps(experience.to_dict(), ensure_ascii=False, indent=2)
+    return [
+        Message(role="system", content=ENRICH_PROMPT_V1),
+        Message(
+            role="user",
+            content=f"Record:\n\n{material}\n\nOutput ONLY the JSON array.",
+        ),
+    ]
+
+
+def parse_proposals(raw: str) -> list[dict[str, Any]]:
+    """Parse the model reply into a list of proposal dicts."""
+    text = raw.strip()
+    fence = _FENCE_RE.search(text)
+    if fence:
+        text = fence.group(1)
+    else:
+        start, end = text.find("["), text.rfind("]")
+        if start != -1 and end > start:
+            text = text[start : end + 1]
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"enrich output is not valid JSON: {exc}") from exc
+    if isinstance(data, dict):
+        if "proposals" not in data:
+            raise ValueError("enrich output is not a JSON array")
+        data = data["proposals"]
+    if not isinstance(data, list):
+        raise ValueError("enrich output is not a JSON array")
+    return [item for item in data if isinstance(item, dict)]
+
+
+def normalize_proposals(
+    data: list[dict[str, Any]],
+) -> tuple[list[EnrichProposal], list[str]]:
+    """Split raw proposals into (in-scope, rejected descriptions).
+
+    A proposal is rejected when its field is outside the whitelist or
+    its payload is malformed — the record itself is the source of truth,
+    so anything questionable is dropped, never guessed.
+    """
+    accepted: list[EnrichProposal] = []
+    rejected: list[str] = []
+    for item in data:
+        field = item.get("field")
+        if field not in ALLOWED_FIELDS:
+            rejected.append(
+                f"out-of-scope field {field!r} (allowed: {', '.join(ALLOWED_FIELDS)})"
+            )
+            continue
+        suggested = item.get("suggested")
+        if isinstance(suggested, str):
+            suggested_items = (suggested.strip(),) if suggested.strip() else ()
+        elif isinstance(suggested, list):
+            suggested_items = tuple(
+                name.strip() for name in suggested if isinstance(name, str) and name.strip()
+            )
+        else:
+            suggested_items = ()
+        if not suggested_items:
+            rejected.append("malformed proposal (suggested missing or empty)")
+            continue
+        current = item.get("current")
+        has_current = isinstance(current, str) and bool(current.strip())
+        if field != "technology" and not has_current:
+            # STAR rewrites replace an existing item, so the model must
+            # name it; technology replaces the whole list instead
+            rejected.append("malformed proposal (current missing)")
+            continue
+        accepted.append(
+            EnrichProposal(
+                field=field,
+                current=current.strip() if has_current else "",
+                suggested_items=suggested_items,
+                reason=str(item.get("reason", "")).strip(),
+            )
+        )
+    return accepted, rejected
+
+
+def apply_proposal(experience: Experience, proposal: EnrichProposal) -> None:
+    """Mutate *experience* in place; pydantic validates the assignment."""
+    if proposal.field == "technology":
+        experience.technology = list(proposal.suggested_items)
+        return
+    items = list(getattr(experience, proposal.field))
+    for index, item in enumerate(items):
+        if item.casefold() == proposal.current.casefold():
+            items[index] = proposal.suggested_items[0]
+            break
+    else:
+        # the model paraphrased the current item; append instead of guessing
+        items.append(proposal.suggested_items[0])
+    setattr(experience, proposal.field, items)

experienceos/ai/eval_cases.jsonl

@@ -0,0 +1,9 @@
+{"id": "search_with_evidence", "question": "找出检索项目，概括技术亮点和可验证结果。", "experiences": [{"id": "exp_01ARZ3NDEKTSV4RRFFQ69G5FAV", "title": "Campus Search Engine", "type": "course_project", "period": {"start": "2024-01", "end": "2024-06"}, "description": "Built a Chinese document search engine with BM25 ranking.", "technology": ["Python", "BM25"], "result": ["Top-10 hit rate reached 92% on a 200-query set."], "evidence": [{"kind": "repo", "location": "github.com/example/campus-search"}]}], "expected_tool_sequence": ["search_experiences", "get_experience", "get_evidence_stats"], "expected_terms": ["BM25", "92%"], "label_source": "ai-assisted-synthetic", "expected_behavior_notes": "Search, load the full record, then inspect evidence coverage before citing the stored metric.", "recorded_turns": [{"tool_calls": [{"id": "s1", "name": "search_experiences", "arguments": {"query": "search", "limit": 5}}, {"id": "g1", "name": "get_experience", "arguments": {"id_or_prefix": "exp_01ARZ3NDEKTSV4RRFFQ69G5FAV"}}, {"id": "e1", "name": "get_evidence_stats", "arguments": {}}]}, {"content": {"answer": "Campus Search Engine is the matching retrieval project.", "highlights": ["It uses Python and BM25.", "Top-10 hit rate reached 92%."], "citations": [{"experience_id": "exp_01ARZ3NDEKTSV4RRFFQ69G5FAV", "claim": "The archive records BM25 and a 92% hit rate.", "evidence_locations": ["github.com/example/campus-search"]}], "evidence_gaps": [], "next_actions": ["Keep the evaluation report with the repository."]}}]}
+{"id": "missing_evidence", "question": "检查发布自动化的量化结果是否有证据，并给出补证建议。", "experiences": [{"id": "exp_01ARZ3NDEKTSV4RRFFQ69G5FAW", "title": "Release Automation", "type": "work", "period": {"start": "2025-01", "end": "2025-08"}, "description": "Automated the release pipeline.", "technology": ["Python", "GitHub Actions"], "result": ["Reduced release time by 40%."], "evidence": []}], "expected_tool_sequence": ["search_experiences", "get_experience", "get_evidence_stats"], "expected_terms": ["40%", "evidence"], "label_source": "ai-assisted-synthetic", "expected_behavior_notes": "Report the stored number while explicitly identifying the missing supporting artifact.", "recorded_turns": [{"tool_calls": [{"id": "s2", "name": "search_experiences", "arguments": {"query": "release", "limit": 5}}, {"id": "g2", "name": "get_experience", "arguments": {"id_or_prefix": "exp_01ARZ3NDEKTSV4RRFFQ69G5FAW"}}, {"id": "e2", "name": "get_evidence_stats", "arguments": {}}]}, {"content": {"answer": "Release Automation records a 40% reduction, but it has no linked evidence.", "highlights": ["Python and GitHub Actions automate the workflow."], "citations": [{"experience_id": "exp_01ARZ3NDEKTSV4RRFFQ69G5FAW", "claim": "The stored result says release time fell by 40%.", "evidence_locations": []}], "evidence_gaps": ["The 40% result has no linked evidence."], "next_actions": ["Attach a before-and-after timing report."]}}]}
+{"id": "similar_record_disambiguation", "question": "只总结面向用户的 Release Dashboard，不要混入发布流水线项目。", "experiences": [{"id": "exp_01ARZ3NDEKTSV4RRFFQ69G5FAX", "title": "Release Dashboard", "type": "personal", "period": {"start": "2025-03", "end": "2025-05"}, "description": "Built a dashboard for release status.", "technology": ["TypeScript"], "evidence": [{"kind": "repo", "location": "github.com/example/release-dashboard"}]}, {"id": "exp_01ARZ3NDEKTSV4RRFFQ69G5FAY", "title": "Release Pipeline", "type": "work", "period": {"start": "2025-02", "end": "2025-06"}, "description": "Automated package publishing.", "technology": ["Python"], "evidence": [{"kind": "pull_request", "location": "github.com/example/platform/pull/42"}]}], "expected_tool_sequence": ["search_experiences", "get_experience"], "expected_terms": ["Dashboard", "TypeScript"], "label_source": "ai-assisted-synthetic", "expected_behavior_notes": "Search returns similar records; the full-record read and citation must select only the dashboard.", "recorded_turns": [{"tool_calls": [{"id": "s3", "name": "search_experiences", "arguments": {"query": "Release", "limit": 5}}, {"id": "g3", "name": "get_experience", "arguments": {"id_or_prefix": "exp_01ARZ3NDEKTSV4RRFFQ69G5FAX"}}]}, {"content": {"answer": "Release Dashboard is the user-facing project.", "highlights": ["It is implemented in TypeScript."], "citations": [{"experience_id": "exp_01ARZ3NDEKTSV4RRFFQ69G5FAX", "claim": "The dashboard tracks release status.", "evidence_locations": ["github.com/example/release-dashboard"]}], "evidence_gaps": [], "next_actions": ["Add a screenshot or usability note."]}}]}
+{"id": "direct_record_lookup", "question": "总结 exp_01ARZ3NDEKTSV4RRFFQ69G5FAZ，并保持引用可追溯。", "experiences": [{"id": "exp_01ARZ3NDEKTSV4RRFFQ69G5FAZ", "title": "CLI Importer", "type": "personal", "period": {"start": "2024-07", "end": "2024-08"}, "description": "Imported resume entries into structured records.", "technology": ["Python", "Typer"], "evidence": [{"kind": "file", "location": "demo/importer.cast"}]}], "expected_tool_sequence": ["get_experience"], "expected_terms": ["CLI Importer", "Typer"], "label_source": "ai-assisted-synthetic", "expected_behavior_notes": "A full exact ID makes search unnecessary; read the record and cite its real demo.", "recorded_turns": [{"tool_calls": [{"id": "g4", "name": "get_experience", "arguments": {"id_or_prefix": "exp_01ARZ3NDEKTSV4RRFFQ69G5FAZ"}}]}, {"content": {"answer": "CLI Importer converts resume entries into structured records.", "highlights": ["It uses Python and Typer."], "citations": [{"experience_id": "exp_01ARZ3NDEKTSV4RRFFQ69G5FAZ", "claim": "The CLI imports resume entries.", "evidence_locations": ["demo/importer.cast"]}], "evidence_gaps": [], "next_actions": ["Keep the demo recording current."]}}]}
+{"id": "reject_invented_location", "question": "总结证据，但不要虚构地址。", "experiences": [{"id": "exp_01ARZ3NDEKTSV4RRFFQ69G5FB0", "title": "Evidence Guard", "type": "personal", "period": {"start": "2025-04", "end": "2025-04"}, "description": "Validated grounded citations.", "evidence": [{"kind": "repo", "location": "github.com/example/evidence-guard"}]}], "expected_tool_sequence": ["get_experience"], "expected_terms": [], "expected_status": "paused", "expected_error_contains": "unknown evidence locations", "label_source": "ai-assisted-synthetic", "expected_behavior_notes": "The workflow must pause when final structured output invents an evidence location.", "recorded_turns": [{"tool_calls": [{"id": "g5", "name": "get_experience", "arguments": {"id_or_prefix": "exp_01ARZ3NDEKTSV4RRFFQ69G5FB0"}}]}, {"content": {"answer": "Evidence Guard validates citations.", "highlights": [], "citations": [{"experience_id": "exp_01ARZ3NDEKTSV4RRFFQ69G5FB0", "claim": "The project validates citations.", "evidence_locations": ["github.com/example/invented"]}], "evidence_gaps": [], "next_actions": []}}]}
+{"id": "invalid_tool_arguments", "question": "搜索记录并限制返回零条。", "experiences": [], "expected_tool_sequence": ["search_experiences"], "expected_terms": [], "expected_status": "paused", "expected_error_contains": "invalid arguments", "label_source": "ai-assisted-synthetic", "expected_behavior_notes": "Strict tool schemas must reject an out-of-range limit and leave a resumable checkpoint.", "recorded_turns": [{"tool_calls": [{"id": "s6", "name": "search_experiences", "arguments": {"query": "anything", "limit": 0}}]}]}
+{"id": "provider_failure_resume", "question": "总结可恢复项目，并在临时网络错误后继续。", "experiences": [{"id": "exp_01ARZ3NDEKTSV4RRFFQ69G5FB1", "title": "Recoverable Workflow", "type": "work", "period": {"start": "2025-05", "end": "2025-07"}, "description": "Checkpointed long-running work.", "technology": ["Python"], "evidence": [{"kind": "repo", "location": "github.com/example/recoverable"}]}], "expected_tool_sequence": ["get_experience"], "expected_terms": ["Recoverable Workflow", "checkpoint"], "resume_after_error": true, "label_source": "ai-assisted-synthetic", "expected_behavior_notes": "A provider error after tool execution must resume without executing the completed tool twice.", "recorded_turns": [{"tool_calls": [{"id": "g7", "name": "get_experience", "arguments": {"id_or_prefix": "exp_01ARZ3NDEKTSV4RRFFQ69G5FB1"}}]}, {"error": "simulated network failure"}, {"content": {"answer": "Recoverable Workflow checkpoints long-running work.", "highlights": ["The implementation uses Python."], "citations": [{"experience_id": "exp_01ARZ3NDEKTSV4RRFFQ69G5FB1", "claim": "The workflow persists checkpoints.", "evidence_locations": ["github.com/example/recoverable"]}], "evidence_gaps": [], "next_actions": ["Exercise recovery in CI."]}}]}
+{"id": "empty_archive", "question": "档案为空时明确说明证据缺口。", "experiences": [], "expected_tool_sequence": ["search_experiences", "get_evidence_stats"], "expected_terms": ["empty", "evidence"], "label_source": "ai-assisted-synthetic", "expected_behavior_notes": "The agent should inspect the empty archive and finish without fabricating a citation.", "recorded_turns": [{"tool_calls": [{"id": "s8", "name": "search_experiences", "arguments": {"query": "", "limit": 5}}, {"id": "e8", "name": "get_evidence_stats", "arguments": {}}]}, {"content": {"answer": "The experience archive is empty, so no evidence-backed brief can be produced.", "highlights": [], "citations": [], "evidence_gaps": ["No experience records or evidence are available."], "next_actions": ["Record and verify one experience first."]}}]}
+{"id": "invalid_structured_output", "question": "返回严格结构化摘要。", "experiences": [], "expected_tool_sequence": [], "expected_terms": [], "expected_status": "paused", "expected_error_contains": "schema validation", "label_source": "ai-assisted-synthetic", "expected_behavior_notes": "Local Pydantic validation must reject a response missing required structured fields; the workflow gives the model exactly one schema repair round, and a second invalid answer still pauses the run.", "recorded_turns": [{"content": {"answer": "Incomplete output", "highlights": [], "citations": [], "evidence_gaps": []}}, {"content": {"answer": "Still incomplete", "citations": [], "evidence_gaps": []}}]}

experienceos/ai/eval_manifest.json

@@ -0,0 +1,23 @@
+{
+  "manifest_version": 1,
+  "dataset": "experience_brief.jsonl",
+  "dataset_sha256": "18433be486d4d2b3e374dfe6f27372cb10a934209f45252b9656eb50526b1c29",
+  "case_count": 9,
+  "created_on": "2026-08-28",
+  "data_origin": "ai-assisted-synthetic",
+  "label_review": "not-independently-human-reviewed",
+  "contains_real_user_data": false,
+  "contains_personal_data": false,
+  "uses_external_source_records": false,
+  "evidence_locations": "placeholder-only",
+  "intended_use": [
+    "deterministic workflow regression",
+    "live-model smoke evaluation"
+  ],
+  "not_valid_for": [
+    "model accuracy claims",
+    "representative user-task claims",
+    "production performance claims"
+  ],
+  "license": "MIT repository test fixture"
+}