weakincentives 0.2.0__tar.gz → 0.3.0__tar.gz

weakincentives-0.3.0/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "makefile.configureOnOpen": false
+}

weakincentives-0.3.0/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+Release highlights for weakincentives.
+
+## Unreleased
+
+- No changes yet.
+
+## v0.3.0 - 2025-11-01
+
+### Prompt & Rendering
+
+- Renamed and reorganized the prompt authoring primitives (`MarkdownSection`,
+  `SectionNode`, `Tool`, `ToolResult`, `parse_structured_output`, …) under the
+  consolidated `weakincentives.prompt` surface.
+- Prompts now require namespaces and explicit section keys so overrides line up with
+  rendered content and structured response formats.
+- Added tool-aware prompt version metadata and the `PromptVersionStore` override
+  workflow to track section edits and tool changes across revisions.
+
+### Session & State
+
+- Introduced the `Session` container with typed reducers/selectors that capture prompt
+  outputs and tool payloads directly from emitted events.
+- Added helper reducers (`append`, `replace_latest`, `upsert_by`) and selectors
+  (`select_latest`, `select_where`) to simplify downstream state management.
+
+### Built-in Tools
+
+- Shipped the planning tool suite (`PlanningToolsSection` plus typed plan dataclasses)
+  for creating, updating, and tracking multi-step execution plans inside a session.
+- Added the virtual filesystem tool suite (`VfsToolsSection`) with host-mount
+  materialization, ASCII write limits, and reducers that maintain a versioned snapshot.
+
+### Events & Telemetry
+
+- Implemented the event bus with `ToolInvoked` and `PromptExecuted` payloads and wired
+  adapters/examples to publish them for sessions or external observers.
+
+### Adapters
+
+- Added a LiteLLM adapter behind the `litellm` extra with tool execution parity and
+  structured output parsing.
+- Updated the OpenAI adapter to emit native JSON schema response formats, tighten
+  `tool_choice` handling, avoid echoing tool payloads, and surface richer telemetry.
+
+### Examples
+
+- Rebuilt the OpenAI and LiteLLM demos as shared CLI entry points powered by the new
+  code review agent scaffold, complete with planning and virtual filesystem sections.
+
+### Tooling & Packaging
+
+- Lowered the supported Python baseline to 3.12 (the repository now pins 3.14 for
+  development) and curated package exports to match the reorganized modules.
+- Added OpenAI integration tests and stabilized the tool execution loop used by the
+  adapters.
+- Raised the optional `litellm` extra to require the latest upstream release.
+
+### Documentation
+
+- Documented the planning and virtual filesystem tool suites, optional provider extras,
+  and updated installation guidance.
+- Refreshed the README and supporting docs to highlight the new prompt workflow,
+  adapters, and development tooling expectations.
+
+## v0.2.0 - 2025-10-29
+
+### Highlights
+
+- Launched the prompt composition system with typed `Prompt`, `Section`, and `TextSection` building blocks, structured rendering, and placeholder validation backed by comprehensive tests.
+- Added tool orchestration primitives including the `Tool` dataclass, shared dataclass handling, duplicate detection, and prompt-level aggregation utilities.
+- Delivered stdlib-only dataclass serde helpers (`parse`, `dump`, `clone`, `schema`) for lightweight validation and JSON serialization.
+
+### Integrations
+
+- Introduced an optional OpenAI adapter behind the `openai` extra that builds configured clients and provides friendly guidance when the dependency is missing.
+
+### Developer Experience
+
+- Tightened the quality gate with quiet wrappers for Ruff, Ty, pytest (100% coverage), Bandit, Deptry, and pip-audit, all wired through `make check`.
+- Adopted Hatch VCS versioning, refreshed `pyproject.toml` metadata, and standardized automation scripts for releases.
+
+### Documentation
+
+- Replaced `WARP.md` with a comprehensive `AGENTS.md` handbook describing workflows, TDD guidance, and integration expectations.
+- Added prompt and tool specifications under `specs/` and refreshed the README to highlight the new primitives and developer tooling.
+
+## v0.1.0 - 2025-10-22
+
+Initial repository bootstrap with the package scaffold, testing and linting toolchain, CI configuration, and contributor documentation.

