weakincentives 0.1.0__tar.gz → 0.2.0__tar.gz

{weakincentives-0.1.0 → weakincentives-0.2.0}/.github/workflows/release.yml

@@ -29,10 +29,13 @@ jobs:
     
     - name: Install dependencies
       run: uv sync
-    
+
     - name: Run checks
       run: make check
     
+    - name: Restore clean lockfile
+      run: git checkout -- uv.lock
+
     - name: Build package
       run: uv build
     

weakincentives-0.2.0/AGENTS.md

@@ -0,0 +1,95 @@
+# AGENTS.md
+
+This handbook is the primary source of truth for autonomous or assisted agents working in the `weakincentives` repository. WARP and other entrypoints should defer to this document.
+
+## Project Snapshot
+
+- **Goal**: Build tooling for "side effect free" background agents; current codebase is intentionally minimal and pre-alpha.
+- **Language**: Python 3.14 (see `.python-version`).
+- **Package manager**: [`uv`](https://github.com/astral-sh/uv) orchestrates dependency management and task execution.
+- **Build backend**: `hatchling` (configured in `pyproject.toml`).
+
+## Repository Tour
+
+- `src/weakincentives/`: Library source. Currently contains the prompt scaffolding and supporting modules.
+- `tests/`: Pytest suite. `tests/test_example.py` demonstrates the expected structure and ensures the package imports.
+- `specs/`: Design docs and product specifications. `PROMPTS.md` defines the prompt abstraction requirements—read this before adding prompt-related code.
+- `Makefile`: Canonical task surface (formatting, linting, typing, tests, aggregate checks, clean-up).
+- `uv.lock`: Dependency lockfile maintained by `uv`.
+- `hooks/` & `install-hooks.sh`: Symlink-based Git hook installer. Hooks expect `make check` to pass before commits land.
+- Version tags (`vX.Y.Z`, the `v` prefix is required) in git control the published package version; cut them manually when releasing.
+
+## Environment & Setup
+
+1. Install Python 3.14 (pyenv users can run `pyenv install 3.14.0` if needed).
+1. Install `uv` locally.
+1. Sync dependencies and development tooling:
+   ```bash
+   uv sync
+   ./install-hooks.sh
+   ```
+   The hook installer wires every script in `hooks/` into `.git/hooks/` via symlinks.
+
+## Day-to-Day Commands
+
+All commands are defined in `Makefile` and should be executed with `uv` to ensure a consistent virtualenv. The targets are configured to run in quiet mode—by default they suppress success chatter and surface only warnings or errors. Mirror this style when invoking tools manually so downstream agents process as few tokens as possible.
+
+- `make format`: Auto-format via `ruff format -q`.
+- `make format-check`: Formatting audit without changes (`ruff format -q --check`).
+- `make lint` / `make lint-fix`: Static analysis with Ruff in quiet mode (`ruff check --preview -q`; add `--fix` when autofixing).
+- `make bandit`: Security linting via `build/run_bandit.py`, which patches Python 3.14 AST regressions before invoking Bandit.
+- `make deptry`: Dependency graph audit on `src/weakincentives` that surfaces unused or missing requirements while staying quiet on success.
+- `make pip-audit`: Dependency vulnerability audit that stays silent on success via `build/run_pip_audit.py`.
+- `make markdown-check`: Runs `mdformat --check` through `build/run_mdformat.py` to ensure Markdown stays consistently formatted. This command now runs inside `make check`.
+- `make typecheck`: Runs `ty check -qq --error-on-warning` for silent success.
+- `make test`: Executes pytest through `build/run_pytest.py`, only emitting failures or warnings while enforcing coverage (`--cov-fail-under=80`).
+- `make check`: Aggregates format-check, lint, typecheck, Bandit, deptry, pip-audit, markdown-check, and tests with minimal output.
+- `make all`: Runs format, lint-fix, Bandit, pip-audit, typecheck, and tests while staying quiet on success.
+- `make clean`: Purges caches (`__pycache__`, `.pytest_cache`, `.ruff_cache`, `*.pyc`).
+
+Prefer `make check` before every commit; git hooks will call the same pipeline.
+
+**You MUST run `make check` before committing any changes.**
+
+## Optional Dependencies
+
+- `openai` is exposed as an extra. Install it with `uv sync --extra openai` during development or `pip install weakincentives[openai]` for consumers. Adapter modules guard imports and raise clear guidance when the extra is missing, so the core package stays lean.
+- `make test` (and thus `make check` / `make all`) automatically run with all extras enabled via `uv run --all-extras`, ensuring adapter integrations stay validated.
+
+## Testing & Quality Expectations
+
+- Pytest is configured in `pyproject.toml` to collect coverage on `src/weakincentives` and fail if coverage dips below 80%.
+- Type hints are part of the public contract (`py.typed`). Keep new code fully typed and run `make typecheck` when touching typing-sensitive areas.
+- Ruff is both the formatter and the linter. Obey the default line length of 88 and the Python target version `py314`.
+- Lint runs enable `I`, `UP`, `B`, `SIM`, `C4`, `ANN`, `RET`, `RSE`, `PTH`, and `ISC` rule families; fix or explicitly justify any violations when contributing.
+
+## TDD Workflow Recipe
+
+- Read the relevant spec in `specs/` and any prior plans to anchor scope, capture target module paths, and list the concrete behaviors you will validate.
+- Break the work into thin iterations that each pair a specific test module or case (for example `tests/prompts/test_text_section.py`) with the minimal production changes required in `src/weakincentives/`.
+- For every iteration, author the failing test first, run it directly with `uv run pytest tests/path_to_test.py -k target_case`, and confirm it asserts the desired API, errors, and context payloads.
+- Implement only the code needed to satisfy the new test (including exports and defaults), then rerun the targeted test and expand to `make test` once the local loop is green.
+- Refactor immediately after the test passes: deduplicate helpers, thread depth or placeholder metadata, and update docs so the next iteration starts from a clean slate.
+- Repeat the loop until the feature-level acceptance scenario is covered, finish with `make check`, and capture the final iteration summary in the commit message or handoff notes.
+
+## Release & Versioning Notes
+
+- Package releases read their version from the latest git tag (`vX.Y.Z`, must include the `v`). Use `git tag vX.Y.Z` followed by `git push origin vX.Y.Z` when you’re ready to release.
+- No publishing automation exists yet—coordinate manual releases outside this repository.
+
+## Adding Features
+
+- Mirror the structure in `tests/` when adding new modules—write tests alongside new code and keep them deterministic.
+- Follow test-driven development best practices while iterating; commit to the red→green→refactor loop so features stay focused and covered.
+- Reference `specs/PROMPTS.md` before modifying or introducing prompt-related functionality.
+- Write commit messages with useful descriptions that summarize the change set; avoid placeholder or empty messages.
+- Keep the `README.md` concise; extended onboarding belongs here in `AGENTS.md`.
+- When introducing new tooling, extend the `Makefile` so agents can discover it without hunting through scripts.
+
+## Quick Facts
+
+- `README.md` offers a public-facing overview; this document captures agent-facing operational details.
+- The codebase is intentionally small; expect to create new modules under `src/weakincentives/` rather than modifying many existing files.
+- All documentation should be ASCII unless the surrounding file already uses other characters.
+
+Use this document as the authoritative onboarding and execution guide for automated agents. Update it whenever workflows or tooling change.

weakincentives-0.2.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+Release highlights for weakincentives.
+
+## 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/Makefile

@@ -0,0 +1,58 @@
+.PHONY: format check test lint typecheck bandit deptry pip-audit markdown-check all clean
+
+# Format code with ruff
+format:
+	@uv run ruff format -q .
+
+# Check formatting without making changes
+format-check:
+	@uv run ruff format -q --check .
+
+# Run ruff linter
+lint:
+	@uv run ruff check --preview -q .
+
+# Run ruff linter with fixes
+lint-fix:
+	@uv run ruff check --fix -q .
+
+# Run Bandit security scanner
+bandit:
+	@uv run python build/run_bandit.py -q -r src/weakincentives
+
+# Check for unused or missing dependencies with deptry
+deptry:
+	@uv run python build/run_deptry.py
+
+# Run pip-audit for dependency vulnerabilities
+pip-audit:
+	@uv run python build/run_pip_audit.py
+
+# Validate Markdown formatting
+markdown-check:
+	@uv run python build/run_mdformat.py
+
+# Run type checkers
+typecheck:
+	@uv run --all-extras ty check --error-on-warning -qq . || \
+                (echo "ty check failed; rerunning with verbose output..." >&2; \
+                uv run --all-extras ty check --error-on-warning .)
+	@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)
+
+# Run tests with coverage (100% minimum)
+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 all checks (format check, lint, typecheck, bandit, deptry, pip-audit, markdown, test)
+check: format-check lint typecheck bandit deptry pip-audit markdown-check test
+
+# Run all checks and fixes
+all: format lint-fix bandit deptry pip-audit typecheck test
+
+# Clean cache files
+clean:
+	rm -rf .pytest_cache .ruff_cache __pycache__
+	find . -type d -name "__pycache__" -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete

