docs+refactor: reposition README, add Weaver Stack block, unify naming (#102, #109, #106)#114
Merged
Merged
Conversation
Unify the package name users install with the name they import: the PyPI distribution is weaver-kernel, so the import package is now weaver_kernel. Also renames the AGENT_KERNEL_SECRET env var to WEAVER_KERNEL_SECRET. The GitHub repo slug (agent-kernel) is the only remaining outlier; it is addressed separately via a repo-settings rename (GitHub auto-redirects old URLs) plus a prominent repo<->package<->import explainer in the README. Mechanical rename only; no behavioral change. make ci green.
, #109, #106) #102 — lead the README with the unique capability-token + tamper-evident audit value; reframe the policy engine (vs AgentFence, #111) and context firewall (vs contextweaver, #110) with explicit boundary framing, and add a 'why agent-kernel and not contextweaver/AgentFence?' answer above the fold. #109 — add the standardized 'Part of the Weaver Stack' section with the shared request-path diagram and an explicit standalone-use / no-hard- sibling-dependency statement, cross-linking the deeper neighbor table. #106 — add a prominent repo<->package<->import explainer at the install step (also the PyPI long description), a '## Naming' section in docs/architecture.md documenting the unify-on-weaver decision, and both names in PyPI keywords. Docs/messaging only; make ci green.
There was a problem hiding this comment.
Pull request overview
This PR implements a repo-wide naming unification and docs repositioning: the Python import path is renamed from agent_kernel to weaver_kernel (and AGENT_KERNEL_SECRET → WEAVER_KERNEL_SECRET), while the README/docs are restructured to clarify agent-kernel’s unique role in the Weaver stack (capability-token authorization + tamper-evident audit) and its boundaries vs contextweaver and AgentFence.
Changes:
- Rename the import package to
weaver_kerneland update all code/tests/examples/docs accordingly (incl. env var rename). - Reposition README with a “Weaver Stack” block + naming explainer and update architecture/security docs to match.
- Refactor/split several runtime modules into smaller files (drivers/firewall/policy/kernel helpers) to keep module size within
AGENTS.mdlimits.
Reviewed changes
Copilot reviewed 71 out of 90 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_version.py | Updates version-consistency tests to import weaver_kernel. |
| tests/test_trace.py | Updates TraceStore/ActionTrace imports to weaver_kernel. |
| tests/test_tokens.py | Updates token tests, logging namespaces, and env var name. |
| tests/test_router.py | Updates router import to weaver_kernel. |
| tests/test_registry.py | Updates registry/model imports to weaver_kernel. |
| tests/test_redaction.py | Updates firewall redaction imports to weaver_kernel. |
| tests/test_public_api.py | Updates public API docstring/export checks for weaver_kernel. |
| tests/test_policy.py | Updates policy-related imports to weaver_kernel. |
| tests/test_otel.py | Updates OTel tests to new weaver_kernel.* span/metric names. |
| tests/test_models.py | Updates model imports to weaver_kernel. |
| tests/test_mcp_driver.py | Updates MCP driver tests and patch paths to weaver_kernel. |
| tests/test_logging.py | Updates logging tests to new weaver_kernel.* logger names. |
| tests/test_kernel.py | Updates kernel integration tests to weaver_kernel. |
| tests/test_handles.py | Updates handle-store tests to weaver_kernel. |
| tests/test_firewall.py | Updates firewall tests to weaver_kernel. |
| tests/test_firewall_stream.py | Updates streaming firewall tests to weaver_kernel. |
| tests/test_firewall_boundary.py | Updates firewall boundary tests to weaver_kernel. |
| tests/test_federation.py | Updates federation tests to weaver_kernel. |
| tests/test_federation_discovery.py | Updates discovery tests and internal import paths to weaver_kernel. |
| tests/test_evaluation_artifact_policy.py | Updates example-policy test to weaver_kernel. |
| tests/test_drivers.py | Updates driver tests and httpx patch paths to weaver_kernel. |
| tests/test_chainweaver_flow.py | Updates ChainWeaver flow test imports to weaver_kernel. |
| tests/test_adapters.py | Updates adapter tests and logger names to weaver_kernel. |
| tests/conftest.py | Updates shared fixtures to weaver_kernel. |
| src/weaver_kernel/trace.py | Updates TraceStore docstring references to weaver_kernel. |
| src/weaver_kernel/tokens.py | Renames env var usage/messages to WEAVER_KERNEL_SECRET. |
| src/weaver_kernel/search_index.py | Updates registry reference in search-index docstring. |
| src/weaver_kernel/router.py | Adds/refactors router protocol + StaticRouter implementation under weaver_kernel. |
| src/weaver_kernel/registry.py | Updates search-index module reference for new package path. |
| src/weaver_kernel/rate_limit.py | Extracts rate limiting into a dedicated module. |
| src/weaver_kernel/py.typed | Marks package as typed for type checkers. |
| src/weaver_kernel/policy.py | Updates docs/exports references to weaver_kernel protocols/engines. |
| src/weaver_kernel/policy_reasons.py | Updates docstring reference to weaver_kernel.PolicyDenied. |
| src/weaver_kernel/policy_dsl.py | Updates public API references to weaver_kernel imports. |
| src/weaver_kernel/policy_dsl_parser.py | Updates optional-dep import note to weaver_kernel. |
| src/weaver_kernel/policy_dsl_explain.py | Extracts declarative denial-explanation logic into a dedicated module. |
| src/weaver_kernel/otel.py | Renames span/metric namespaces from agent_kernel.* → weaver_kernel.*. |
| src/weaver_kernel/models.py | Updates cross-module docstrings to the new package path. |
| src/weaver_kernel/kernel/_stream.py | Updates logger name and docstring references to weaver_kernel. |
| src/weaver_kernel/kernel/_invoke.py | Updates logger name and docstring references to weaver_kernel. |
| src/weaver_kernel/kernel/_federation.py | Updates logger name to weaver_kernel.kernel. |
| src/weaver_kernel/kernel/_dry_run.py | Adds extracted dry-run result builder helper module. |
| src/weaver_kernel/kernel/init.py | Updates kernel package docstring references to weaver_kernel. |
| src/weaver_kernel/handles.py | Adds/refactors HandleStore implementation under weaver_kernel. |
| src/weaver_kernel/firewall/transform.py | Adds/refactors Firewall transform logic under weaver_kernel. |
| src/weaver_kernel/firewall/token_counting.py | Updates budget-manager docstring references to weaver_kernel. |
| src/weaver_kernel/firewall/summarize.py | Adds deterministic summarization helper for firewall. |
| src/weaver_kernel/firewall/redaction.py | Adds PII/secret redaction helpers for firewall. |
| src/weaver_kernel/firewall/budgets.py | Updates docstring references to weaver_kernel. |
| src/weaver_kernel/firewall/budget_manager.py | Updates docstring references to weaver_kernel. |
| src/weaver_kernel/firewall/init.py | Adds firewall subpackage exports for weaver_kernel. |
| src/weaver_kernel/federation.py | Updates docstrings/references to weaver_kernel paths. |
| src/weaver_kernel/federation_discovery.py | Adds federated discovery + signed-manifest support under weaver_kernel. |
| src/weaver_kernel/errors.py | Updates docstring references to weaver_kernel types/paths. |
| src/weaver_kernel/enums.py | Adds/refactors SafetyClass and SensitivityTag enums under weaver_kernel. |
| src/weaver_kernel/drivers/memory.py | Adds in-memory driver under weaver_kernel. |
| src/weaver_kernel/drivers/mcp.py | Adds/refactors MCP driver under weaver_kernel. |
| src/weaver_kernel/drivers/mcp_support.py | Adds internal MCP wiring helpers under weaver_kernel. |
| src/weaver_kernel/drivers/http.py | Adds/refactors HTTP driver under weaver_kernel. |
| src/weaver_kernel/drivers/base.py | Adds driver protocol + ExecutionContext under weaver_kernel. |
| src/weaver_kernel/drivers/init.py | Adds drivers subpackage exports under weaver_kernel. |
| src/weaver_kernel/adapters/openai.py | Updates adapter docstring references to weaver_kernel. |
| src/weaver_kernel/adapters/anthropic.py | Adds Anthropic adapter/middleware under weaver_kernel. |
| src/weaver_kernel/adapters/_base.py | Updates base adapter docstrings/exports to weaver_kernel. |
| src/weaver_kernel/adapters/init.py | Updates adapter package docstring references to weaver_kernel. |
| src/weaver_kernel/init.py | Updates top-level package docstring examples and version docstring note. |
| README.md | Repositions README (hero + Weaver Stack block + naming explainer + updated quickstart). |
| pyproject.toml | Updates wheel package path to src/weaver_kernel and expands keywords. |
| Makefile | Updates coverage target to --cov=weaver_kernel. |
| examples/tutorial.py | Updates imports/env var in tutorial example. |
| examples/repository_safety_check.py | Updates imports in repository safety example. |
| examples/readme_quickstart.py | Updates quickstart example to weaver_kernel + env var rename. |
| examples/http_driver_demo.py | Updates HTTP driver demo imports/env var. |
| examples/evaluation_artifact_policy.py | Updates imports in evaluation-policy example. |
| examples/contextweaver_policy_flow.py | Updates imports in contextweaver policy-flow example. |
| examples/chainweaver_flow.py | Updates imports and docstring references in chainweaver example. |
| examples/billing_demo.py | Updates imports/env var in billing demo. |
| examples/basic_cli.py | Updates imports/env var in CLI example. |
| docs/tutorial.md | Updates tutorial docs to weaver_kernel and env var rename. |
| docs/security.md | Updates secret env var name in security docs. |
| docs/integrations.md | Updates integration docs examples and OTel naming. |
| docs/federation.md | Updates federation docs links/imports to weaver_kernel. |
| docs/context_firewall.md | Updates firewall docs imports and OTel naming to weaver_kernel. |
| docs/capabilities.md | Updates declarative policy examples to weaver_kernel. |
| docs/architecture.md | Adds Naming section and updates agent_kernel references to weaver_kernel. |
| docs/agent-context/review-checklist.md | Updates version-source reference to src/weaver_kernel/__init__.py. |
| docs/agent-context/invariants.md | Updates secret env var name in invariants. |
| CHANGELOG.md | Documents the breaking rename and README/docs positioning changes. |
| AGENTS.md | Updates repo layout and security rule env var to WEAVER_KERNEL_SECRET. |
| .github/workflows/ci.yml | Updates coverage target and conformance-suite comment to weaver_kernel. |
The BREAKING rename note for agent_kernel -> weaver_kernel only listed the import path and AGENT_KERNEL_SECRET env var. The same rename also changes the OpenTelemetry span/metric/attribute names and the library's logger namespaces, which downstream dashboards, alerts, and log filters key on. Document those surfaces so the breaking entry is complete. https://claude.ai/code/session_018xSFiDamJm5UCuEUH8DvJW
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements the "README positioning & cross-project clarity" group from issue triage — #102, #109, #106 — in one PR (Mode B).
What changed
refactor: rename import package agent_kernel → weaver_kernel(#106)git mv src/agent_kernel → src/weaver_kernel; replaced theagent_kernelimport token across all 67 tracked files (src, tests, examples, docs,pyproject.toml,Makefile,.github/workflows/ci.yml).AGENT_KERNEL_SECRETenv var →WEAVER_KERNEL_SECRET(12 files).pyproject.toml: wheel package path →src/weaver_kernel; PyPI name staysweaver-kernel.docs: reposition README + Weaver Stack block + naming explainer(#102, #109, #106)AgentFencecoherence: consume the shared Policy + safety-class contract (weaver-spec#78 / agentfence#76) — write once, enforce embedded + at the edge #111, vscontextweavercoherence: adopt the canonical Frame seam (producer side) — resolve "two firewalls" with contextweaver#352 / weaver-spec#84 #110), and a "Why agent-kernel and not contextweaver/AgentFence?" section sits above the fold.weaver-stacktopic #109 — new standardized "Part of the Weaver Stack" section with the shared request-path diagram (contextweaver → ChainWeaver → agent-kernel → AgentFence) and an explicit standalone-use / no-hard-sibling-dependency statement; the existing neighbor table is kept and cross-linked.agent-kernel/weaver-kernel/agent_kernel) #106 — prominent repo↔package↔import callout at the install step (also the PyPI long description, sincereadme = "README.md"), a## Namingsection indocs/architecture.mddocumenting the unify-on-weaverdecision, and both names added to PyPIkeywords.Why
agent-kernel's README co-led four features (two of which overlap with siblings), used three different names for itself (agent-kernel/weaver-kernel/agent_kernel), and lacked the standardized stack block its siblings carry. These three issues share one implementation path — the top of the README + the names a user types — so they are cleaner together than apart. Since retro-compat was explicitly waived, #106 is resolved by a real unification (pip install weaver-kernel→import weaver_kernel) rather than only an explainer.How verified
make ci— green:ruff format --checkclean (76 files),ruff checkclean,mypy src/clean (41 files),pytest580 passed, 1 skipped, all 9 examples run.pytest tests/test_readme_quickstart.py— passes (the test re-extracts the README python block and executes it against the live API).grepconfirms 0 remainingagent_kernel/AGENT_KERNEL_SECRETtokens in tracked files.Tradeoffs / risks
import agent_kernelandAGENT_KERNEL_SECRETno longer work (intended; documented in CHANGELOG under### Changed). No alias was added because retro-compat was waived.agent-kernel— the one name I can't change from here. The README/docs document the optional repo-settings rename toweaver-kernel(GitHub redirects old URLs).Out of band (cannot be done via a file change)
weaver-stackGitHub topic (ecosystem: add the standardized "Part of the Weaver Stack" block +weaver-stacktopic #109) and the other discovery topics — repo-settings action.Scope notes
Limited to these three issues. Adjacent triage issues left as follow-ups: #107 (topics/registry submissions — mostly out-of-repo), #108 (marketing assets), #105 (large-scale federation hero example), #110/#111/#103/#104/#99/#94/#113.
Closes #102
Closes #109
Closes #106
https://claude.ai/code/session_014dNGiRyRUqDja2NtCyz2Yn
Generated by Claude Code