weakincentives 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

weakincentives-0.4.0.dist-info/METADATA

@@ -0,0 +1,490 @@
+Metadata-Version: 2.4
+Name: weakincentives
+Version: 0.4.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
+Requires-Dist: asteval>=1.0.6
+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.
+
+## Why now?
+
+This library was built out of frustration with LangGraph and DSPy to explore
+better ways to do state and context management when building apps with LLMs
+while allowing the prompts to be automatically optimized.
+
+## 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
+```
+
+## Tutorial: Build a Stateful Code-Reviewing Agent
+
+Use Weak Incentives to assemble a reproducible reviewer that tracks every
+decision, stages file edits in a sandbox, and evaluates quick calculations when
+the diff raises questions. Compared to LangGraph you do not need to bolt on a
+custom state store—the `Session` captures prompt and tool telemetry out of the
+box. Unlike DSPy, prompt sections already expose versioning and override hooks
+so optimizers can swap instructions without rewriting the runtime.
+
+### 1. Model review data and expected outputs
+
+Typed dataclasses keep inputs and outputs honest so adapters can emit consistent
+telemetry and structured responses stay predictable.
+
+```python
+from dataclasses import dataclass
+
+
+@dataclass
+class PullRequestContext:
+    repository: str
+    title: str
+    body: str
+    files_summary: str
+
+
+@dataclass
+class ReviewComment:
+    file_path: str
+    line: int
+    severity: str
+    summary: str
+    rationale: str
+
+
+@dataclass
+class ReviewBundle:
+    comments: tuple[ReviewComment, ...]
+    overall_assessment: str
+```
+
+### 2. Create a session, surface built-in tool suites, and mount diffs
+
+Planning, virtual filesystem, and Python-evaluation sections register reducers on
+the provided session. Introducing them early keeps every evaluation capable of
+multi-step plans, staged edits, and quick calculations. Host mounts feed the
+reviewer precomputed diffs before the run begins so it can read them through the
+virtual filesystem tools without calling back to your orchestrator.
+
+```python
+from pathlib import Path
+
+from weakincentives.events import InProcessEventBus, PromptExecuted
+from weakincentives.session import Session
+from weakincentives.tools import (
+    AstevalSection,
+    HostMount,
+    PlanningToolsSection,
+    VfsPath,
+    VfsToolsSection,
+)
+
+
+bus = InProcessEventBus()
+session = Session(bus=bus)
+
+
+diff_root = Path("/srv/agent-mounts")
+diff_root.mkdir(parents=True, exist_ok=True)
+vfs_section = VfsToolsSection(
+    session=session,
+    allowed_host_roots=(diff_root,),
+    mounts=(
+        HostMount(
+            host_path="octo_widgets/cache-layer.diff",
+            mount_path=VfsPath(("diffs", "cache-layer.diff")),
+        ),
+    ),
+)
+planning_section = PlanningToolsSection(session=session)
+asteval_section = AstevalSection(session=session)
+
+
+def log_prompt(event: PromptExecuted) -> None:
+    print(
+        f"Prompt {event.prompt_name} completed with "
+        f"{len(event.result.tool_results)} tool calls"
+    )
+
+
+bus.subscribe(PromptExecuted, log_prompt)
+```
+
+Copy unified diff files into `/srv/agent-mounts` before launching the run. The
+host mount resolves `octo_widgets/cache-layer.diff` relative to that directory
+and exposes it to the agent as `diffs/cache-layer.diff` inside the virtual
+filesystem snapshot.
+
+### 3. Compose the prompt with deterministic sections
+
+Sections rely on `string.Template`, so prepare readable placeholders up front.
+Combine your review instructions with the built-in tool suites to publish a
+single, auditable prompt tree.
+
+```python
+from weakincentives import MarkdownSection, Prompt
+
+
+@dataclass
+class ReviewGuidance:
+    severity_scale: str = "minor | major | critical"
+    output_schema: str = "ReviewBundle with comments[] and overall_assessment"
+    focus_areas: str = (
+        "Security regressions, concurrency bugs, test coverage gaps, and"
+        " ambiguous logic should be escalated."
+    )
+
+
+overview_section = MarkdownSection[PullRequestContext](
+    title="Repository Overview",
+    key="review.overview",
+    template="""
+    You are a principal engineer reviewing a pull request.
+    Repository: ${repository}
+    Title: ${title}
+
+    Pull request summary:
+    ${body}
+
+    Files touched: ${files_summary}
+    """,
+)
+
+
+analysis_section = MarkdownSection[ReviewGuidance](
+    title="Review Directives",
+    key="review.directives",
+    template="""
+    - Classify findings using this severity scale: ${severity_scale}.
+    - Emit output that matches ${output_schema}; missing fields fail the run.
+    - Investigation focus:
+      ${focus_areas}
+    - Inspect mounted diffs under `diffs/` with `vfs_read_file` before
+      commenting on unfamiliar hunks.
+    """,
+    default_params=ReviewGuidance(),
+)
+
+
+review_prompt = Prompt[ReviewBundle](
+    ns="tutorial/code_review",
+    key="review.generate",
+    name="code_review_agent",
+    sections=(
+        overview_section,
+        planning_section,
+        vfs_section,
+        asteval_section,
+        analysis_section,
+    ),
+)
+
+
+rendered = review_prompt.render(
+    PullRequestContext(
+        repository="octo/widgets",
+        title="Add caching layer",
+        body="Introduces memoization to reduce redundant IO while preserving correctness.",
+        files_summary="loader.py, cache.py",
+    ),
+)
+
+
+print(rendered.text)
+print([tool.name for tool in rendered.tools])
+```
+
+### 4. Evaluate the prompt with an adapter
+
+Adapters send the rendered prompt to a provider and publish telemetry to the
+event bus. The session subscribed above automatically ingests each
+`PromptExecuted` and `ToolInvoked` event.
+
+```python
+from weakincentives.adapters.openai import OpenAIAdapter
+
+
+adapter = OpenAIAdapter(
+    model="gpt-4o-mini",
+    client_kwargs={"api_key": "sk-..."},
+)
+
+
+response = adapter.evaluate(
+    review_prompt,
+    PullRequestContext(
+        repository="octo/widgets",
+        title="Add caching layer",
+        body="Introduces memoization to reduce redundant IO while preserving correctness.",
+        files_summary="loader.py, cache.py",
+    ),
+    bus=bus,
+)
+
+
+bundle = response.output
+if bundle is None:
+    raise RuntimeError("Structured parsing failed")
+
+
+for comment in bundle.comments:
+    print(f"{comment.file_path}:{comment.line} → {comment.summary}")
+```
+
+If the model omits a required field, `OpenAIAdapter` raises `PromptEvaluationError`
+with provider context rather than silently degrading.
+
+### 5. Mine session state for downstream automation
+
+Built-in selectors expose the data collected by reducers that each tool suite
+registered. This gives you ready-to-ship audit logs without building LangGraph
+callbacks or DSPy side channels.
+
+```python
+from weakincentives.session import select_all, select_latest
+from weakincentives.tools import Plan, VirtualFileSystem
+
+
+plan_history = select_all(session, Plan)
+latest_plan = select_latest(session, Plan)
+vfs_snapshot = select_latest(session, VirtualFileSystem)
+
+
+print(f"Plan steps recorded: {len(plan_history)}")
+if latest_plan:
+    for step in latest_plan.steps:
+        print(f"- [{step.status}] {step.title}")
+
+
+if vfs_snapshot:
+    for file in vfs_snapshot.files:
+        print(f"Staged file {file.path.segments} (version {file.version})")
+```
+
+### 6. Override sections with a version store
+
+DSPy-style optimizers can persist improved instructions and let the runtime swap
+them in without re-deploying code. Implement the `PromptVersionStore` protocol to
+serve overrides by namespace, key, and tag.
+
+```python
+from dataclasses import dataclass
+from weakincentives.prompt.versioning import (
+    PromptDescriptor,
+    PromptOverride,
+    PromptVersionStore,
+)
+
+
+@dataclass
+class StaticVersionStore(PromptVersionStore):
+    override: PromptOverride | None = None
+
+
+    def resolve(
+        self,
+        descriptor: PromptDescriptor,
+        tag: str = "latest",
+    ) -> PromptOverride | None:
+        if (
+            self.override
+            and self.override.ns == descriptor.ns
+            and self.override.prompt_key == descriptor.key
+            and self.override.tag == tag
+        ):
+            return self.override
+        return None
+
+
+overrides = PromptOverride(
+    ns=review_prompt.ns,
+    prompt_key=review_prompt.key,
+    tag="assertive-feedback",
+    overrides={
+        ("review.directives",): """
+        - Classify findings using this severity scale: minor | major | critical.
+        - Always cite the exact diff hunk when raising a major or critical issue.
+        - Respond with ReviewBundle JSON. Missing fields terminate the run.
+        """,
+    },
+)
+
+
+store = StaticVersionStore(override=overrides)
+rendered_with_override = review_prompt.render_with_overrides(
+    PullRequestContext(
+        repository="octo/widgets",
+        title="Add caching layer",
+        body="Introduces memoization to reduce redundant IO while preserving correctness.",
+        files_summary="loader.py, cache.py",
+    ),
+    version_store=store,
+    tag="assertive-feedback",
+)
+
+
+print(rendered_with_override.text)
+```
+
+Because sections expose stable `(ns, key, path)` identifiers, overrides stay scoped
+to the intended content. That means optimizers can explore new directives without
+risking accidental prompt drift elsewhere in the tree.
+
+### 7. Ship it
+
+You now have a deterministic reviewer that:
+
+1. Enforces typed contracts for inputs, tools, and outputs.
+1. Persists multi-step plans, VFS edits, and evaluation transcripts inside a
+   session without custom plumbing.
+1. Supports optimizer-driven overrides that slot cleanly into CI, evaluation
+   harnesses, or on-call tuning workflows.
+
+Drop the agent into a queue worker, Slack bot, or scheduled job. Every evaluation
+is replayable thanks to the captured session state, so postmortems start with
+facts—not speculation.
+
+## 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.dist-info → weakincentives-0.4.0.dist-info}/RECORD

@@ -1,35 +1,36 @@
-weakincentives/__init__.py,sha256=MOVuBbGbGA2O_QS69wH8E17bkRc_fHQ2Z0MGD-79ngE,1092
+weakincentives/__init__.py,sha256=d6uIlHj5DSwWYQ5Ky9J1qQXaK0vgj-OJeoMQXjfhqyI,1049
 weakincentives/events.py,sha256=s1ddTuCOgKNcRZvL9T7vX7PUOXbifD8Gr1QJiuenA6c,3048
 weakincentives/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-weakincentives/adapters/__init__.py,sha256=loPj9FVLCSm2zZu8-8GV9h_Usc3lPISzojPOlS2Us8k,948
+weakincentives/adapters/__init__.py,sha256=YWZqiAce-auh8sIAdGRcyYAh69uNXgh76Rjm5yZHIEw,977
 weakincentives/adapters/core.py,sha256=Eo1309SsjZPPET_xCIjbSoeSQmakwwLdVXDlv2ZlulI,2101
 weakincentives/adapters/litellm.py,sha256=ZO8B05zZ8JkHirxciCQPZjxNILFWCop3LjvcKU4SBmA,21261
 weakincentives/adapters/openai.py,sha256=LEYih4EcQ7So-b_sTItgRt-6JVRITsfO0aG847TpHNs,20871
 weakincentives/examples/__init__.py,sha256=SNyUBOjzdKl4UkaEk99uSenVnqDvK7m1UnAe27Rhry8,1724
-weakincentives/examples/code_review_prompt.py,sha256=VkLS3ZNcyxWQLX6VxH8MmTWbKCjDxNFnjye2nbhMcK8,4316
-weakincentives/examples/code_review_session.py,sha256=ArCrBiakJb3DlcNjVw2s420zdVOsdT8Pq_fQaTItGyE,5236
+weakincentives/examples/code_review_prompt.py,sha256=oMHwzQ6EoifvH2oBmo_FxBsY3yklQXFkln7sdswf9nk,4602
+weakincentives/examples/code_review_session.py,sha256=YrfnfIbNMqylz0uvIGIREn4mAv4kcjEmS1OMrK-Yqv8,5434
 weakincentives/examples/code_review_tools.py,sha256=rOTZBxgMZfuy8b_oNCJu31BskeExSa4jWB3GPOSJ88g,11193
 weakincentives/prompt/__init__.py,sha256=gPGFeVN6puN-P1ztqFrobE5zRb3CJ4_JZJSmPatIjUo,1274
 weakincentives/prompt/_types.py,sha256=zvb4KrJyqFGhilmvzvgZzIxpZhm1LRIzc8vwugnZ2jY,925
 weakincentives/prompt/errors.py,sha256=DR3GN54oTnNARkto3mVbIuT6BwhijTP3onLpcB6jdq0,1664
-weakincentives/prompt/markdown.py,sha256=KUqxKfRWvASNzAyLno7M0Z0d7TWx8jc6qiWaWImBiHY,3460
-weakincentives/prompt/prompt.py,sha256=tO-u9ZdjlzdTSjc6obvhniV3564ry7yilHZhmJVUf00,22962
+weakincentives/prompt/markdown.py,sha256=DM3rUcqvknwuZB6viojTkrWkePSTy8oI8PILy1mROdg,3414
+weakincentives/prompt/prompt.py,sha256=VrcEnc-RJG3mxMXgufW09pVAO6zFyGj8fuCT9XC3mjg,22676
 weakincentives/prompt/response_format.py,sha256=uYGg2mD6KIXuBDGgx65szV7er804ychb0zuZj9Irtuo,1805
 weakincentives/prompt/section.py,sha256=LdqoZADjsvvSpTvPzG0Unan_N-q1AgPWw-0F2LrWn5Y,4962
-weakincentives/prompt/structured_output.py,sha256=v3Ton3DpJbXYOf-itpUrUJtIad9j58oHmZ1UeMCRviY,5286
-weakincentives/prompt/tool.py,sha256=_a5vKUfH6mBYtHWbf1KFk4RlXr6O9endzB4yjh9tTiE,9156
+weakincentives/prompt/structured_output.py,sha256=SdK645AD3cz_Kkz-50eyO2YhSUmXQ0HzuFvLTftBhCQ,5207
+weakincentives/prompt/tool.py,sha256=XLy5lcWgtsL2ZPnylOoPVhUUJlhBozwobalJofLqMpM,9114
 weakincentives/prompt/versioning.py,sha256=Ur0rLYvVvMuoGxOB-SzYIALMlK6IKbOvxJWf2HsE9lQ,4034
 weakincentives/serde/__init__.py,sha256=jkYZa12RWgXlDzfPVHA6x3Jh0x52SnkVbVD2SpRUOtU,690
-weakincentives/serde/dataclass_serde.py,sha256=9ZYYGyl0PCRLweYx9XQk8vKKLiSiY_3mf_P7BmsCxOE,37327
+weakincentives/serde/dataclass_serde.py,sha256=07mJQj08cbaTsrcZ5xvtjlLxzVkUGirHl1k74jPAFQI,37881
 weakincentives/session/__init__.py,sha256=f-JN93x4VXzGJd1oontyZuaRJ1wSN80MQ6qduNG-3ss,1000
 weakincentives/session/reducers.py,sha256=_Wi8brUaGhT9jxfCychu59T_6jo3tvYp5JkhWpSb5ts,1944
 weakincentives/session/selectors.py,sha256=uLYfhVF8ot8W03BQtmj7AzLltrdZ_VAsRsn31gQfWUk,1427
-weakincentives/session/session.py,sha256=RnLG9KRXdpj3PRVlXwTa501qNdUzeTaXc5s2G4hLlL8,5782
-weakincentives/tools/__init__.py,sha256=B5U8Ujh4--3CwssNSUApkC5KCn5z_NqbHR2w_jdgcyc,1524
+weakincentives/session/session.py,sha256=jXPq-zQkmUnH6VeKcYxQPVY-Yt9VjV4r_lK3swxvFtQ,5987
+weakincentives/tools/__init__.py,sha256=2MabNTtfvAiZGzQcGA7i_XNj9UqDW9-X7IWoDzVpdVE,1737
+weakincentives/tools/asteval.py,sha256=RwhHLAifA0ZWmMZBtrJQRQFOnh9FEamY-4ztaEK7UBw,25107
 weakincentives/tools/errors.py,sha256=cHD_78WEpwzVjtuiSGtEyMy8u-n-1k0I95fEBoMngbI,765
 weakincentives/tools/planning.py,sha256=qlxulLZgLlt_7eFI4Psb8IGNaea4N6uR_ijch1f7Jc4,17023
-weakincentives/tools/vfs.py,sha256=3u9v3CDkqcKmuNFId8Bov00Mb5IxcJvH9mb5yTE2zo4,20582
-weakincentives-0.3.0.dist-info/METADATA,sha256=jfUtPG9WpJcyXTwU3jeJ51uzC37C4dfpuVx3TGha9rs,6965
-weakincentives-0.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-weakincentives-0.3.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-weakincentives-0.3.0.dist-info/RECORD,,
+weakincentives/tools/vfs.py,sha256=-3hIs5YOM1T_Lmi0UUULejce83oomM_EZDc5Gnua1SI,20615
+weakincentives-0.4.0.dist-info/METADATA,sha256=NMd3oDspblHXanLHAWH7vzoH-ZYeciG7DXTqIBgsF3A,14728
+weakincentives-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+weakincentives-0.4.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+weakincentives-0.4.0.dist-info/RECORD,,