bbagents 0.1.0__tar.gz

bbagents-0.1.0/GUIDE.md

@@ -0,0 +1,210 @@
+# BrilBerry Agents (`bbagents`)
+
+BrilBerry Agents is a provider-neutral reference toolkit for modeling and enforcing
+the plans, policies, memory, learning, and organizational structure of agent systems.
+It can run independently or complement orchestration frameworks such as LangGraph
+and integration frameworks such as LangChain.
+
+The package turns the conceptual Python examples from *Agent Engineering* into
+small, typed, executable components. It deliberately has no model-provider or
+storage dependency.
+
+The package is an alpha reference implementation. Its stable boundary is the set of
+typed values and protocols; production applications should supply their own model,
+storage, sandbox, and telemetry adapters.
+
+## Install for development
+
+```console
+python -m pip install -e '.[dev]'
+pytest
+```
+
+Python 3.11 or newer is required.
+
+## Where it fits
+
+`bbagents` is not intended to replace LangChain or LangGraph. LangChain supplies a
+broad ecosystem of model, tool, retriever, and provider integrations. LangGraph
+supplies durable, stateful orchestration, checkpointing, streaming, and
+human-in-the-loop execution. `bbagents` supplies the application-level plans,
+policies, bounded context, versioned state, memory records, learning procedures,
+roles, and governance rules that can run inside those systems.
+
+These primitives can be composed into an application-specific **agent harness**:
+the layer that assembles context, constrains actions, applies policy, and captures
+feedback around a model. `bbagents` does not impose a universal harness or own the
+outer execution loop; applications and orchestration frameworks retain that role.
+
+The [manuscript alignment audit](MANUSCRIPT_ALIGNMENT.md) maps the current book to
+implemented contracts and records production concerns still owned by applications.
+
+For small deterministic workflows, the package can run by itself. In a larger
+application, LangGraph can own the outer execution loop while graph nodes use
+`bbagents` primitives. LangChain models and tools can be connected through narrow
+adapters without making them required dependencies.
+
+## Minimal example
+
+```python
+from bbagents import AgentState, FunctionTool, Observation, Plan, PlanStep, ToolCall, ToolRegistry
+from bbagents.observability import InMemoryTrace
+from bbagents.reference import PlanningAgent
+
+tools = ToolRegistry([
+    FunctionTool(
+        "inspect",
+        "Inspect a named component",
+        lambda component: Observation("inspect", f"inspected {component}"),
+    )
+])
+
+state = AgentState("Inspect authentication", Plan(
+    "Inspect authentication",
+    [PlanStep("inspect", "Inspect authentication")],
+))
+
+agent = PlanningAgent(
+    tools,
+    lambda state, step: [ToolCall("inspect", {"component": "authentication"})],
+    trace=InMemoryTrace(),
+)
+agent.run(state)
+assert state.completed
+```
+
+The root namespace is intentionally limited to the common planning, action, tool,
+and decision contracts. Import specialised components from their module, such as
+`bbagents.intervention`, `bbagents.models`, `bbagents.safety`, or
+`bbagents.observability`.
+
+## Examples
+
+Runnable examples include:
+
+- [`langgraph_integration.py`](examples/langgraph_integration.py), which lets
+  LangGraph own orchestration and checkpointing while graph nodes use `bbagents`;
+- [`langgraph_intervention.py`](examples/langgraph_intervention.py), which pauses a
+  governed action through LangGraph and resumes it with a typed human response;
+- [`coding_organization.py`](examples/coding_organization.py), which coordinates
+  persistent roles under ownership, dependency, and governance rules;
+- [`dependency_vulnerability_audit.py`](examples/dependency_vulnerability_audit.py),
+  which turns repository and advisory evidence into verified remediation steps;
+- [`model_routing_and_cache.py`](examples/model_routing_and_cache.py), which routes
+  workloads under quality and latency constraints and caches stable results;
+- [`secure_deployment.py`](examples/secure_deployment.py), which separates action
+  proposals, capabilities, approval, and side effects;
+- [`repository_constraint_learning.py`](examples/repository_constraint_learning.py),
+  which separates retained experience from validated behavioral change;
+- [`oauth_migration_planner.py`](examples/oauth_migration_planner.py), which
+  demonstrates dependent planning, evidence accumulation, and tracing;
+- [`langchain_integration.py`](examples/langchain_integration.py), which adapts
+  LangChain models and tools without transferring ownership of the agent loop.
+- [`langfuse_tracing.py`](examples/langfuse_tracing.py), which runs locally by
+  default and publishes nested traces to Langfuse when configured;
+- [`langsmith_tracing.py`](examples/langsmith_tracing.py), which publishes the
+  same trace hierarchy to LangSmith as an alternative integration.
+
+The [`examples/README.md`](examples/README.md) explains the goals and architectural
+boundaries of each example.
+
+## Modules and manuscript provenance
+
+| Module | Adapted concepts |
+|---|---|
+| `core` | Provider-neutral models and observations (Chapters 6–8) |
+| `tools` | Tool schemas, registries, and deterministic invocation (Chapter 4) |
+| `planning` | Explicit plans, dependencies, execution, and traces (Chapter 7) |
+| `runtime` | First-class actions, policy checks, results, and retries (Chapter 8) |
+| `decision` | Structured model proposals with bounded context, validation, and traces (Chapters 2, 5, 7) |
+| `skills` | Versioned authored guidance, progressive discovery/loading, and provenance (Chapters 3, 8, 13) |
+| `evaluation` | Separate response, transcript, and environment evidence; graders and repeated-trial reports (Chapter 5) |
+| `models` | Role-scoped heterogeneous model selection and independent review (Chapters 6, 12) |
+| `intervention` | Human-intervention requests, explicit delegation, and action gating (Chapters 8, 13) |
+| `context` | Budgeted context views, state projection, and summarization contracts (Chapters 2, 3, 9) |
+| `retrieval` | Provider-neutral evidence retrieval and context augmentation (Chapter 3) |
+| `memory` | Episodic/semantic/procedural records and retrieval (Chapter 9) |
+| `learning` | Experience, generalization, validation, and promotion (Chapter 10) |
+| `organization` | Roles, messages, delegation, and governance (Chapters 6, 11) |
+| `optimization` | Model cost estimates, routing constraints, and caching (Chapter 12) |
+| `safety` | Trust, capabilities, approvals, and audit decisions (Chapter 13) |
+| `observability` | Structured traces and evaluations (Chapter 5) |
+| `persistence` | Versioned state snapshots and optimistic concurrency contracts (Chapters 8-11) |
+
+## Adaptation policy
+
+The manuscript contains more than 120 Python fences. Many are pseudocode fragments,
+provider examples, alternative versions of the same class, or deliberately incomplete
+interfaces. The library does not concatenate them. It makes these adaptations:
+
+- Repeated names such as `Action`, `Runtime`, `MemoryManager`, and `Policy` are merged
+  into one responsibility-specific implementation.
+- Values shared between chapters use a single canonical definition.
+- Model-generated planning is represented by injected callables. This keeps model
+  providers optional and leaves the deterministic loop testable.
+- Model calls can use `DecisionRuntime`: applications adapt their provider to the
+  `LanguageModel` or `DecisionModel` protocol while the library applies explicit
+  output schemas, bounded context, validation, retries, and traces. Provider
+  adapters may return model identity, token usage, and request metadata.
+- `ModelCatalog` and `ModelSelector` make heterogeneous routing explicit. The
+  optimization module retains a small compatibility wrapper but does not own a
+  second routing policy.
+- Agent profiles name their permitted model identities. Applications retain control
+  of the selection policy, and can exclude a generator's model when assigning an
+  independent reviewer.
+- Authored skills use `SkillDescriptor`, `Skill`, and the application-implemented
+  `SkillSource` protocol. Discovery can expose descriptions before loading an exact
+  version. Resource references remain opaque and required tools confer no authority.
+- Evaluation uses `TrialEvidence` to keep answers, transcripts, and environment
+  outcomes separate. Applications provide graders and isolated trial execution;
+  `report_trials` distinguishes observed any-success and all-success counts without
+  assuming independent runs. Missing evidence is distinct from failure or success.
+- Context summaries retain their original `summary_sources` for provenance and
+  review. Only `Context.content` is rendered to the model by the decision adapter.
+- Storage examples include in-memory state and an optional JSON file-backed state
+  store. Corrupt or incompatible state files are treated as absent checkpoints;
+  vector databases, embeddings, and production stores remain adapters.
+- Context selection, state persistence, and policy evaluation have explicit typed
+  contracts. Applications retain ownership of domain state, storage encoding,
+  summaries, and policy semantics.
+- Human intervention is represented as typed, expiring requests, versioned
+  responses, explicit delegation, and action-runtime pending states. Identity
+  verification, UI, notification, and workflow suspension remain application
+  adapters.
+- State, intervention, and memory records use stable identity and optimistic
+  concurrency. Applications retain ownership of database choice and encoding.
+- Trace events carry portable run/span context and can be redacted before delivery
+  to in-memory or external tracing backends. Langfuse and LangSmith remain optional
+  adapters rather than framework dependencies.
+- `Provenance` labels observations, memory, retrieved evidence, context, and
+  intervention requests with a source identity and trust level. Applications decide
+  how those labels affect their policies.
+- The optional `bbagents[langgraph]` integration maps a stored intervention request
+  to LangGraph's durable interrupt and resume flow without requiring applications to
+  encode or validate intervention payloads themselves.
+- Retrieval is a narrow evidence-to-context boundary. Applications supply document
+  loading, chunking, embeddings, vector stores, rerankers, and orchestration.
+- Browser, computer-use, shell, filesystem, LangGraph, and vendor SDK examples are
+  omitted because they require external runtimes or create unsafe defaults.
+- Prompt strings and chapter-specific OAuth/coding-agent examples remain examples,
+  not library behavior.
+- Optimization and organizational data models are included, while speculative
+  scheduling and distributed execution are left to application runtimes.
+
+## Design constraints
+
+The [implementation notes](IMPLEMENTATION.md) describe production contracts and
+migration from the original synchronous reference runtimes. New modules cover
+transactional persistence, bounded execution, effect recovery, task lifecycle,
+governed memory/skills/procedure promotion, and isolated evaluation experiments.
+The root API stays small; import these features from their responsibility modules.
+
+- Standard library only at runtime.
+- Default-deny capability policy when safety controls are used.
+- Deterministic code owns loops, retries, policy checks, and state transitions.
+- Probabilistic model behavior enters through narrow injected interfaces.
+- No hidden global registries or network calls.
+- No orchestration, checkpointing, or hosted tracing runtime: applications may use
+  LangGraph, Langfuse, LangSmith, or another platform directly. The default tracing
+  example runs locally and exports to Langfuse when configured; optional Langfuse
+  and LangSmith adapters translate planning events into nested hosted traces.

