purrcept-core 0.5.1__tar.gz

purrcept_core-0.5.1/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --all-groups
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pyright
+      - run: uv run pytest --cov=purrcept_core --cov-report=term-missing
+      - name: Run examples
+        run: |
+          uv run python examples/01_inline_effect.py
+          uv run python examples/02_declarative_effect.py
+          uv run python examples/03_error_recovery.py
+          uv run python examples/04_nested_flow.py
+          uv run python examples/05_progress_events.py
+          uv run python examples/06_model_conversation.py
+      - if: matrix.python-version == '3.11'
+        name: Run external extension-package example
+        run: >-
+          uv run
+          --with-editable .
+          --with-editable ./examples/plugin_package
+          python examples/plugin_package/demo.py
+      - if: matrix.python-version == '3.11'
+        name: Build Core and extension distributions
+        run: |
+          uv build
+          uv build --project ./examples/plugin_package --out-dir ./dist/plugin_package
+      - if: matrix.python-version == '3.11'
+        name: Install wheels in a clean environment
+        run: |
+          uv venv --python 3.11 .wheel-venv
+          uv pip install --python .wheel-venv/bin/python \
+            dist/purrcept_core-*-py3-none-any.whl \
+            dist/plugin_package/purrcept_demo_plugin-*-py3-none-any.whl
+          uv pip check --python .wheel-venv/bin/python
+          .wheel-venv/bin/python -c "from importlib.resources import files; assert files('purrcept_core').joinpath('py.typed').is_file()"
+          .wheel-venv/bin/python examples/plugin_package/demo.py
+      - if: matrix.python-version == '3.11'
+        name: Install source distributions in a clean environment
+        run: |
+          uv venv --python 3.11 .sdist-venv
+          uv pip install --python .sdist-venv/bin/python \
+            dist/purrcept_core-*.tar.gz
+          uv pip install --python .sdist-venv/bin/python \
+            dist/plugin_package/purrcept_demo_plugin-*.tar.gz
+          uv pip check --python .sdist-venv/bin/python
+          .sdist-venv/bin/python -c "from importlib.resources import files; assert files('purrcept_core').joinpath('py.typed').is_file()"
+          .sdist-venv/bin/python examples/plugin_package/demo.py

