<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-01-31-1-vendor-spec-kitty-events/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-01-31-1-vendor-spec-kitty-events/</id>
  <title>Vendor spec-kitty-events Library Instead of External PyPI Dependency</title>
  <updated>2026-01-31T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-01-31-1-vendor-spec-kitty-events/"/>
  <summary>Vendors the events library into the CLI because PyPI refuses direct git dependencies, trading repository purity for a package that can actually be published.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;During the 0.13.20 release, PyPI rejected the package upload because &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; was specified as a direct Git dependency:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;toml&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#FFFFFF;--1:#984E4D&quot;&gt;&quot;spec-kitty-events @ git+ssh://git@github.com/Priivacy-ai/spec-kitty-events.git@fc332dda...&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;PyPI’s policy prohibits direct Git dependencies because:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;They cannot be resolved reliably by pip&lt;/li&gt;
&lt;li&gt;They may point to private repositories&lt;/li&gt;
&lt;li&gt;They lack proper semantic versioning&lt;/li&gt;
&lt;li&gt;They bypass PyPI’s security and trust mechanisms&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This blocked the release process, requiring an immediate decision on how to handle the &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; dependency.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Release urgency&lt;/strong&gt;: 0.13.20 needs to ship immediately with ADR-18 fixes&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Package complexity&lt;/strong&gt;: Maintaining two separate PyPI packages adds overhead&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Distribution simplicity&lt;/strong&gt;: Users prefer single &lt;code dir=&quot;auto&quot;&gt;pip install&lt;/code&gt; command&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Future extensibility&lt;/strong&gt;: Events library will be used extensively in future features&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Development workflow&lt;/strong&gt;: Events code is tightly coupled to spec-kitty internals&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;PyPI policy compliance&lt;/strong&gt;: Must eliminate Git dependencies to publish&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Publish spec-kitty-events as separate PyPI package&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Vendor spec-kitty-events into spec-kitty&lt;/strong&gt; (CHOSEN)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Make spec-kitty-events an optional dependency&lt;/strong&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; “Vendor spec-kitty-events into spec-kitty”, because it provides the simplest distribution model, eliminates the need to maintain two PyPI packages, and ensures all users get the events functionality without extra installation steps.&lt;/p&gt;
&lt;h3 id=&quot;implementation&quot;&gt;Implementation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Copied &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events/src/spec_kitty_events/&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;spec-kitty/src/specify_cli/spec_kitty_events/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Converted all imports to relative imports (&lt;code dir=&quot;auto&quot;&gt;.models&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.storage&lt;/code&gt;, etc.)&lt;/li&gt;
&lt;li&gt;Removed Git dependency from &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Added &lt;code dir=&quot;auto&quot;&gt;python-ulid&gt;=1.1.0&lt;/code&gt; dependency (required by events library)&lt;/li&gt;
&lt;li&gt;Updated &lt;code dir=&quot;auto&quot;&gt;adapter.py&lt;/code&gt; to import from vendored location: &lt;code dir=&quot;auto&quot;&gt;from specify_cli.spec_kitty_events import ...&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Single package distribution&lt;/strong&gt;: Users install one package (&lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt;), get all functionality&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No PyPI publishing overhead&lt;/strong&gt;: Don’t need to maintain, version, and publish two packages&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No dependency resolution issues&lt;/strong&gt;: Everything bundled together, no version conflicts&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Faster releases&lt;/strong&gt;: Changes to events code don’t require coordinated releases&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Simplified CI/CD&lt;/strong&gt;: One release workflow, one set of credentials&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Better for private development&lt;/strong&gt;: Can iterate on events without public API commitments&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Larger package size&lt;/strong&gt;: Adds ~30KB to distribution (negligible)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Tighter coupling&lt;/strong&gt;: Events library can’t be used independently by other projects&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Harder to extract later&lt;/strong&gt;: If we need to separate it, requires migration&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Duplicates pydantic dependency&lt;/strong&gt;: Both spec-kitty and events use pydantic (but same version range)&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Code organization&lt;/strong&gt;: Events code lives in &lt;code dir=&quot;auto&quot;&gt;specify_cli/spec_kitty_events/&lt;/code&gt; subdirectory&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Import paths change&lt;/strong&gt;: From &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;specify_cli.spec_kitty_events&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Version coupling&lt;/strong&gt;: Events version (0.1.0-alpha) now tied to spec-kitty version&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;Success metrics:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;✅ 0.13.20 published to PyPI without errors&lt;/li&gt;
&lt;li&gt;✅ All 1,886 tests passing in CI&lt;/li&gt;
&lt;li&gt;✅ &lt;code dir=&quot;auto&quot;&gt;pip install spec-kitty-cli&lt;/code&gt; works without additional setup&lt;/li&gt;
&lt;li&gt;✅ Events functionality works via adapter layer&lt;/li&gt;
&lt;li&gt;✅ No import errors from vendored module&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Confidence level: &lt;strong&gt;High&lt;/strong&gt; - This is standard practice for Python packages that include tightly-coupled utilities.&lt;/p&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;publish-spec-kitty-events-as-separate-pypi-package&quot;&gt;Publish spec-kitty-events as separate PyPI package&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Independent versioning - can release events updates without spec-kitty release&lt;/li&gt;
&lt;li&gt;Reusable by other projects - events library available to ecosystem&lt;/li&gt;
&lt;li&gt;Cleaner separation of concerns - clear API boundary between packages&lt;/li&gt;
&lt;li&gt;Smaller individual packages - users who don’t need events can skip it&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Doubled maintenance burden&lt;/strong&gt; - must maintain two PyPI projects, two release workflows, two sets of credentials&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Coordinated releases required&lt;/strong&gt; - breaking changes in events require synchronized releases&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;User friction&lt;/strong&gt; - two &lt;code dir=&quot;auto&quot;&gt;pip install&lt;/code&gt; commands or complex dependency specification&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Version compatibility complexity&lt;/strong&gt; - must document which spec-kitty versions work with which events versions&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CI/CD complexity&lt;/strong&gt; - need SSH deploy keys or publish events first for every CI run&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;vendor-spec-kitty-events-into-spec-kitty-chosen&quot;&gt;Vendor spec-kitty-events into spec-kitty (CHOSEN)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Single package distribution&lt;/strong&gt; - &lt;code dir=&quot;auto&quot;&gt;pip install spec-kitty-cli&lt;/code&gt; gets everything&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Simplified maintenance&lt;/strong&gt; - one release workflow, one version number&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No dependency resolution&lt;/strong&gt; - everything bundled, no version conflicts&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Faster iteration&lt;/strong&gt; - change events code without public API stability concerns&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Immediate PyPI compliance&lt;/strong&gt; - eliminates Git dependency issue&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Larger package size - adds ~30KB (negligible for modern systems)&lt;/li&gt;
&lt;li&gt;Not independently reusable - other projects can’t use events library&lt;/li&gt;
&lt;li&gt;Tighter coupling - events changes require spec-kitty release&lt;/li&gt;
&lt;li&gt;Harder to extract later - would require migration if we need separation&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;make-spec-kitty-events-an-optional-dependency&quot;&gt;Make spec-kitty-events an optional dependency&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Users can choose whether to install events functionality&lt;/li&gt;
&lt;li&gt;Keeps package size minimal for users who don’t need events&lt;/li&gt;
&lt;li&gt;Optional extras pattern (&lt;code dir=&quot;auto&quot;&gt;pip install spec-kitty-cli[events]&lt;/code&gt;) is standard&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Doesn’t solve PyPI issue&lt;/strong&gt; - optional dependencies still can’t be Git URLs&lt;/li&gt;
&lt;li&gt;Feature detection complexity - need runtime checks for events availability&lt;/li&gt;
&lt;li&gt;User confusion - “which features need events?” not obvious&lt;/li&gt;
&lt;li&gt;Testing complexity - must test both with and without events installed&lt;/li&gt;
&lt;li&gt;Documentation burden - must explain optional installation clearly&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Related Decisions:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Feature 025 (CLI Event Log Integration) - Introduced dependency on spec-kitty-events&lt;/li&gt;
&lt;li&gt;ADR-18 (Merged Single-Parent Dependency Detection) - Shipped in 0.13.20 alongside this change&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;References:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;PyPI Core Metadata Specification: &lt;a href=&quot;https://packaging.python.org/specifications/core-metadata&quot;&gt;https://packaging.python.org/specifications/core-metadata&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;PEP 440 (Version Identification): &lt;a href=&quot;https://peps.python.org/pep-0440/&quot;&gt;https://peps.python.org/pep-0440/&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Original spec-kitty-events repo: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty-events&quot;&gt;https://github.com/Priivacy-ai/spec-kitty-events&lt;/a&gt; (now archived/vendored)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Implementation:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Commits: 879d812d (vendor code), 0dcd7c0b (fix imports)&lt;/li&gt;
&lt;li&gt;Release: v0.13.20&lt;/li&gt;
&lt;li&gt;Files affected: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/spec_kitty_events/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/events/adapter.py&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Alternatives rejected:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Forking events library to separate PyPI package&lt;/li&gt;
&lt;li&gt;Using git submodules (still wouldn’t solve PyPI issue)&lt;/li&gt;
&lt;li&gt;Implementing events functionality directly in spec-kitty (duplicates mature code)&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