bbagents-0.1.0/IMPLEMENTATION.md

@@ -0,0 +1,61 @@
+# Production contract implementation
+
+Each phase is tested, committed, and pushed before the next phase starts.
+
+1. Persistence: implemented SQLite transactional checkpoints and failure-safe file
+   replacement. FileStateStore remains a single-writer reference backend.
+2. Deadlines and retries: implemented cooperative async deadlines, allowlisted
+   subprocess cancellation, typed failures and conservative retry policy.
+3. Recovery and idempotency: implemented durable intent, action/state binding,
+   leases, reconciliation, confirmed result reuse, and current-policy checks.
+4. Task lifecycle and enforcement: implemented persisted acceptance/progress state,
+   evidence completion policy, measured budgets, and bounded traced hooks.
+5. Skills, memory, and learning governance: implemented reviewed filesystem skills,
+   scope-bound access before ranking, revision history, promotion and rollback.
+6. Evaluation execution and compaction checks: implemented versioned datasets,
+   isolated fixture lifecycle, configuration binding, calibration records, empirical
+   variability, opt-in Wilson intervals and structured continuation probes.
+7. Cross-domain demonstrations: implemented durable release and pandemic-response
+   fixtures using shared approval, execution journal and completion contracts.
+   Added optional Ollama decisions and offline transport tests.
+
+## Migration notes
+
+- Existing StateStore implementations and call sites remain valid. Use
+  `SQLiteStateStore` for concurrent local checkpoint updates. JSON codecs work as
+  with FileStateStore; database corruption is surfaced rather than reset silently.
+- Run `PYTHONPATH=src python examples/durable_checkpoints.py` for a restart and
+  stale-writer example.
+- Use `execution.AsyncActionRuntime` for bounded execution. Cancellation is
+  cooperative for Python handlers and propagates to the caller; subprocess children
+  are killed and reaped. Neither guarantees reversal of external effects. Legacy
+  synchronous ActionRuntime remains available and does not enforce deadlines.
+- `SafeRetryPolicy` retries confirmed transient failures only when `retry_safe`
+  is explicitly set. An idempotency key alone does not prove a provider honors it.
+- `RecoverableActionRuntime` requires stable execution IDs and JSON-compatible
+  action metadata/results. Uncertain outcomes and expired leases require an
+  application reconciler. A NOT_EXECUTED answer must rule out a late side effect;
+  the journal cannot discover this on its own. It never promises exactly-once.
+- TaskLifecycle persists progress but does not schedule work. Hosts measure/report
+  time and spend and check budgets before dispatch. Domain completion rules implement
+  CompletionPolicy. HookRunner exposes before-model/action/result/completion boundaries;
+  AsyncActionRuntime wires action/result hooks and TaskLifecycle wires completion.
+  Only observational after-result hooks may fail open. Callbacks must honor cancellation.
+- Install `[skills]` for YAML parsing. FilesystemSkillSource accepts a trusted
+  digest manifest and policy; discovery is lazy and resources need separate access.
+  It never executes scripts. Keep manifests outside agent-writable storage.
+- RevisionRepository binds trusted identity/scope and retains candidate/activation
+  history. ScopedMemoryStore ranks only authorized scoped items. ProcedurePromoter
+  requires validation evidence; rejected proposals never replace the active version.
+  Use separate namespaces for memory and procedures. The reference aggregate is
+  intended for small local stores, not large distributed corpora.
+- run_dataset requires a fresh context-managed environment per trial; hosts provide
+  actual isolation/reset. Runner identity/configuration mismatches fail loudly after
+  cleanup. Held-out cases are excluded by default. success_interval returns nothing
+  unless independent Bernoulli trials are explicitly justified; repeated task runs
+  are often correlated. CompactionGrader consumes observed continuation behavior,
+  not the summary's claims about itself.
+- StateInterventionStore preserves approval lifecycle over StateStore; approved
+  requests can be revoked or expire after restart. Release publication remains a
+  simulated transactional index. `--model NAME` opts into an installed Ollama model;
+  no model download or real publication occurs implicitly.

