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

weakincentives-0.3.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,35 @@
+weakincentives/__init__.py,sha256=MOVuBbGbGA2O_QS69wH8E17bkRc_fHQ2Z0MGD-79ngE,1092
+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/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_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/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/versioning.py,sha256=Ur0rLYvVvMuoGxOB-SzYIALMlK6IKbOvxJWf2HsE9lQ,4034
+weakincentives/serde/__init__.py,sha256=jkYZa12RWgXlDzfPVHA6x3Jh0x52SnkVbVD2SpRUOtU,690
+weakincentives/serde/dataclass_serde.py,sha256=9ZYYGyl0PCRLweYx9XQk8vKKLiSiY_3mf_P7BmsCxOE,37327
+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/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-0.2.0.dist-info/METADATA

@@ -1,173 +0,0 @@
-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.dist-info/RECORD

@@ -1,20 +0,0 @@
-weakincentives/__init__.py,sha256=2hDTwJS-d3T6LPBd2dNcZvv-OLLjb8RV5UzuqUg3S7c,615
-weakincentives/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-weakincentives/adapters/__init__.py,sha256=i4zRQQvL21f1up1NFSe9kk3U6E4Nxj3hYMkGHSc4xbE,923
-weakincentives/adapters/core.py,sha256=UDo-Em289TiBwj6dau0tbssoSecyDEaYWyI5POPECiM,2345
-weakincentives/adapters/openai.py,sha256=fDmh-V1_FO3tvvw68VJh9ggh-OW5Vl9HycwB7oSC6_w,12240
-weakincentives/prompts/__init__.py,sha256=SQWvYq1je_dH_H55Yo8SaOawKPoOtODkuAsbMwvrZOo,1273
-weakincentives/prompts/_types.py,sha256=y9-bB9Pt_bG-C0258UJ93oGq1zt-ktoutjAKkEsjSSk,904
-weakincentives/prompts/errors.py,sha256=DR3GN54oTnNARkto3mVbIuT6BwhijTP3onLpcB6jdq0,1664
-weakincentives/prompts/prompt.py,sha256=k9D3O00vJb1YN-jKKB7vtKUPrOtj3ux6JpbHgjcNnX4,17152
-weakincentives/prompts/response_format.py,sha256=1LyhgEy9pWrx0n0oiYDqPb69qPLeZY7W165C6DkjYrY,1723
-weakincentives/prompts/section.py,sha256=kvbtsk7cWr3cSh9GxoPpsPItwI1cwV0ZgLzxUulbefw,4240
-weakincentives/prompts/structured.py,sha256=sUyfMwYI7oHqbvISTf7OABUs4VFKKGBkl_7LD7qvcHo,4842
-weakincentives/prompts/text.py,sha256=KRliScmPigC45zHV-SotD9UZ2RdIspkwPTiVCCp8kd4,3118
-weakincentives/prompts/tool.py,sha256=uGOFW8F2cMs_RRODqsXl6BpVXXTI3rlfKeTG-AHW3YE,9051
-weakincentives/serde/__init__.py,sha256=oGOvoKTF2txToLZJ2sRAH9SC5myO_-GFKi1X9YHdQ6w,1270
-weakincentives/serde/dataclass_serde.py,sha256=g5fEq3ACq6xphB0yGxIB_gJAD2u4nUxhDEC9mOtOk1c,37886
-weakincentives-0.2.0.dist-info/METADATA,sha256=w1xpKkylT9qfaMjR5YxE00ux1yEX4bdQMzicO_kvyJc,5936
-weakincentives-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-weakincentives-0.2.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-weakincentives-0.2.0.dist-info/RECORD,,