weakincentives-0.2.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: weakincentives
+Version: 0.2.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.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: openai
+Requires-Dist: openai>=2.6.1; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Weak Incentives
+
+Tools for developing and optimizing side effect free background agents. The library ships prompt composition primitives, structured tool metadata, and optional provider adapters so you can scaffold deterministic automation flows quickly. All commands below assume Astral's `uv` CLI.
+
+## For Library Users
+
+### Installation
+
+- `uv add weakincentives`
+- Add `uv add "weakincentives[openai]"` (or `uv sync --extra openai` when cloning the repo) to enable the OpenAI adapter helpers.
+
+### Key Features
+
+- Fully typed prompt composition primitives (`Prompt`, `Section`, `TextSection`, `Tool`, `ToolResult`) for assembling deterministic Markdown prompts with attached tool metadata.
+- Stdlib-only dataclass serde utilities (`parse`, `dump`, `clone`, `schema`) for Pydantic-like ergonomics without third-party dependencies.
+- Optional OpenAI adapter that gates imports behind a friendly error and returns the SDK client when the extra is present.
+- Quiet-by-default package with minimal runtime dependencies so background agents stay lean and predictable.
+
+### Quickstart
+
+````python
+from dataclasses import dataclass
+
+from weakincentives.prompts import (
+    Prompt,
+    TextSection,
+    Tool,
+    ToolResult,
+    parse_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}", payload=details)
+
+
+catalog_tool = Tool[SourceLookup, SourceDetails](
+    name="catalog_lookup",
+    description="Look up a primary source identifier and return structured details.",
+    handler=lookup_source,
+)
+
+research_section = TextSection[ResearchGuidance](
+    title="Task",
+    body=(
+        "Research ${topic}. Use the `catalog_lookup` tool for citations and return"
+        " a JSON summary with citations."
+    ),
+    tools=[catalog_tool],
+)
+
+prompt = Prompt[ResearchSummary](
+    name="research_run",
+    sections=[research_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"]
+}
+```"""
+
+parsed = parse_output(reply, rendered)
+print(parsed.summary)
+print(parsed.citations)
+````
+
+### Optional Extras
+
+Use the OpenAI helpers once the extra is installed:
+
+```python
+from weakincentives.adapters import OpenAIAdapter
+
+adapter = OpenAIAdapter(model="gpt-4o-mini", client_kwargs={"api_key": "sk-..."})
+```
+
+If the dependency is missing, the adapter raises a runtime error with installation guidance.
+
+## For Library Developers
+
+### Environment Setup
+
+1. Install Python 3.14 (pyenv users can run `pyenv install 3.14.0`).
+1. Install [`uv`](https://github.com/astral-sh/uv).
+1. Sync the virtualenv and optional git hooks:
+   ```bash
+   uv sync
+   ./install-hooks.sh  # optional – wires git hooks that call make check
+   ```
+1. Use `uv run ...` when invoking ad-hoc scripts so everything stays inside the managed environment.
+
+### Development Workflow
+
+- `make format` / `make format-check` — run Ruff formatters.
+- `make lint` / `make lint-fix` — lint with Ruff.
+- `make typecheck` — execute Ty with warnings promoted to errors.
+- `make test` — run pytest via `build/run_pytest.py` with `--cov-fail-under=100`.
+- `make bandit`, `make deptry`, `make pip-audit` — security, dependency, and vulnerability audits.
+- `make check` — aggregate the quiet quality gate; run this before every commit (git hooks enforce it).
+
+### Project Layout
+
+- `src/weakincentives/` — package root for the Python module.
+- `src/weakincentives/prompts/` — prompt, section, and tool primitives.
+- `src/weakincentives/adapters/` — optional provider integrations.
+- `tests/` — pytest suites covering prompts, tools, and adapters.
+- `specs/` — design docs; see `specs/PROMPTS.md` for prompt requirements.
+- `build/` — thin wrappers that keep CLI tools quiet inside `uv`.
+- `hooks/` — symlink-friendly git hooks (install via `./install-hooks.sh`).
+
+### Release Notes
+
+Version numbers come from git tags named `vX.Y.Z`. Tag the repository manually before pushing a release.
+
+### More Documentation
+
+`AGENTS.md` captures the full agent handbook, workflows, and TDD expectations. `ROADMAP.md` and `specs/` document upcoming work and prompt requirements.

weakincentives-0.2.0/README.md

@@ -0,0 +1,146 @@
+# Weak Incentives
+
+Tools for developing and optimizing side effect free background agents. The library ships prompt composition primitives, structured tool metadata, and optional provider adapters so you can scaffold deterministic automation flows quickly. All commands below assume Astral's `uv` CLI.
+
+## For Library Users
+
+### Installation
+
+- `uv add weakincentives`
+- Add `uv add "weakincentives[openai]"` (or `uv sync --extra openai` when cloning the repo) to enable the OpenAI adapter helpers.
+
+### Key Features
+
+- Fully typed prompt composition primitives (`Prompt`, `Section`, `TextSection`, `Tool`, `ToolResult`) for assembling deterministic Markdown prompts with attached tool metadata.
+- Stdlib-only dataclass serde utilities (`parse`, `dump`, `clone`, `schema`) for Pydantic-like ergonomics without third-party dependencies.
+- Optional OpenAI adapter that gates imports behind a friendly error and returns the SDK client when the extra is present.
+- Quiet-by-default package with minimal runtime dependencies so background agents stay lean and predictable.
+
+### Quickstart
+
+````python
+from dataclasses import dataclass
+
+from weakincentives.prompts import (
+    Prompt,
+    TextSection,
+    Tool,
+    ToolResult,
+    parse_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}", payload=details)
+
+
+catalog_tool = Tool[SourceLookup, SourceDetails](
+    name="catalog_lookup",
+    description="Look up a primary source identifier and return structured details.",
+    handler=lookup_source,
+)
+
+research_section = TextSection[ResearchGuidance](
+    title="Task",
+    body=(
+        "Research ${topic}. Use the `catalog_lookup` tool for citations and return"
+        " a JSON summary with citations."
+    ),
+    tools=[catalog_tool],
+)
+
+prompt = Prompt[ResearchSummary](
+    name="research_run",
+    sections=[research_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"]
+}
+```"""
+
+parsed = parse_output(reply, rendered)
+print(parsed.summary)
+print(parsed.citations)
+````
+
+### Optional Extras
+
+Use the OpenAI helpers once the extra is installed:
+
+```python
+from weakincentives.adapters import OpenAIAdapter
+
+adapter = OpenAIAdapter(model="gpt-4o-mini", client_kwargs={"api_key": "sk-..."})
+```
+
+If the dependency is missing, the adapter raises a runtime error with installation guidance.
+
+## For Library Developers
+
+### Environment Setup
+
+1. Install Python 3.14 (pyenv users can run `pyenv install 3.14.0`).
+1. Install [`uv`](https://github.com/astral-sh/uv).
+1. Sync the virtualenv and optional git hooks:
+   ```bash
+   uv sync
+   ./install-hooks.sh  # optional – wires git hooks that call make check
+   ```
+1. Use `uv run ...` when invoking ad-hoc scripts so everything stays inside the managed environment.
+
+### Development Workflow
+
+- `make format` / `make format-check` — run Ruff formatters.
+- `make lint` / `make lint-fix` — lint with Ruff.
+- `make typecheck` — execute Ty with warnings promoted to errors.
+- `make test` — run pytest via `build/run_pytest.py` with `--cov-fail-under=100`.
+- `make bandit`, `make deptry`, `make pip-audit` — security, dependency, and vulnerability audits.
+- `make check` — aggregate the quiet quality gate; run this before every commit (git hooks enforce it).
+
+### Project Layout
+
+- `src/weakincentives/` — package root for the Python module.
+- `src/weakincentives/prompts/` — prompt, section, and tool primitives.
+- `src/weakincentives/adapters/` — optional provider integrations.
+- `tests/` — pytest suites covering prompts, tools, and adapters.
+- `specs/` — design docs; see `specs/PROMPTS.md` for prompt requirements.
+- `build/` — thin wrappers that keep CLI tools quiet inside `uv`.
+- `hooks/` — symlink-friendly git hooks (install via `./install-hooks.sh`).
+
+### Release Notes
+
+Version numbers come from git tags named `vX.Y.Z`. Tag the repository manually before pushing a release.
+
+### More Documentation
+
+`AGENTS.md` captures the full agent handbook, workflows, and TDD expectations. `ROADMAP.md` and `specs/` document upcoming work and prompt requirements.

weakincentives-0.2.0/ROADMAP.md

@@ -0,0 +1,64 @@
+# Roadmap
+
+## 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
+
+- 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.
+
+### Single Turn Prompt Optimizations
+
+- Profile current single-turn flows to surface latency and token usage hot spots.
+- Experiment with prompt compression techniques and instruction restructuring to maintain quality while reducing cost.
+- Add benchmarks or harness scripts that assert improvements before regression.
+
+### Named Entities Handling (Input and Output)
+
+- Introduce utilities for detecting and tagging named entities across inputs.
+- 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.
+- Surface sandbox lifecycle APIs that expose logs, artifacts, and exit metadata without leaking host resources.
+- Add validation suites and stress tests that assert isolation boundaries hold across supported runtimes.
+
+### Agentic Reasoning Loop
+
+- Design an orchestrator that coordinates system prompts, user turns, tool routing, and session state updates.
+- Integrate entity resolvers and named-entity policies to normalize inputs before tool calls and responses.
+- Document the execution phases (think, act, observe) with diagrams and tests that enforce correct transitions.
+
+### Tracing & Observability
+
+- Capture structured trace data from agent runs, including tool calls and message content classification.
+- Export telemetry to persistent storage with configurable redaction for sensitive fields and PII.
+- Provide replay and visualization utilities that allow developers to inspect state transitions and timing.
+
+### Subagents & Parallel Execution
+
+- Enable the primary agent to spawn scoped subagents with dedicated sessions for independent objectives.
+- Coordinate concurrent execution, result aggregation, and conflict resolution when subagents touch shared resources.
+- Provide lifecycle hooks so subagents inherit policies, tools, and logging while remaining cancellable.
+
+## Out of Scope (For Now)
+
+- Graph-based agent composers—current focus is flexible orchestration over rigid node/edge pipelines.
+- Retrieval and memory connectors—the library assumes ambient context rather than external knowledge stores.
+- Human-in-the-loop gating—agents should operate autonomously once launched inside controlled environments.
+- Evaluation frameworks beyond prompt optimization—the only supported eval loops will target prompt tuning scenarios.

weakincentives-0.2.0/WARP.md

@@ -0,0 +1,3 @@
+# WARP.md
+
+`AGENTS.md` is the canonical guide for working in this repository. Please follow the workflows documented there.

weakincentives-0.2.0/concat_all.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def iter_project_files(target: Path) -> list[Path]:
+    if not target.exists():
+        return []
+    return [
+        path
+        for path in sorted(target.rglob("*"))
+        if path.is_file() and path.suffix != ".pyc"
+    ]
+
+
+def emit_file(path: Path, project_root: Path) -> None:
+    relative_path = path.relative_to(project_root).as_posix()
+    sys.stdout.write(f"{relative_path}\n")
+    with path.open("r", encoding="utf-8", errors="replace") as stream:
+        contents = stream.read()
+    sys.stdout.write(contents)
+    if not contents.endswith("\n"):
+        sys.stdout.write("\n")
+
+
+def main() -> None:
+    project_root = Path(__file__).resolve().parent
+    prelude_files = [project_root / "README.md", project_root / "ROADMAP.md"]
+    postlude_files = [
+        project_root / "pyproject.toml",
+        project_root / "openai_example.py",
+    ]
+    targets = [project_root / "specs", project_root / "src"]
+
+    for path in prelude_files:
+        if path.exists():
+            emit_file(path, project_root)
+
+    for target in targets:
+        for path in iter_project_files(target):
+            emit_file(path, project_root)
+
+    for path in postlude_files:
+        if path.exists():
+            emit_file(path, project_root)
+
+
+if __name__ == "__main__":
+    main()