bbagents-0.1.0/INVENTORY.md

@@ -0,0 +1,75 @@
+# Manuscript snippet inventory
+
+The current manuscript contains 102 Python code fences (audited 2026-10-21).
+Chapter-local sketches are adapted into portable contracts rather than copied
+verbatim. See [MANUSCRIPT_ALIGNMENT.md](MANUSCRIPT_ALIGNMENT.md) for the current
+coverage and explicit production limitations.
+
+| Chapter | Fences | Library disposition |
+|---|---:|---|
+| 2 - Models | 2 | `core`, `decision`; provider-neutral proposal boundary |
+| 3 - Retrieval | 2 | `retrieval`, `context`; progressive loading and summary provenance |
+| 4 — Tools | 20 | `tools`; vendor-specific calling loops omitted |
+| 5 — Observability | 6 | `observability`, `evaluation`; optional Langfuse and LangSmith trace adapters included |
+| 6 — Multi-agent systems | 8 | `core`, `models`, `organization`; application-owned coordination |
+| 7 — Planning | 4 | `planning`; provider prompts and LangGraph wiring remain application code |
+| 8 — Harnesses and runtimes | 16 | `runtime`, `safety`, `skills`; application harness composes contracts |
+| 9 — Memory | 14 | `memory`; external vector and embedding providers represented by injection points |
+| 10 — Learning | 8 | `learning`; model-driven generalization represented by an injected callable |
+| 11 — Organizations | 6 | `organization`; domain-specific department examples omitted |
+| 12 — Optimization | 7 | `models`, `optimization`; speculative/distributed schedulers omitted |
+| 13 — Safety | 9 | `safety`; OS sandbox implementation and incident integrations omitted |
+| 14 — Languages | 0 | Architectural discussion; no language runtime |
+
+## Reconciled definitions
+
+- Chapter-local `Observation` definitions became `core.Observation`; memory safety uses
+  the separate and more specific `memory.MemoryRecord`.
+- Tool calls and registries from Chapters 4 and 7 became `tools.ToolCall` and
+  `tools.ToolRegistry`.
+- The several `Action` and `Runtime` sketches in Chapter 8 became `runtime.Action`,
+  `runtime.ActionResult`, and `runtime.ActionRuntime`.
+- The abstract and concrete memory-manager sketches became `memory.MemoryStore`, a
+  deliberately small reference backend with replaceable embedding behavior.
+- Repeated `Generalizer`, `Validator`, and `LearningRuntime` sketches became generic
+  callables plus `learning.LearningRuntime`.
+- Context-window and stateful-execution concepts are represented by `context`:
+  applications project their own state while the library applies a budget and an
+  optional injected summarizer.
+- The language-model decision boundary is represented by `decision`: a provider
+  adapter receives a typed task and bounded context, while validation and tracing
+  remain deterministic runtime behavior.
+- Chapter 6 heterogeneous specialization is represented by `models`: organizational
+  agent profiles constrain model identity, while application policies select from
+  those models and can require reviewer independence.
+- Runtime and safety concepts also include `intervention`: applications supply an
+  authenticated human interface and identity resolver while the library preserves
+  portable requests, responses, delegation, and pending action state.
+- Chapter 3 retrieval concepts are represented by `retrieval.Retriever` and
+  `RetrievalAugmenter`, which normalize evidence and pass it through the shared
+  context budget without selecting a document store or embedding provider.
+- Durable execution boundaries are represented by `persistence.StateStore` and its
+  versioned `StateSnapshot`; production encodings and backends remain application
+  adapters.
+- Policy decisions have a generic, contextual `safety.Policy` protocol; the existing
+  capability policy remains the action-runtime implementation.
+- Trace events carry portable run and span correlation identifiers without coupling
+  the package to a trace backend.
+- Chapter 11 and Chapter 13 both define `Policy`; these were separated into
+  `organization.GovernancePolicy` and `safety.CapabilityPolicy` because they enforce
+  different boundaries.
+
+## Deliberate omissions
+
+The seven production-contract phases now add `execution`, `recovery`, `hooks`,
+`lifecycle`, `revisions`, `governed_memory`, `promotion`, `experiments`, and
+`compaction`, plus filesystem-skill and local Ollama adapters. The implementation
+and migration details are in [IMPLEMENTATION.md](IMPLEMENTATION.md). These are
+portable adaptations, not new chapter-local snippets or a separate orchestrator.
+
+The following snippets are educational integration examples rather than portable
+library code: OpenAI/Anthropic/LangGraph calls, shell and repository mutation, browser
+and computer use, deployment commands, concrete vector databases, distributed
+coordination, and chapter-specific case studies. Including them would introduce
+vendor coupling, unsafe defaults, or false production guarantees. The package exposes
+interfaces where applications can add those integrations explicitly.