purrcept_core-0.5.1/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+# Build and validate the release tag before granting a separate job PyPI access.
+# The publisher consumes only the checked distribution artifacts, not source code.
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Validate and build distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.release.tag_name }}
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.11"
+          enable-cache: false
+      - name: Check release tag against package version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          uv run --no-project python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          tag = os.environ["RELEASE_TAG"]
+          if tag != f"v{version}":
+              raise SystemExit(f"Release tag {tag!r} does not match package version {version!r}.")
+          PY
+      # Resolve published dependencies; a developer's sibling editable checkout must
+      # never supply a dependency that users cannot install from PyPI.
+      - run: uv sync --no-sources --all-groups
+      - run: uv run --no-sync ruff check .
+      - run: uv run --no-sync ruff format --check .
+      - run: uv run --no-sync pyright
+      - run: uv run --no-sync pytest --cov=purrcept_core --cov-report=term-missing
+      - run: uv build --no-sources
+      - run: uvx --from twine twine check --strict dist/*
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish distributions
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/purrcept-core/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist/
+      - name: Publish with PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

purrcept_core-0.5.1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.pytest_cache/
+.ruff_cache/
+.venv/
+.wheel-venv/
+.sdist-venv/
+.pyright/
+build/
+dist/
+htmlcov/

purrcept_core-0.5.1/AGENTS.md

@@ -0,0 +1,115 @@
+## Git commit messages
+
+Write all new Git commit subjects and bodies in Chinese. Technical names, code
+identifiers, and commands may retain their original spelling.
+
+## Source narrative and commenting style
+
+Purrcept Core is an abstraction-heavy SDK. Source code must be optimized for
+guided reading and long-term maintenance, not for minimum line count.
+
+### General principle
+
+A reader should be able to understand the responsibility, control flow,
+invariants, and extension points of a module without repeatedly searching
+through unrelated files.
+
+Comments must explain semantic intent, constraints, ordering, lifecycle, or
+design rationale. Do not add comments that merely restate the code.
+
+### Module documentation
+
+Every non-trivial module must begin with a module docstring that explains:
+
+- What the module owns.
+- What the module intentionally does not own.
+- Its primary entry points.
+- Its major processing stages.
+- Its important invariants.
+- Its relationship to neighboring modules.
+
+Small data-only or re-export modules may use a shorter docstring.
+
+### Abstract interfaces
+
+Every public Protocol, ABC, abstract class, and extension interface must
+document:
+
+- Who creates it.
+- Who calls it.
+- When it is called.
+- Preconditions and postconditions.
+- State ownership and lifecycle.
+- Ordering and mutation rules.
+- Error behavior.
+- Built-in implementations.
+- How an implementation is selected.
+
+The abstraction owns the shared contract. Concrete implementations should
+document only behavior that differs from that contract.
+
+### Functions and methods
+
+All public functions and methods require docstrings.
+
+Private functions also require a docstring or an immediately adjacent block
+comment when they involve non-obvious behavior, state changes, ordering,
+caching, concurrency, lifecycle, error handling, or algorithmic decisions.
+
+Trivial private helpers whose complete semantics are obvious from their name,
+signature, and body do not require a docstring.
+
+### Narrative flow
+
+Functions containing multiple conceptual phases must separate those phases
+with blank lines.
+
+Add a short block comment before a phase when its purpose or ordering is not
+obvious. Phase comments should explain why the phase exists or why it occurs
+at that point, rather than paraphrasing its statements.
+
+The main orchestration path must remain visible. Do not extract small private
+helpers solely to reduce function length when doing so hides the overall flow.
+
+### Section boundaries
+
+Long modules should use restrained semantic section headings:
+
+    # ---------------------------------------------------------------------------
+    # Reminder resolution
+    # ---------------------------------------------------------------------------
+
+Use section headings only for substantial conceptual regions. Prefer domain
+names such as "Context budget allocation" over structural names such as
+"Private helpers".
+
+### Required rationale comments
+
+Explicitly document:
+
+- Invariants and state transitions.
+- Order-dependent behavior.
+- Cache-key and stable-prefix decisions.
+- Ownership and concurrency assumptions.
+- Retry, suppression, and exception translation.
+- Provider compatibility workarounds.
+- Deliberate rejection of an obvious alternative.
+- Cross-module hand-off points.
+- Non-obvious performance tradeoffs.
+
+Critical comments may begin with `Invariant:`, `Ordering:`, `Cache:`,
+`Compatibility:`, or `Lifecycle:`.
+
+### Style
+
+Write comments as complete sentences. Keep them close to the behavior they
+explain. Use paragraphs for multi-sentence explanations.
+
+Do not repeat type hints, signatures, or obvious operations.
+
+When changing behavior, update or remove affected comments in the same change.
+A stale comment is a correctness defect.
+
+Before completing a change, read every modified file from top to bottom as a
+new maintainer. Add enough orientation that the main control flow can be
+understood before opening helper implementations.

purrcept_core-0.5.1/CHANGELOG.md

@@ -0,0 +1,158 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## Unreleased
+
+## 0.5.1 - 2026-09-08
+
+- Resolve callable instance annotations from `__call__` explicitly on Python 3.14,
+  preserving FunctionTool support across the advertised Python versions.
+- Publish validated wheel and source distributions automatically when a GitHub Release
+  is published, using PyPI Trusted Publishing and an isolated publishing job.
+
+- Add `ReasoningDelta` as an immutable, separately indexed stream of provider-exposed
+  readable reasoning or summaries. It never contains opaque continuation state.
+- Restore the documented default of eight model rounds in both conversation factories;
+  the previous zero default contradicted the positive-round validator.
+
+### Clarified
+
+- Reminder placement is position relative to history, not wire role. Provider
+  adapters must not serialize `SystemReminder` as the system role; that role is
+  reserved for `SystemInstruction`. Chat Completions adapters emit reminders as
+  user messages.
+
+## 0.5.0 - 2026-07-28
+
+### Added
+
+- Immutable `ReminderState` and complete `ConversationCheckpoint` values so prompt-control state
+  can be snapshotted, restored, forked, and cleared independently from committed history.
+- A deterministic `PromptCompiler` boundary with `PromptDraft`, `CompiledPrompt`, metadata-only
+  `PromptDiagnostics`, and optional synchronous prompt trace events.
+- Synchronous, conversation-local `ReminderSource` projections that are resolved before every
+  model request and naturally refresh after tool execution without weakening the busy guard.
+- `RequestTokenBudget` and `RequestTokenCounter` for budgeting the complete `ModelRequest`,
+  including instructions, tools, messages, reminders, and provider-neutral request overhead.
+- Multi-request Provider Conformance scenarios for reminder removal and keyed replacement, plus
+  explicit reminder order and placement fixtures.
+
+### Changed
+
+- `NEXT_REQUEST` reminders are consumed only after a request has compiled and passed its request
+  budget; `TURN` reminders are acquired when the turn Flow first advances and expire on every
+  ending path.
+- `CONVERSATION` reminders now require a non-empty key.
+- `Conversation.snapshot()` now returns `ConversationCheckpoint`. Use `history_snapshot()` and
+  `restore_history()` when only committed transcript state is intended.
+- `Conversation.fork()` copies complete mutable state while retaining the same reusable
+  configuration. Full checkpoints and state mutations remain unavailable while a turn is busy.
+- `TokenBudgetContext` is explicitly transcript-only; complete prompt budgeting uses
+  `RequestTokenBudget`.
+
+### Deprecated
+
+- `Conversation.clear()` is retained as a warning-emitting alias for `clear_history()`. Use
+  `reset()` to clear both committed history and stored reminders.
+
+### Design
+
+- Reminders remain prompt-control state and never become canonical conversation messages.
+- Dynamic source output and reusable configuration are deliberately excluded from checkpoints.
+- Provider continuations must not retain reminders that are absent or replaced in a later
+  `ModelRequest`.
+
+## 0.4.0 - 2026-07-28
+
+### Added
+
+- Immutable `PromptTemplate` values with strict and partial rendering, exact dotted placeholder
+  keys, immutable value binding, and direct compilation to `SystemInstruction`, `Message`, or
+  `SystemReminder`.
+- Composable synchronous `RenderPolicy` values and built-in `optional`, `trim`, `header`, `wrap`,
+  `join_blocks`, and `min_len` policies.
+- `PromptLibrary`, an immutable local named template registry, plus structured prompt definition,
+  lookup, and rendering errors.
+- First-class template inputs for `model.conversation()`, `conversation.ask()`, and
+  `conversation.remind()`.
+
+### Design
+
+- Prompt authoring is compiled before the Provider boundary, so `ModelRequest` remains a
+  provider-neutral transport value.
+- Core intentionally has no global prompt manager, import-time template registration, global
+  build event, or hidden reminder content.
+- Existing `SystemReminder` scope, placement, priority, replacement, and consumption behavior is
+  unchanged.
+
+## 0.3.0 - 2026-07-26
+
+### Added
+
+- `Model`, an explicit binding between a runtime-owned backend and one model name.
+- `Conversation`, immutable `ConversationState`, transactional turns, snapshots, restore, fork,
+  and the official observable tool-loop Flow.
+- `FunctionTool`, `ToolSet`, `ToolContext`, `InvokeTool`, `ToolParameter`, tool policies, and
+  provider-neutral tool results and errors.
+- Pydantic v2-powered internal JSON Schema generation and argument validation without exposing
+  Pydantic types in the public protocol.
+- `SystemInstruction`, scoped `SystemReminder`, prompt cache/stability policies, model settings,
+  and opaque Provider continuation state.
+- Append-only, complete-turn sliding-window, and injected token-budget context policies.
+- Expanded token usage for cache reads, cache writes, and reasoning tokens.
+- A deterministic Provider Backend Conformance Kit covering request semantics, streaming,
+  model errors, and cancellation.
+
+### Changed
+
+- The documented default path is now
+  `Model → Conversation → FunctionTool → SystemReminder`; low-level requests and `Generate`
+  remain the escape hatch.
+- `Generate` now carries an explicit `Model`, and `model.generate(request)` is the preferred
+  one-shot constructor.
+- `ModelBackend.generate()` now receives the selected model name as a required keyword argument.
+- System-level prompt content is represented separately from conversational messages.
+- Common generation controls now live in `ModelSettings`; tools use `ToolSpec`.
+- Each model generation and Python tool invocation in the automatic loop remains an independent
+  Effect.
+
+### Removed
+
+- The implicit single-backend host binding used by model generation.
+- The system role and system-message convenience constructor.
+- Model-name and common generation-setting fields from the flat request surface.
+
+### Compatibility
+
+- This is an intentional alpha breaking release. See
+  [`docs/compatibility.md`](docs/compatibility.md) for the migration guide.
+- Purrcept Core now has a runtime dependency on Pydantic v2.
+
+## 0.2.0 - 2026-07-26
+
+### Added
+
+- Provider-neutral model contracts in the `purrcept_core.models` capability layer.
+- Immutable message, content block, request, response, usage, and streaming event types.
+- A shared model error hierarchy for provider-independent retry and recovery policies.
+- A self-executing one-shot model-generation Effect and runtime-owned Backend protocol.
+- Runtime validation for Backend responses and ordered stream-event lifecycles.
+
+### Changed
+
+- Model contracts ship in the same distribution while remaining isolated from the generic
+  Effect/Driver kernel.
+- The external extension example implements the official model protocol instead of defining
+  its own contract.
+
+## 0.1.0 - 2026-07-26
+
+### Added
+
+- Effect and generator-flow primitives.
+- Generator-backed and protocol-based agent runs.
+- Inline, dispatch, and middleware executors.
+- Deterministic lifecycle events and progress reporting.
+- Async agent driver with explicit error and cancellation semantics.
+- Testing helpers, runnable examples, and an external extension-package example.

purrcept_core-0.5.1/CONTRIBUTING.md

@@ -0,0 +1,221 @@
+# Contributing
+
+Purrcept Core 保持两条清晰边界：
+
+- 通用内核中，Flow 决定下一步，Effect 描述一次操作，Executor 执行，Driver 推进 Run；
+- 模型标准库中，Conversation 编排独立的 Generate / InvokeTool Effect，并面向统一的
+  Provider 协议。
+
+平台会话、数据库、持久化、调度、网络、Provider client、凭据、平台工具和业务权限仍
+属于 Runtime 或独立扩展包。不要通过全局 Registry、import-time 注册、隐藏重试或隐藏
+模型调用跨越边界。
+
+开发环境使用 Python 3.11+ 和 `uv`：
+
+```bash
+uv sync --all-groups
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv run pytest
+uv run python -m build
+```
+
+新增公共行为应包含聚焦测试和对应文档，并维持分支覆盖率门禁。模型值对象应保持不可变、
+Provider 无关和 keyword-only 可扩展性。新的自动化步骤必须继续以可观察 Effect 表达。
+
+函数工具可以在内部使用 Pydantic v2，但公共注解、Protocol、值对象和错误不能暴露
+Pydantic 类型。涉及 Python 3.11 `TypedDict` 的工具测试应优先使用
+`typing_extensions.TypedDict`。
+
+Provider 适配变更应运行标准 Backend Conformance Kit，并在扩展包中补充供应商
+wire-format、SDK 版本、认证和特殊能力测试。新增运行时依赖需要说明维护成本、替换边界
+和为什么现有能力不足。
+
+## Source Readability and Narrative Documentation
+
+Repository-specific instructions take precedence over this section.
+
+Treat source code as a technical document for future maintainers. Optimize for
+guided reading, clear control flow, and explicit design intent rather than
+minimum line count or maximum compactness.
+
+Types describe data shape. Names describe local actions. Documentation and
+comments must explain semantics, contracts, constraints, ordering, lifecycle,
+ownership, and design rationale.
+
+### General requirements
+
+- Preserve the repository's established documentation language and style.
+- If no documentation language is established, use English.
+- Write comments and documentation as complete, precise sentences.
+- Do not add comments merely to increase comment coverage.
+- Do not assume that clean naming, type hints, or private visibility make
+  non-obvious behavior self-explanatory.
+- Documentation is part of correctness. Stale or misleading comments are
+  defects and must be updated with the code.
+
+### Files and modules
+
+Every non-trivial source file or module must provide an opening documentation
+comment or module docstring that gives the reader an initial mental model.
+
+When relevant, explain:
+
+- What the module owns.
+- What it intentionally does not own.
+- Its primary entry points.
+- Its major processing stages.
+- Its important invariants.
+- Its relationship to neighboring modules.
+- Where concrete implementations or extension points can be found.
+
+Small data-only modules, generated files, re-export modules, and obvious
+single-purpose wrappers may use shorter documentation.
+
+### Public APIs and abstractions
+
+Document all public APIs and all extension-facing abstractions.
+
+Protocols, abstract classes, interfaces, hooks, policies, strategies, and
+lifecycle components must document their shared contract, including relevant
+details such as:
+
+- Who creates the object.
+- Who calls it.
+- When it is called.
+- Preconditions and postconditions.
+- State ownership and mutation rules.
+- Ordering guarantees.
+- Concurrency and reuse assumptions.
+- Error behavior.
+- Built-in implementations.
+- How an implementation is selected or registered.
+
+The abstraction should own the shared contract. Concrete implementations
+should document only behavior that differs from or extends that contract.
+
+Do not write documentation that merely repeats a function signature, type
+annotation, field name, or return type. Explain what the values mean and what
+callers may rely on.
+
+### Private functions
+
+Private visibility does not remove the need for explanation.
+
+A private function requires a docstring or a nearby rationale comment when it
+contains non-obvious:
+
+- State changes.
+- Ordering dependencies.
+- Cache behavior.
+- Lifecycle behavior.
+- Ownership or concurrency assumptions.
+- Failure, retry, fallback, or suppression behavior.
+- Algorithms or heuristics.
+- Compatibility workarounds.
+- Cross-module hand-offs.
+- Semantics that cannot be inferred from its name, signature, and body at a
+  glance.
+
+Trivial private helpers whose complete behavior is obvious may omit a
+docstring.
+
+### Narrative control flow
+
+The main orchestration path should read from top to bottom like an outline of
+the operation.
+
+- Keep major processing stages visible in the main function.
+- Use meaningful intermediate variables instead of deeply nested expressions
+  when they represent distinct concepts.
+- Separate conceptual phases with blank lines.
+- Add a short block comment before a phase when its purpose or position is not
+  obvious.
+- Explain why a phase exists or why it must occur at that point. Do not merely
+  paraphrase the statements below it.
+- Extract helpers only when they represent a meaningful concept, isolate real
+  complexity, enable reuse, improve testing, or hide irrelevant detail.
+- Do not split a readable workflow into many tiny private methods solely to
+  reduce function length.
+- Do not compress multiple semantic operations into one expression solely to
+  reduce line count.
+
+A reader should be able to understand the overall workflow before opening
+every helper implementation.
+
+### Required rationale comments
+
+Explicitly document behavior involving:
+
+- Invariants and state transitions.
+- Steps whose order must not change.
+- Stable prefixes, cache keys, invalidation, or cache boundaries.
+- Object ownership, resource lifetime, or concurrency.
+- Exception translation, ignored failures, retries, and fallbacks.
+- Provider, platform, protocol, or version compatibility.
+- Non-obvious performance or memory tradeoffs.
+- Security-sensitive decisions.
+- Deliberate rejection of a simpler-looking alternative.
+- Code that appears redundant but must not be removed.
+- Handoffs between subsystems.
+
+Critical comments may begin with labels such as:
+
+- `Invariant:`
+- `Ordering:`
+- `Cache:`
+- `Lifecycle:`
+- `Concurrency:`
+- `Compatibility:`
+- `Security:`
+
+Use these labels selectively, only when they improve discoverability.
+
+### File structure and visual rhythm
+
+Long files may use restrained semantic section headings, for example:
+
+    # ---------------------------------------------------------------------------
+    # Context budget allocation
+    # ---------------------------------------------------------------------------
+
+Use section headings only for substantial conceptual regions. Prefer domain
+headings such as `Reminder resolution` over structural headings such as
+`Private helpers`.
+
+Use whitespace to communicate changes in thought. Code should not appear as
+an uninterrupted dense block when it contains multiple conceptual stages.
+
+### Avoid
+
+Do not write comments that:
+
+- Restate obvious code.
+- Repeat type annotations.
+- Use vague verbs such as "handle", "process", or "manage" without explaining
+  the actual semantics.
+- Describe fragile line-by-line implementation details instead of stable
+  intent.
+- Compensate for poor names or unclear abstractions.
+- Duplicate large amounts of documentation across an interface and all its
+  implementations.
+- Claim behavior that is not enforced by the implementation or tests.
+
+### Completion check
+
+Before completing a change, read every modified file from top to bottom as a
+new maintainer.
+
+Verify that:
+
+- The file's responsibility and entry points are quickly understandable.
+- The main control flow is visible without excessive navigation.
+- Abstract contracts and extension points are documented.
+- Important ordering, state, cache, lifecycle, and concurrency rules are
+  explained.
+- Dense expressions have not hidden distinct conceptual steps.
+- Comments explain information that the code alone does not communicate.
+- All affected documentation and comments still match the implementation.
+
+Improve the narrative readability before considering the task complete.