{weakincentives-0.2.0 → weakincentives-0.3.0}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: format check test lint typecheck bandit deptry pip-audit markdown-check all clean
+.PHONY: format check test lint typecheck bandit deptry pip-audit markdown-check integration-tests all clean
 
 # Format code with ruff
 format:
@@ -34,9 +34,9 @@ markdown-check:
 
 # Run type checkers
 typecheck:
-	@uv run --all-extras ty check --error-on-warning -qq . || \
+	@uv run --all-extras ty check --error-on-warning -qq --exclude 'test-repositories/**' . || \
                 (echo "ty check failed; rerunning with verbose output..." >&2; \
-                uv run --all-extras ty check --error-on-warning .)
+                uv run --all-extras ty check --error-on-warning --exclude 'test-repositories/**' .)
 	@uv run --all-extras pyright --project pyproject.toml || \
 		(echo "pyright failed; rerunning with verbose output..." >&2; \
 		uv run --all-extras pyright --project pyproject.toml --verbose)
@@ -45,6 +45,14 @@ typecheck:
 test:
 	@uv run --all-extras python build/run_pytest.py --strict-config --strict-markers --maxfail=1 --cov-fail-under=100 -q --no-header --no-summary --cov-report=
 
+# Run OpenAI integration tests
+integration-tests:
+	@if [ -z "$$OPENAI_API_KEY" ]; then \
+		echo "OPENAI_API_KEY is not set; export it to run integration tests." >&2; \
+		exit 1; \
+	fi
+	@uv run --all-extras pytest --no-cov --strict-config --strict-markers -vv --maxfail=1 integration-tests
+
 # Run all checks (format check, lint, typecheck, bandit, deptry, pip-audit, markdown, test)
 check: format-check lint typecheck bandit deptry pip-audit markdown-check test
 