bbagents-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 BrilBerry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

bbagents-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include GUIDE.md INVENTORY.md MANUSCRIPT_ALIGNMENT.md IMPLEMENTATION.md
+include RELEASING.md
+recursive-include examples *.py *.md
+recursive-include demos *.py *.md
+recursive-include tests *.py

bbagents-0.1.0/MANUSCRIPT_ALIGNMENT.md

@@ -0,0 +1,61 @@
+# Manuscript alignment audit
+
+Audited against the local manuscript on 2026-10-21, including the harness, skills,
+and evaluation revision in `c7c1bd8`. Subsequent chapter changes through `2f8c240`
+predominantly concern figure formats and print presentation. Chapter-local Python
+sketches illustrate architecture; the package does not promise identical classes
+or production implementations of every sketch.
+
+| Book concepts | Library support and disposition |
+|---|---|
+| Chapters 1-2: model/runtime separation | `core`, `decision`, `runtime`: typed proposals, schema validation, policy-controlled effects. |
+| Chapter 3: retrieval, progressive loading, compaction | `retrieval`, `context`, `skills`: bounded assembly, attributable evidence, lazy skill-source protocol. Summaries retain source items separately from model-facing text. |
+| Chapter 4: tools and protocols | `tools`: injectable deterministic invocation; provider APIs, MCP connections, and code-execution sandboxes remain adapters. |
+| Chapter 5: observable execution and evaluation | `observability` plus optional tracing adapters; `evaluation` records configuration, response, transcript, actual outcome, duration, and cost. Graders can return insufficient evidence. Repeated-trial reporting separates any success from all successes. |
+| Chapter 6: heterogeneous specialization | `models` catalog/selector, role-scoped candidates, independent reviewer exclusion; application owns coordination. |
+| Chapter 7: explicit plans | `planning`: dependencies, cycle rejection, evidence, one-step executor; `reference` supplies the local synchronous runner. |
+| Chapter 8: harness composition and skills | Existing primitives compose into application harnesses. `skills` adds version, owner, scope, provenance, resource references, and discovery/loading contracts. No universal harness or second graph scheduler is added. |
+| Chapter 9: memory | `memory`, `governed_memory`, `revisions`, `provenance`, `persistence`: scoped access, versioned records, retrieval, checkpoints, history and rollback. Domain consolidation remains application-defined. |
+| Chapter 10: runtime learning | `learning` and `promotion`: generalization, validation, versioned promotion evidence, activation history and rollback. Applications supply evaluation and promotion authority. |
+| Chapter 11: organizations | `organization`, `safety`, `intervention`: typed roles, messages, governance and delegated approval; transport and scheduling remain adapters. |
+| Chapter 12: optimization | `models`, `optimization`, `context`: selection constraints, caching, context budget. Distributed scheduling and speculative execution remain outside the library. |
+| Chapter 13: safety | Capabilities, intervention fingerprints/expiry, provenance, trace redaction. Skills remain guidance and do not grant tool authority. Authentication, tenant isolation, OS restrictions, and configuration review must be supplied by the host. |
+| Chapter 14: languages | Discussion and illustrative syntax; no language implementation is implied. |
+
+## Remaining implementation boundaries
+
+The seven implementation phases are complete; see [IMPLEMENTATION.md](IMPLEMENTATION.md).
+The following deployment responsibilities and reference-backend limitations remain:
+
+- AsyncActionRuntime enforces cooperative deadlines; SubprocessAdapter kills and
+  reaps direct child processes. The legacy synchronous dispatcher does not enforce
+  deadlines. External side effects and descendants require application controls;
+  timeouts produce uncertain outcomes that must be reconciled before replay.
+- ExecutionJournal and RecoverableActionRuntime now persist intent and confirmed
+  results, bind action/state fingerprints, protect live claims, and recheck current
+  authorization. Reconciler implementations establish external status; an unknown
+  result blocks replay, and no exactly-once guarantee is inferred from a journal.
+- TaskLifecycle now persists task progress, acceptance evidence and measured budgets.
+  HookRunner provides bounded traced boundaries; application/orchestrator code owns
+  scheduling, budget measurement and recovery against the actual environment.
+- FilesystemSkillSource parses reviewed SKILL.md files with optional PyYAML, verifies
+  scope, digest and path containment, and authorizes resources separately. Hosts
+  supply trusted manifests and identity; scripts remain subject to execution policy.
+- Dataset trials now have isolated fixture lifecycle, held-out selection, configuration
+  checks, calibration reports and empirical variability. Wilson intervals require
+  an explicit independence assumption. Hosts still implement environment isolation
+  and supply representative datasets, human labels and domain graders. Unknown
+  grades count as trials without demonstrated success in the empirical rate.
+- ScopedMemoryStore and RevisionRepository enforce host-defined access before
+  ranking and retain revision/activation history. ProcedurePromoter records validation
+  and rollback. Provenance labels still require trustworthy host assignment;
+  source records alone cannot prove summary fidelity.
+- SQLiteStateStore now supplies transactional version checks across competing
+  writers. FileStateStore uses unique temporary files and failure cleanup, but
+  remains a single-writer reference backend.
+
+These boundaries apply to both the release-manager and pandemic-response fixture.
+The release demo persists approvals/state and reconciles its simulated index.
+Release-note generation is deterministic by default; `--model` opts into an installed
+local Ollama model. The adapter is tested with an offline transport; a live model
+service and real package-index publication are not required or exercised by CI.

