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

weakincentives-0.2.0.dist-info/METADATA

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

@@ -0,0 +1,20 @@
+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,,

weakincentives-0.1.0.dist-info/METADATA

@@ -1,21 +0,0 @@
-Metadata-Version: 2.4
-Name: weakincentives
-Version: 0.1.0
-Summary: Tools for developing and optimizing side effect free background agents
-Author-email: Andrei Savu <andrei@weakincentives.com>
-License-File: LICENSE
-Requires-Python: >=3.14
-Description-Content-Type: text/markdown
-
-# weakincentives
-Tools for developing and optimizing side effect free background agents
-
-## Setup
-
-```bash
-# Install dependencies
-uv sync
-
-# Install git hooks
-./install-hooks.sh
-```

weakincentives-0.1.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-weakincentives/__init__.py,sha256=-KKie-6SsxmXheAK6zrI6G1Ij75q7794xcUDj-eFImk,60
-weakincentives/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-weakincentives-0.1.0.dist-info/METADATA,sha256=nGxxU8A0gNEmH8689RvMfePDqfHhq714eMyqZzVTU2g,461
-weakincentives-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-weakincentives-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-weakincentives-0.1.0.dist-info/RECORD,,