weakincentives-0.3.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: weakincentives
+Version: 0.3.0
+Summary: Tools for developing and optimizing side effect free background agents
+Project-URL: Homepage, https://weakincentives.com/
+Project-URL: Documentation, https://github.com/weakincentives/weakincentives#readme
+Project-URL: Repository, https://github.com/weakincentives/weakincentives
+Project-URL: Issue Tracker, https://github.com/weakincentives/weakincentives/issues
+Author-email: Andrei Savu <andrei@weakincentives.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,background-agents,optimization,side-effect-free,weak-incentives
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.79.0; extra == 'litellm'
+Provides-Extra: openai
+Requires-Dist: openai>=2.6.1; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Weak Incentives
+
+**Lean, typed building blocks for side-effect-free background agents.**
+Compose deterministic prompts, run typed tools, and parse strict JSON replies without
+heavy dependencies. Optional adapters snap in when you need a model provider.
+
+## Highlights
+
+- Namespaced prompt trees with deterministic Markdown renders, placeholder
+  verification, and tool-aware versioning metadata.
+- Stdlib-only dataclass serde (`parse`, `dump`, `clone`, `schema`) keeps request and
+  response types honest end-to-end.
+- Session state container and event bus collect prompt and tool telemetry for
+  downstream automation.
+- Built-in planning and virtual filesystem tool suites give agents durable plans and
+  sandboxed edits backed by reducers and selectors.
+- Optional OpenAI and LiteLLM adapters integrate structured output parsing, tool
+  orchestration, and telemetry hooks.
+
+## Requirements
+
+- Python 3.12+ (the repository pins 3.14 in `.python-version` for development)
+- [`uv`](https://github.com/astral-sh/uv) CLI
+
+## Install
+
+```bash
+uv add weakincentives
+# optional provider adapters
+uv add "weakincentives[openai]"
+uv add "weakincentives[litellm]"
+# cloning the repo? use: uv sync --extra openai --extra litellm
+```
+
+## Quickstart
+
+````python
+from dataclasses import dataclass
+from weakincentives import (
+    MarkdownSection,
+    Prompt,
+    Tool,
+    ToolResult,
+    parse_structured_output,
+)
+
+@dataclass
+class ResearchGuidance:
+    topic: str
+
+@dataclass
+class SourceLookup:
+    source_id: str
+
+@dataclass
+class SourceDetails:
+    source_id: str
+    title: str
+
+@dataclass
+class ResearchSummary:
+    summary: str
+    citations: list[str]
+
+def lookup_source(params: SourceLookup) -> ToolResult[SourceDetails]:
+    details = SourceDetails(source_id=params.source_id, title="Ada Lovelace Archive")
+    return ToolResult(message=f"Loaded {details.title}", value=details)
+
+catalog_tool = Tool[SourceLookup, SourceDetails](
+    name="catalog_lookup",
+    description="Look up a primary source identifier and return details.",
+    handler=lookup_source,
+)
+
+task_section = MarkdownSection[ResearchGuidance](
+    title="Task",
+    template=(
+        "Research ${topic}. Use `catalog_lookup` for citations and reply with a "
+        "JSON summary."
+    ),
+    key="research.task",
+    tools=[catalog_tool],
+)
+
+prompt = Prompt[ResearchSummary](
+    ns="examples/research",
+    key="research.run",
+    name="research_prompt",
+    sections=[task_section],
+)
+
+rendered = prompt.render(ResearchGuidance(topic="Ada Lovelace"))
+print(rendered.text)
+print([tool.name for tool in rendered.tools])
+
+reply = """```json
+{
+  "summary": "Ada Lovelace pioneered computing...",
+  "citations": ["catalog_lookup:ada-archive"]
+}
+```"""
+result = parse_structured_output(reply, rendered)
+print(result.summary)
+print(result.citations)
+````
+
+The rendered prompt text stays deterministic, tool metadata travels with the prompt,
+and `parse_structured_output` enforces your dataclass contract.
+
+## Sessions and Built-in Tools
+
+Session state turns prompt output and tool calls into durable data. Built-in planning
+and virtual filesystem sections register reducers on the provided session.
+
+```python
+from weakincentives.session import Session, select_latest
+from weakincentives.tools import (
+    PlanningToolsSection,
+    Plan,
+    VfsToolsSection,
+    VirtualFileSystem,
+)
+
+session = Session()
+planning_section = PlanningToolsSection(session=session)
+vfs_section = VfsToolsSection(session=session)
+
+prompt = Prompt[ResearchSummary](
+    ns="examples/research",
+    key="research.session",
+    sections=[task_section, planning_section, vfs_section],
+)
+
+active_plan = select_latest(session, Plan)
+vfs_snapshot = select_latest(session, VirtualFileSystem)
+```
+
+Use `session.select_all(...)` or the helpers in `weakincentives.session` to drive UI
+state, persistence, or audits after each adapter run.
+
+## Adapter Integrations
+
+Adapters stay optional and only load their dependencies when you import them.
+
+```python
+from weakincentives.adapters.openai import OpenAIAdapter
+from weakincentives.events import InProcessEventBus
+from weakincentives.session import Session
+from weakincentives.tools import Plan
+
+bus = InProcessEventBus()
+session = Session(bus=bus)
+
+adapter = OpenAIAdapter(
+    model="gpt-4o-mini",
+    client_kwargs={"api_key": "sk-..."},
+)
+
+response = adapter.evaluate(
+    prompt,
+    ResearchGuidance(topic="Ada Lovelace"),
+    bus=bus,
+)
+
+plan_history = session.select_all(Plan)
+```
+
+`InProcessEventBus` publishes `ToolInvoked` and `PromptExecuted` events for the
+session (or any other subscriber) to consume.
+
+## Development Setup
+
+1. Install Python 3.14 (for example with `pyenv install 3.14.0`).
+
+1. Install `uv`, then bootstrap the environment and hooks:
+
+   ```bash
+   uv sync
+   ./install-hooks.sh
+   ```
+
+1. Run checks with `uv run` so everything shares the managed virtualenv:
+
+   - `make format` / `make format-check`
+   - `make lint` / `make lint-fix`
+   - `make typecheck` (Ty + Pyright, warnings fail the build)
+   - `make test` (pytest via `build/run_pytest.py`, 100% coverage enforced)
+   - `make check` (aggregates the quiet checks above plus Bandit, Deptry, pip-audit,
+     and markdown linting)
+
+## Documentation
+
+- `AGENTS.md` — operational handbook and contributor workflow.
+- `specs/` — design docs for prompts, planning tools, and adapters.
+- `ROADMAP.md` — upcoming feature sketches.
+- `docs/api/` — API reference material.
+
+## License
+
+Apache 2.0 • Status: Alpha (APIs may change between releases)

weakincentives-0.3.0/README.md

@@ -0,0 +1,200 @@
+# Weak Incentives
+
+**Lean, typed building blocks for side-effect-free background agents.**
+Compose deterministic prompts, run typed tools, and parse strict JSON replies without
+heavy dependencies. Optional adapters snap in when you need a model provider.
+
+## Highlights
+
+- Namespaced prompt trees with deterministic Markdown renders, placeholder
+  verification, and tool-aware versioning metadata.
+- Stdlib-only dataclass serde (`parse`, `dump`, `clone`, `schema`) keeps request and
+  response types honest end-to-end.
+- Session state container and event bus collect prompt and tool telemetry for
+  downstream automation.
+- Built-in planning and virtual filesystem tool suites give agents durable plans and
+  sandboxed edits backed by reducers and selectors.
+- Optional OpenAI and LiteLLM adapters integrate structured output parsing, tool
+  orchestration, and telemetry hooks.
+
+## Requirements
+
+- Python 3.12+ (the repository pins 3.14 in `.python-version` for development)
+- [`uv`](https://github.com/astral-sh/uv) CLI
+
+## Install
+
+```bash
+uv add weakincentives
+# optional provider adapters
+uv add "weakincentives[openai]"
+uv add "weakincentives[litellm]"
+# cloning the repo? use: uv sync --extra openai --extra litellm
+```
+
+## Quickstart
+
+````python
+from dataclasses import dataclass
+from weakincentives import (
+    MarkdownSection,
+    Prompt,
+    Tool,
+    ToolResult,
+    parse_structured_output,
+)
+
+@dataclass
+class ResearchGuidance:
+    topic: str
+
+@dataclass
+class SourceLookup:
+    source_id: str
+
+@dataclass
+class SourceDetails:
+    source_id: str
+    title: str
+
+@dataclass
+class ResearchSummary:
+    summary: str
+    citations: list[str]
+
+def lookup_source(params: SourceLookup) -> ToolResult[SourceDetails]:
+    details = SourceDetails(source_id=params.source_id, title="Ada Lovelace Archive")
+    return ToolResult(message=f"Loaded {details.title}", value=details)
+
+catalog_tool = Tool[SourceLookup, SourceDetails](
+    name="catalog_lookup",
+    description="Look up a primary source identifier and return details.",
+    handler=lookup_source,
+)
+
+task_section = MarkdownSection[ResearchGuidance](
+    title="Task",
+    template=(
+        "Research ${topic}. Use `catalog_lookup` for citations and reply with a "
+        "JSON summary."
+    ),
+    key="research.task",
+    tools=[catalog_tool],
+)
+
+prompt = Prompt[ResearchSummary](
+    ns="examples/research",
+    key="research.run",
+    name="research_prompt",
+    sections=[task_section],
+)
+
+rendered = prompt.render(ResearchGuidance(topic="Ada Lovelace"))
+print(rendered.text)
+print([tool.name for tool in rendered.tools])
+
+reply = """```json
+{
+  "summary": "Ada Lovelace pioneered computing...",
+  "citations": ["catalog_lookup:ada-archive"]
+}
+```"""
+result = parse_structured_output(reply, rendered)
+print(result.summary)
+print(result.citations)
+````
+
+The rendered prompt text stays deterministic, tool metadata travels with the prompt,
+and `parse_structured_output` enforces your dataclass contract.
+
+## Sessions and Built-in Tools
+
+Session state turns prompt output and tool calls into durable data. Built-in planning
+and virtual filesystem sections register reducers on the provided session.
+
+```python
+from weakincentives.session import Session, select_latest
+from weakincentives.tools import (
+    PlanningToolsSection,
+    Plan,
+    VfsToolsSection,
+    VirtualFileSystem,
+)
+
+session = Session()
+planning_section = PlanningToolsSection(session=session)
+vfs_section = VfsToolsSection(session=session)
+
+prompt = Prompt[ResearchSummary](
+    ns="examples/research",
+    key="research.session",
+    sections=[task_section, planning_section, vfs_section],
+)
+
+active_plan = select_latest(session, Plan)
+vfs_snapshot = select_latest(session, VirtualFileSystem)
+```
+
+Use `session.select_all(...)` or the helpers in `weakincentives.session` to drive UI
+state, persistence, or audits after each adapter run.
+
+## Adapter Integrations
+
+Adapters stay optional and only load their dependencies when you import them.
+
+```python
+from weakincentives.adapters.openai import OpenAIAdapter
+from weakincentives.events import InProcessEventBus
+from weakincentives.session import Session
+from weakincentives.tools import Plan
+
+bus = InProcessEventBus()
+session = Session(bus=bus)
+
+adapter = OpenAIAdapter(
+    model="gpt-4o-mini",
+    client_kwargs={"api_key": "sk-..."},
+)
+
+response = adapter.evaluate(
+    prompt,
+    ResearchGuidance(topic="Ada Lovelace"),
+    bus=bus,
+)
+
+plan_history = session.select_all(Plan)
+```
+
+`InProcessEventBus` publishes `ToolInvoked` and `PromptExecuted` events for the
+session (or any other subscriber) to consume.
+
+## Development Setup
+
+1. Install Python 3.14 (for example with `pyenv install 3.14.0`).
+
+1. Install `uv`, then bootstrap the environment and hooks:
+
+   ```bash
+   uv sync
+   ./install-hooks.sh
+   ```
+
+1. Run checks with `uv run` so everything shares the managed virtualenv:
+
+   - `make format` / `make format-check`
+   - `make lint` / `make lint-fix`
+   - `make typecheck` (Ty + Pyright, warnings fail the build)
+   - `make test` (pytest via `build/run_pytest.py`, 100% coverage enforced)
+   - `make check` (aggregates the quiet checks above plus Bandit, Deptry, pip-audit,
+     and markdown linting)
+
+## Documentation
+
+- `AGENTS.md` — operational handbook and contributor workflow.
+- `specs/` — design docs for prompts, planning tools, and adapters.
+- `ROADMAP.md` — upcoming feature sketches.
+- `docs/api/` — API reference material.
+
+## License
+
+Apache 2.0 • Status: Alpha (APIs may change between releases)

{weakincentives-0.2.0 → weakincentives-0.3.0}/ROADMAP.md

@@ -2,17 +2,11 @@
 
 ## Near-Term Initiatives
 
-### Session State Container
-
-- Formalize a `Session` abstraction that captures conversation state, tool outputs, and transient metadata.
-- Define serialization hooks so sessions can persist across process restarts without leaking sensitive data.
-- Thread the session object through existing prompt and tool layers, backed by integration tests that assert idempotent replay.
-
-### Notes System Retrospectives
+### Built-In Planning & Virtual Filesystem Tools
 
-- Establish a notes pattern that captures retrospectives for individual prompt invocations and entire sessions.
-- Model notes as entities that can attach to `Section` objects and `Tool` objects to preserve context.
-- Outline lifecycle and storage expectations so notes integrate cleanly with existing session state abstractions.
+- Provide first-class tool definitions for planning/todo workflows and virtual filesystem operations for agents.
+- Establish section templates that ensure tools render consistently in prompts and downstream telemetry.
+- Ship representative examples and regression tests demonstrating safe defaults and extensibility points.
 
 ### Single Turn Prompt Optimizations
 
@@ -26,12 +20,6 @@
 - Preserve, normalize, or obfuscate entities in outputs according to privacy and compliance guidelines.
 - Validate the pipeline with targeted tests that cover multilingual and domain-specific vocabularies.
 
-### Built-In Planning & Virtual Filesystem Tools
-
-- Provide first-class tool definitions for planning/todo workflows and virtual filesystem operations for agents.
-- Establish section templates that ensure tools render consistently in prompts and downstream telemetry.
-- Ship representative examples and regression tests demonstrating safe defaults and extensibility points.
-
 ### Sandboxed Code Execution
 
 - Provide hardened sandboxes so agents can run generated code with strict CPU, memory, filesystem, and network guardrails.

{weakincentives-0.2.0 → weakincentives-0.3.0}/concat_all.py

@@ -43,6 +43,7 @@ def main() -> None:
     postlude_files = [
         project_root / "pyproject.toml",
         project_root / "openai_example.py",
+        project_root / "litellm_example.py",
     ]
     targets = [project_root / "specs", project_root / "src"]
 

weakincentives-0.3.0/docs/api/weakincentives/tools/planning.md

@@ -0,0 +1,90 @@
+# `weakincentives.tools.planning`
+
+Session-scoped planning helpers for agents that need a lightweight task list.
+These APIs are transient and scoped to a single `Session` instance.
+
+## Data classes
+
+### `Plan`
+
+Tracks the current objective, overall status (`"active"`, `"completed"`, or
+`"abandoned"`), and an ordered collection of `PlanStep` entries.
+
+### `PlanStep`
+
+Immutable representation of an individual plan step. Includes a stable
+`step_id`, a short title, optional details, current `StepStatus`, and recorded
+notes.
+
+### `NewPlanStep`
+
+Input payload used when creating or appending steps before they receive a
+`step_id`.
+
+### `SetupPlan`
+
+Parameters for `planning_setup_plan`. Captures the plan objective and optional
+initial steps.
+
+### `AddStep`
+
+Parameters for `planning_add_step`. Contains one or more `NewPlanStep`
+instances to append to the active plan.
+
+### `UpdateStep`
+
+Parameters for `planning_update_step`. Identifies an existing step and provides
+updated title and/or details.
+
+### `MarkStep`
+
+Parameters for `planning_mark_step`. Identifies an existing step, sets a new
+status, and optionally appends a note.
+
+### `ClearPlan`
+
+Parameters for `planning_clear_plan`. Signals that the current plan should be
+marked as abandoned and cleared.
+
+### `ReadPlan`
+
+Parameters for `planning_read_plan`. Requests the latest plan snapshot from the
+session store.
+
+## Tools
+
+### `planning_setup_plan(params: SetupPlan) -> SetupPlan`
+
+Validate and persist a new plan. Replaces any existing plan and seeds step
+identifiers starting at `S001`.
+
+### `planning_add_step(params: AddStep) -> AddStep`
+
+Validate appended steps and queue them for persistence. Requires an active
+plan.
+
+### `planning_update_step(params: UpdateStep) -> UpdateStep`
+
+Validate a step edit request and persist title/detail changes for the targeted
+step.
+
+### `planning_mark_step(params: MarkStep) -> MarkStep`
+
+Validate a step status change, append optional notes, and toggle the plan's
+completion status when all steps are done.
+
+### `planning_clear_plan(params: ClearPlan) -> ClearPlan`
+
+Mark the current plan as abandoned and reset the step list.
+
+### `planning_read_plan(params: ReadPlan) -> Plan`
+
+Return the most recent plan snapshot. Raises a validation error when no plan
+has been initialised.
+
+## Prompt integration
+
+### `PlanningToolsSection`
+
+Prompt section that registers reducers on the provided `Session`, exposes all
+planning tools, and renders concise usage guidance for the language model.