bbagents-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: bbagents
+Version: 0.1.0
+Summary: Provider-neutral building blocks for reliable AI agents
+Author: BrilBerry
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Brilberry/bbagents
+Project-URL: Book, https://press.brilberry.com
+Keywords: agents,ai,planning,tools,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Provides-Extra: langchain
+Requires-Dist: langchain-core<2.0,>=1.0; extra == "langchain"
+Provides-Extra: langgraph
+Requires-Dist: langgraph<2.0,>=1.0; extra == "langgraph"
+Provides-Extra: langfuse
+Requires-Dist: langfuse>=4.0; extra == "langfuse"
+Provides-Extra: langsmith
+Requires-Dist: langsmith>=0.1.95; extra == "langsmith"
+Provides-Extra: skills
+Requires-Dist: PyYAML<7,>=6; extra == "skills"
+Dynamic: license-file
+
+# bbagents
+
+Python building blocks for agent systems: tools, planning, model selection, memory,
+human approval, tracing, and evaluation. Works with LangGraph or your own runtime.
+
+Companion code for *Agentic AI: Architecture, Theory, and Practice*.
+[Buy the book](https://press.brilberry.com).
+
+<a href="https://press.brilberry.com">
+  <img src="assets/book-cover.png" alt="Agentic AI: Architecture, Theory, and Practice by Marco Dinacci" width="240" height="360">
+</a>
+
+Requires Python 3.11+.
+
+```sh
+pip install -e '.[dev]'
+pytest
+```
+
+## Complete application example
+
+[Agent Stranded](https://github.com/Brilberry/agentstranded) is a more complete
+example: an autonomous survival game using bbagents planning, tools, memory,
+skills, communication, and tracing, with an optional local LLM. Its code,
+documentation, and run instructions live in that separate repository.
+
+## Features
+
+The previous README's approval/recovery example is preserved as
+[recoverable_release.py](examples/recoverable_release.py).
+
+- Typed tools, dependency-checked plans, structured model decisions and validation.
+- Per-agent model selection, routing constraints, cost estimates and caching.
+- Capability policies, human intervention, explicit delegation and LangGraph interrupts.
+- Bounded async execution, retry policies, execution journals and effect reconciliation.
+- Versioned checkpoints, SQLite persistence, task budgets and completion gates.
+- Budgeted context, summarization contracts and provider-neutral retrieval (RAG).
+- Scoped, revisioned memory and skills; evaluated and approved procedure promotion.
+- Roles, messages, delegation and organizational governance.
+- Structured traces, isolated evaluation trials and compaction-continuation checks.
+- Optional Ollama, LangChain, LangGraph, LangSmith and Langfuse integrations.
+
+No mandatory runtime dependencies. Applications own domain behavior and adapters.
+
+See [examples](examples/), [demos](demos/) and the [guide](GUIDE.md).
+
+Maintainers: see [release instructions](RELEASING.md) for publishing to PyPI.

bbagents-0.1.0/README.md

@@ -0,0 +1,47 @@
+# bbagents
+
+Python building blocks for agent systems: tools, planning, model selection, memory,
+human approval, tracing, and evaluation. Works with LangGraph or your own runtime.
+
+Companion code for *Agentic AI: Architecture, Theory, and Practice*.
+[Buy the book](https://press.brilberry.com).
+
+<a href="https://press.brilberry.com">
+  <img src="assets/book-cover.png" alt="Agentic AI: Architecture, Theory, and Practice by Marco Dinacci" width="240" height="360">
+</a>
+
+Requires Python 3.11+.
+
+```sh
+pip install -e '.[dev]'
+pytest
+```
+
+## Complete application example
+
+[Agent Stranded](https://github.com/Brilberry/agentstranded) is a more complete
+example: an autonomous survival game using bbagents planning, tools, memory,
+skills, communication, and tracing, with an optional local LLM. Its code,
+documentation, and run instructions live in that separate repository.
+
+## Features
+
+The previous README's approval/recovery example is preserved as
+[recoverable_release.py](examples/recoverable_release.py).
+
+- Typed tools, dependency-checked plans, structured model decisions and validation.
+- Per-agent model selection, routing constraints, cost estimates and caching.
+- Capability policies, human intervention, explicit delegation and LangGraph interrupts.
+- Bounded async execution, retry policies, execution journals and effect reconciliation.
+- Versioned checkpoints, SQLite persistence, task budgets and completion gates.
+- Budgeted context, summarization contracts and provider-neutral retrieval (RAG).
+- Scoped, revisioned memory and skills; evaluated and approved procedure promotion.
+- Roles, messages, delegation and organizational governance.
+- Structured traces, isolated evaluation trials and compaction-continuation checks.
+- Optional Ollama, LangChain, LangGraph, LangSmith and Langfuse integrations.
+
+No mandatory runtime dependencies. Applications own domain behavior and adapters.
+
+See [examples](examples/), [demos](demos/) and the [guide](GUIDE.md).
+
+Maintainers: see [release instructions](RELEASING.md) for publishing to PyPI.

bbagents-0.1.0/RELEASING.md

@@ -0,0 +1,46 @@
+# Publishing bbagents
+
+The `publish.yml` workflow publishes to PyPI only when a GitHub release is
+published. Ordinary pushes, tags alone, and draft releases do not upload anything.
+
+## One-time configuration
+
+Configure PyPI Trusted Publishing for owner `Brilberry`, repository `bbagents`,
+workflow `publish.yml`, and GitHub environment `pypi`. Create that environment in
+GitHub settings; a required reviewer is recommended. No PyPI API token is needed.
+
+## Release
+
+1. Set the new version in `pyproject.toml`, commit, push, and check CI passes.
+2. Create a GitHub release targeting that commit with tag `vVERSION` (for example,
+   `v0.1.0` for the current version). Review its changes, then publish the release.
+3. Watch the **Publish to PyPI** workflow. Approve the `pypi` environment deployment
+   if required. It checks the tag/version, runs tests, lint and typing checks,
+   builds the wheel and source distribution, checks metadata, and smoke-tests the
+   installed wheel before uploading through Trusted Publishing.
+4. Verify https://pypi.org/project/bbagents/ and install in a fresh environment:
+
+   ```sh
+   python -m pip install bbagents==0.1.0
+   python -c "from bbagents import Plan, PlanStep"
+   ```
+
+Use a new version for each release: published distribution filenames cannot be
+reused. Do not attempt to replace a published release with different contents.
+GitHub prereleases also trigger publishing; use a PEP 440 prerelease version such
+as `0.2.0rc1` and tag `v0.2.0rc1` when that is intentional.
+
+## Local package checks (no upload)
+
+With the development environment activated:
+
+```sh
+python -m pip install build twine
+python -m build
+python -m twine check --strict dist/*
+```
+
+Build from a clean checkout/output directory so old distributions are not mixed
+into a new release. The CI job starts with an empty build directory.
+
+See [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/using-a-publisher/).