metalworks 0.0.1__tar.gz

metalworks-0.0.1/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "lab2a",
+  "owner": {
+    "name": "Lab2A",
+    "email": "hello@lab2a.dev"
+  },
+  "description": "Lab2A plugins. metalworks: Reddit demand research and engagement from Claude Code.",
+  "plugins": [
+    {
+      "name": "metalworks",
+      "source": "./plugin",
+      "description": "Reddit demand reports, thread discovery, and gated reply drafting via the metalworks MCP server. Zero-key data tools plus key-gated pipelines.",
+      "repository": "https://github.com/Lab2A/metalworks",
+      "license": "MIT",
+      "keywords": ["reddit", "marketing", "research", "demand", "mcp"]
+    }
+  ]
+}

metalworks-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: test (py${{ matrix.python }}, ${{ matrix.extras }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+        extras: ["bare", "all"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv venv --clear
+      - name: Install (bare)
+        if: matrix.extras == 'bare'
+        run: uv pip install -e ".[dev]"
+      - name: Install (all extras)
+        if: matrix.extras == 'all'
+        run: uv pip install -e ".[all,dev]"
+      # Offline by default: pytest-socket blocks all network in CI tests.
+      - name: Test
+        run: uv run pytest -q
+      - name: Console script smoke
+        run: uv run metalworks version
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv venv --clear
+      # All extras so pyright resolves real provider SDK imports (crypto,
+      # supabase, etc.). Adapters keep SDK objects behind Any regardless, but
+      # the few real `from x import y` lines need x present to typecheck.
+      - run: uv pip install -e ".[all,dev]"
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pyright

metalworks-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: release
+
+# Tag vX.Y.Z -> build -> publish to PyPI via trusted publishing (OIDC).
+# Requires the PyPI project to have Lab2A/metalworks configured as a
+# trusted publisher for this workflow file.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

metalworks-0.0.1/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+/build/  # packaging output only — anchored so it never shadows src/metalworks/build/
+.venv/
+.python-version
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.coverage
+
+# Env / secrets — never committed
+.env
+.env.*
+!.env.example
+
+# OS
+.DS_Store
+
+# gstack local runtime state (browse daemon, tokens) — never committed
+.gstack/
+
+# Gate / scratch run artifacts (local evidence, not committed)
+.gate/

metalworks-0.0.1/CHANGELOG.md

@@ -0,0 +1,188 @@
+# Changelog
+
+All notable changes to metalworks are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims
+to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) once it
+reaches 1.0. Below 1.0, anything outside `metalworks.contract` and the MCP tool
+contracts may change in any release.
+
+## [Unreleased]
+
+Pre-release foundations. Nothing here is stable yet.
+
+### Added
+
+- **Contract** (`metalworks.contract`): Pydantic models for the research and
+  Reddit surfaces (`DemandReport`, `ResearchBrief`, `Opportunity`,
+  `RedditPost`, `RedditComment`, `SubredditIntel`, `InboxItem`,
+  `ComplianceVerdict`, `DiscoveryContext`, ...), plus a TypeScript-type +
+  JSON-schema generator with diff-gated snapshots.
+- **Protocols + adapters**: own versioned `ChatModel` / `GroundedChatModel` /
+  `SearchProvider` / `EmbeddingProvider` protocols with a structured-output
+  ladder, plus thin adapters over official SDKs behind extras
+  (`anthropic`, `openai`, `google`, `exa`, `tavily`). Google grounding converts
+  provider byte offsets to character offsets so non-ASCII provenance stays
+  correct.
+- **Stores**: typed repos (`CorpusRepo`, `BriefRepo`, `RunRepo`, `AccountRepo`,
+  `OpportunityRepo`, `InboxRepo`) with `MemoryStores` + `SqliteStores` in core
+  (hosted backends live downstream via the same protocols). `CorpusRepo` carries
+  a local vector memory — embeddings as float64 blobs + brute-force numpy cosine,
+  no new core dependency. New `ArtifactStore` protocol + files-first `FileStore`
+  for Tier-2 pillar artifacts. `TokenCipher` for OAuth tokens at rest. Public
+  conformance suite in `metalworks.testing`.
+- **Research vertical** (`metalworks.research`): brief planner, Arctic Shift
+  corpus reader (HF Parquet submissions + live API comments), hybrid triage,
+  clustered synthesis with exact-matched quotes, web research (grounded +
+  external), cross-stream triangulation, and `run_research` end to end.
+- **Reddit core** (`metalworks.reddit`): rate limiter (token bucket honoring
+  Reddit's headers), OAuth + posting on httpx with typed errors, search,
+  metrics, inbox classification, subreddit intel, and a deterministic
+  compliance gate.
+- **Project layer** (`.metalworks/`): a project is a directory like `.git`.
+  `metalworks init` creates it with a `project.json` manifest, a gitignored
+  `corpus.db` (corpus + embeddings), committed `runs/<id>/research.{md,json}`,
+  and an `artifacts/` tree. A casual `Metalworks().research(...)` with no project
+  present leaves zero footprint. Non-secret config lives in
+  `.metalworks/config.toml` (a legacy cwd `metalworks.toml` is still read).
+- **Evidence chain**: content-addressed stable ids on `QuoteCitation` /
+  `WebFinding` / `PriceEvidence`, a `metalworks.contract.evidence` module
+  (`EvidenceRef` / `EvidenceRecord`), and a `DemandReport.evidence` accessor —
+  the spine downstream pillars resolve grounded claims against.
+- **Embedding reuse**: the research pipeline persists corpus embeddings and
+  reuses them across runs (keyed on the embedding model identity), so a re-run on
+  the same corpus re-embeds only the query.
+- **Front door**: `Metalworks().research(question, subreddits=...)` returns a
+  frozen `Research` bundle, and the CLI gains `metalworks research run
+  --question "..."` (no `brief.json` round-trip for the common case).
+- **Vertex AI**: the Google chat + embedding adapters authenticate via Vertex
+  (Application Default Credentials) when `GOOGLE_GENAI_USE_VERTEXAI=true`
+  (`VERTEX_PROJECT_ID`/`GOOGLE_CLOUD_PROJECT` + `VERTEX_LOCATION`), not just an
+  API key — `build_genai_client` in `metalworks._genai_client`; provider
+  resolution routes to Google under Vertex even with no `GOOGLE_API_KEY`.
+- **Marketing site (Pillar E)**: `build_marketing_site(deps, report, positioning=None)
+  -> MarketingSite` + `render_site_html(site, report)` (`metalworks.research.site`).
+  Top 3 clusters by demand_score; one constrained LLM call assigns each a
+  SiteSection role and picks a VERBATIM fragment; the builder re-runs exact-match
+  against the cluster's real `QuoteCitation.text` and DROPS any section that
+  isn't a verbatim substring (no-quote-no-section). Connective copy ships
+  `provenance="connective"` with no refs and is gated claim-free. Hero = the
+  highest-distinct-author cluster. `render_site_html` emits one self-contained
+  `index.html` with a permalink footnote (+ `data-evidence`) per verbatim
+  section. New contract `metalworks.contract.site` (`MarketingSite` /
+  `SiteSection`). CLI `metalworks research site`, MCP Tier-2 `site_render`, skill
+  `generate-site`.
+- **Launch (Pillar F)**: `build_launch_assets(deps, report, positioning) ->
+  list[LaunchAsset]` + `plan_channels(report) -> ChannelPlan`
+  (`metalworks.research.launch`). Refuses (returns []) on a no-go report
+  (negative verdict or no cluster ≥2 distinct authors). One LLM call per surface
+  (Product Hunt / Show HN / X thread) → title + body + variants + claims; each
+  claim is grounded to a real quote and carries a `ClaimCitation` with char-offset
+  spans into the body (`body[span_start:span_end] == claim_text`) — unresolvable
+  claims are dropped. Bodies run through the compliance gate best-effort.
+  Drafting-only: `plan_channels` marks every `ChannelStep` `requires_human` +
+  `posting_gated`; the library never posts. New contract
+  `metalworks.contract.launch` (`LaunchAsset` / `ClaimCitation` / `ChannelPlan` /
+  `ChannelStep`). CLI `metalworks research launch`, MCP Tier-2 `launch_assets_build`
+  + Tier-1 `channel_plan_build`, skill `launch-kit`.
+- **Content/SEO (Pillar G)**: `content_plan_from_report(report) -> ContentPlan`
+  (`metalworks.research.marketing`) — PURE deterministic, zero-key, no LLM. One
+  `ContentPage` per cluster (normalized target_phrase, heuristic page_kind,
+  real-count `stat_anchors`, FAQ from `ResearchBrief.must_address` verbatim) plus
+  a `CitationStrategy` whose `reddit_targets` are real quote permalinks.
+  `render_content_markdown` + `render_faq_jsonld` (a mechanical FAQPage stub).
+  Makes no ranking promises; never invents a keyword or quote. New contract
+  `metalworks.contract.marketing` (`ContentPlan` / `ContentPage` / `FaqItem` /
+  `CitationStrategy`). CLI `metalworks research content-plan`, MCP **Tier-1**
+  (zero-key) `content_plan_from_report`, skill `content-plan`.
+- **Build (Pillar D)**: `build_spec_from_report(deps, report, positioning=None,
+  surface="web", *, stack="empty") -> BuildSpec` + `scaffold(spec, report, dest,
+  *, base) -> list[Path]` (`metalworks.build`). One LLM call maps demand clusters
+  to candidate features; grounding is DETERMINISTIC — each feature is attached to
+  its `source_cluster_rank`'s verbatim quotes and DROPPED if that cluster is
+  invalid or quote-less (no-cite-no-feature), so the model cannot smuggle in an
+  un-grounded feature. Personas derive from the report's audience segments;
+  pricing tiers copy through from the report's price evidence (never recomputed).
+  An infra error (404/auth) propagates rather than being relabelled a thin-demand
+  `partial`. `scaffold` writes a deterministic build harness for the user's OWN
+  coding agent — `CLAUDE.md` (cite-or-die Rule 0), `docs/SPEC.md`, a frozen
+  `docs/EVIDENCE.md` quote+permalink table, a build-pack of skills
+  (`scaffold-startup` / `spec-from-report` / `cite-or-die`), a `cite_or_die.py`
+  PostToolUse lint, and `.mcp.json` — but writes NO product code (`--base` is a
+  stack hint, not vendored boilerplate). New contract `metalworks.contract.build`
+  (`BuildSpec` / `FeatureSpec` / `BuildPersona` / `PricingTier`). CLI `metalworks
+  build init`, MCP **Tier-2** `build_spec`, skill `build-spec`.
+- **Surface + UX (Pillar C, Design stage)**: `decide_surface(deps, report,
+  positioning) -> SurfaceRecommendation` + `build_ux_skeleton(deps, report,
+  positioning, surface) -> UxSkeleton` (`metalworks.research.surface`). A FIXED
+  five-dimension rubric (where-are-the-users, technical sophistication, usage
+  frequency, realtime/hardware, distribution) drives the surface pick; one LLM
+  call phrases each dimension's finding + the chosen surface, and the service
+  GROUNDS each by cosine-matching to the report's real evidence — a dimension
+  with no match is marked `is_assumption`, and `confidence` is service-assigned
+  from grounded coverage. UX screens with no backing voice ship `validated=False`
+  (an explicit hypothesis). Text + structure only (no pixels); the `DesignBrief`
+  handoff is explicitly ungrounded. New contract `metalworks.contract.surface`
+  (`SurfaceRecommendation` / `UxSkeleton` / `RubricDimension` / `Screen` /
+  `TradeOff` / `DesignBrief`); `Research.competitors` and `.positioning` are both
+  real fields now. Surfaced via `metalworks surface <report_id>` CLI, the
+  synchronous `surface_recommend` + `ux_skeleton_build` MCP tools, and the
+  `surface-and-ux` skill.
+- **Landscape (Pillar A)**: `run_competitor_map(deps, report) -> CompetitorMap`
+  (`metalworks.research.landscape`) maps the competitive set — direct, adjacent,
+  and the mandatory status-quo "do nothing" alternative — with an exploitable,
+  EVIDENCED gap per competitor. Four deterministic stages: grounded enumeration
+  (names with zero grounding chunks dropped; degrades to an ungrounded structured
+  call marked `partial`); per-competitor strength/gap harvest; cosine
+  complaint-matching of each gap against the report's real evidence (cluster
+  quotes first, then web findings); assemble, dropping any gap with no resolvable
+  evidence (no-quote-no-gap). `severity` is service-assigned from the matched
+  complaint's distinct-author breadth, never LLM. The status-quo alternative is
+  built deterministically from the top clusters (always verbatim-grounded). New
+  contract `metalworks.contract.landscape` (`CompetitorMap` / `Competitor` /
+  `GapClaim` / `StrengthClaim`), every gap an `EvidenceRef`; `Research.competitors`
+  is now a real optional field. Surfaced via the `metalworks competitor-map
+  <report_id>` CLI, the synchronous `competitor_map_from_report` MCP tool, and the
+  `competitor-map` skill.
+- **Positioning (Pillar B)**: `build_positioning_brief(deps, report) -> PositioningBrief`
+  (`metalworks.research.synthesis.positioning`) turns a demand report into a
+  grounded Dunford wedge + price hypothesis. Wedge SELECTION is deterministic —
+  it stands on an `InsightCluster` the web stream is `silent_web`/`disagree` on at
+  ≥ MEDIUM signal (a pain competitors miss), ranked by `demand_score`; no white
+  space → an honest null brief. Exactly one LLM call phrases the three free-text
+  slots (constrained to the Dunford template) and a second pass verifies each
+  clause is entailed by its cited quotes (marks the brief `partial` if not). The
+  price band is copied through from `PriceFinding`, never recomputed. New
+  contract `metalworks.contract.positioning` (`PositioningBrief` / `WedgeClaim` /
+  `PriceHypothesis`), every slot an `EvidenceRef`; `Research.positioning` is now a
+  real optional field. Surfaced via the `metalworks position <report_id>` CLI,
+  the synchronous `positioning_from_report` MCP tool, and the `position-wedge` skill.
+- **Supabase mirror reader**: `ArcticMirrorReader` (`metalworks[supabase]`) reads
+  the Arctic submission corpus from a Supabase Storage bucket — months from the
+  `arctic_shift_pulls` table, shards listed and signed at query time, DuckDB
+  reading the signed URLs with `WHERE subreddit`/`id IN` pushdown. A faster
+  alternative to the HF mirror that removes HF as a runtime dependency;
+  implements `CorpusReader` and is selected at runtime with
+  `ARCTIC_SHIFT_SOURCE=mirror`.
+
+### Changed
+
+- `Metalworks.research()` now returns a `Research` bundle instead of a bare
+  `DemandReport`; the report is on `.demand` and the grounded evidence on
+  `.evidence`. This stabilizes the stage-1 front-door shape before the 0.1.0 tag.
+- Renamed the low-level discovery export `generate_reply` → `draft_reply` (the
+  MCP tool name is unchanged).
+- Cut `SupabaseStores` from the OSS core; hosted store backends bind to the
+  same repo protocols downstream. The `[supabase]` extra now scopes the Arctic
+  mirror reader (above) instead of the dropped stores.
+- The Google adapters respect Vertex's request ceilings: embeddings are batched
+  at 100 instances/request (Vertex caps at 250) and chat clamps
+  `max_output_tokens` to 65536, so large triage/synthesis calls no longer 400.
+- Tightened package public surfaces: demoted internal plumbing out of the
+  `reddit` / `research` / `discovery` package `__all__`s (still importable from
+  their submodules).
+
+### Notes
+
+- A bare `import metalworks` pulls in no provider SDKs; CI asserts this.
+- The fabricated-persona / account-backstory tooling from the source pipeline
+  was deliberately not open-sourced. See `USAGE_POLICY.md`.

metalworks-0.0.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and maintainers pledge to make participation in
+the metalworks project a harassment-free experience for everyone, regardless of
+age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Being respectful of differing opinions, viewpoints, and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Accepting responsibility, apologizing to those affected by our mistakes, and
+  learning from the experience.
+- Focusing on what is best for the community.
+
+Examples of unacceptable behavior:
+
+- Sexualized language or imagery, and sexual attention or advances of any kind.
+- Trolling, insulting or derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information without explicit permission.
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers at **conduct@lab2a.dev** (update this address).
+All complaints will be reviewed and investigated promptly and fairly. The
+maintainers are obligated to respect the privacy and security of the reporter.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

metalworks-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to metalworks
+
+Thanks for helping. metalworks is pre-release, so the most useful contributions
+right now are provider adapters, storage backends, bug reports against the
+shipped pieces, and docs fixes. Please read [USAGE_POLICY.md](USAGE_POLICY.md)
+and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) first.
+
+## Dev setup
+
+We use [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv venv
+uv pip install -e ".[all,dev]"
+```
+
+`[all,dev]` gives you every provider adapter plus the test and lint toolchain.
+
+## The gate
+
+Everything must pass before a PR lands:
+
+```bash
+ruff check .
+ruff format --check .
+pyright
+pytest -q
+```
+
+`pyright` runs in strict mode over `src`. The test suite runs offline:
+`pytest-socket` disables network, recorded fixtures (respx cassettes, committed
+Parquet shards, recorded grounding responses) stand in for live services.
+
+## The extras model
+
+Core depends only on pydantic, httpx, typing-extensions, typer, and rich.
+Everything that pulls a provider SDK or a heavy dependency (duckdb, supabase,
+the LLM SDKs) lives behind an extra.
+
+Provider SDKs are **lazy-imported behind their extra**. The import happens
+inside the method that needs it, not at module top level, so:
+
+- `import metalworks` never requires a provider SDK. CI asserts a bare import
+  pulls in zero provider modules.
+- A missing extra raises `MissingExtraError` carrying the exact
+  `pip install "metalworks[...]"` command, instead of a raw `ModuleNotFoundError`.
+
+When you add an import of an optional dependency, wrap it:
+
+```python
+try:
+    import duckdb
+except ImportError as exc:
+    raise MissingExtraError("arctic", package="duckdb") from exc
+```
+
+## Adding a provider adapter
+
+1. Implement the protocol. For a chat adapter, implement `ChatModel`
+   (`complete_text`, `complete_structured`, the `model_id` /
+   `capabilities` / `protocol_version` attributes). Add `complete_grounded` and
+   set `capabilities.native_grounding` only if the provider does native web
+   grounding, and carry the full `GroundedResult` provenance (chunks plus
+   character-offset supports, converting from the provider's offsets).
+2. Lazy-import the SDK behind your extra and raise `MissingExtraError` when it
+   is absent.
+3. Read credentials from the environment, raise `MissingKeyError` (naming the
+   env var) when absent. Never read keys from config or at import time.
+4. Run the conformance suite against your adapter:
+
+   ```python
+   from metalworks.testing import FakeChatModel  # reference behavior
+   # repo backends:
+   from metalworks.testing import check_all_repos
+   check_all_repos(MyBackend())
+   ```
+
+   `check_all_repos` includes the >1000-row pagination case that catches
+   silently-truncating backends. Match the semantics the fakes and built-in
+   backends demonstrate.
+
+See [docs/how-to-custom-chatmodel.md](docs/how-to-custom-chatmodel.md) for a
+worked example.
+
+## Rules that are not negotiable
+
+- **No module-level singletons.** No constructing clients, repos, or models at
+  import time.
+- **No env reads at import.** Read environment variables inside functions, never
+  at module scope. A clean-env import test walks every submodule and asserts zero
+  exceptions and zero network with no environment variables set.
+- **Protocols are versioned as a unit.** Additive keyword-only parameters with
+  defaults are a minor bump; anything breaking is a major bump.
+
+## CI matrix
+
+CI runs on Python 3.11, 3.12, and 3.13, each against a bare install and an
+`[all]` install. The bare leg proves core imports clean with no provider
+dependencies; the `[all]` leg runs the full suite.
+
+## Releases and version pinning
+
+The Claude Code plugin launches the MCP server with a version-pinned `uvx`
+command. The plugin and the PyPI package bump in lockstep: when you cut a PyPI
+release, the plugin's pinned version moves with it, in the same release. Do not
+ship one without the other.
+
+Follow the deprecation policy: emit a `DeprecationWarning` at least one minor
+version before removing anything, and call out breaking changes in
+[CHANGELOG.md](CHANGELOG.md) with migration notes.

metalworks-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lab2A
+
+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.