icelake 0.5.0__tar.gz

icelake-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --group dev
+      - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --group dev
+      - run: uv run mypy
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    services:
+      mongodb:
+        image: mongo:7
+        ports:
+          - 27017:27017
+        options: >-
+          --health-cmd "mongosh --eval 'db.adminCommand({ ping: 1 })'"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+          --health-start-period 20s
+    env:
+      MONGODB_URI: mongodb://127.0.0.1:27017/icelake_test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --group dev
+      - name: Wait for MongoDB
+        run: |
+          for i in $(seq 1 30); do
+            uv run python -c "import socket; socket.create_connection(('127.0.0.1', 27017), 1).close()" && exit 0
+            sleep 1
+          done
+          echo "MongoDB did not become ready" >&2
+          exit 1
+      - run: uv run pytest tests/ -q --cov=icelake --cov-report=xml
+      - uses: codecov/codecov-action@v5
+        if: matrix.python-version == '3.12'
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+
+  changelog:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --group dev
+      - run: uv run towncrier check --compare-with origin/${{ github.base_ref }}

icelake-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,73 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+[ab][0-9]+"
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - name: Test
+        run: uv sync --group dev && uv run pytest tests/ -q
+      - name: Build
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/icelake
+    permissions:
+      id-token: write
+    steps:
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - run: uv publish
+
+  release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Extract release notes
+        id: notes
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          VERSION="${TAG#v}"
+          awk -v v="$VERSION" '
+            $0 ~ "^## \\[" v "\\]" { found=1; next }
+            found && /^## \[/ { exit }
+            found { print }
+          ' CHANGELOG.md > release_notes.md
+          if [ ! -s release_notes.md ]; then
+            echo "See [CHANGELOG.md](CHANGELOG.md) for details." > release_notes.md
+          fi
+          case "$VERSION" in
+            *a[0-9]*|*b[0-9]*|*rc[0-9]*) echo "prerelease=true" >> "$GITHUB_OUTPUT" ;;
+            *) echo "prerelease=false" >> "$GITHUB_OUTPUT" ;;
+          esac
+      - uses: softprops/action-gh-release@v2
+        with:
+          body_path: release_notes.md
+          prerelease: ${{ steps.notes.outputs.prerelease }}

icelake-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,100 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Base bump. 'none' releases the version already in pyproject.toml (e.g. a manual major)."
+        required: true
+        type: choice
+        options: [minor, patch, none]
+      prerelease:
+        description: "Pre-release stage (PEP 440). Pre-releases may run on any branch and push only a tag."
+        required: true
+        type: choice
+        options: [none, alpha, beta, rc]
+
+permissions:
+  contents: write
+  actions: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    concurrency: release
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --group dev
+
+      - name: Guard stable releases to main
+        if: inputs.prerelease == 'none'
+        run: |
+          if [ "${{ github.ref_name }}" != "main" ]; then
+            echo "Stable releases must run on main. Use a prerelease stage from a feature branch." >&2
+            exit 1
+          fi
+
+      - name: Compute version
+        id: bump
+        run: |
+          set -euo pipefail
+          if [ "${{ inputs.bump }}" = "none" ]; then
+            BASE="$(uv version --short)"
+          else
+            BASE="$(uv version --bump "${{ inputs.bump }}" --dry-run | awk '{print $NF}')"
+          fi
+          if [ "${{ inputs.prerelease }}" = "none" ]; then
+            VERSION="$BASE"
+          else
+            case "${{ inputs.prerelease }}" in
+              alpha) SHORT=a ;; beta) SHORT=b ;; rc) SHORT=rc ;;
+            esac
+            LAST=0
+            for TAG in $(git tag -l "v${BASE}${SHORT}[0-9]*"); do
+              N="${TAG#v${BASE}${SHORT}}"
+              [ "$N" -gt "$LAST" ] && LAST="$N"
+            done
+            VERSION="${BASE}${SHORT}$((LAST + 1))"
+          fi
+          if git rev-parse -q --verify "refs/tags/v${VERSION}" >/dev/null; then
+            echo "Tag v${VERSION} already exists." >&2
+            exit 1
+          fi
+          uv version "$VERSION" --no-sync
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Build changelog
+        run: uv run towncrier build --yes --version "${{ steps.bump.outputs.version }}"
+
+      - name: Commit and tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml uv.lock CHANGELOG.md changelog.d
+          git commit -m "release: v${{ steps.bump.outputs.version }}"
+          git tag -a "v${{ steps.bump.outputs.version }}" -m "v${{ steps.bump.outputs.version }}"
+
+      - name: Push stable release to main
+        if: inputs.prerelease == 'none'
+        run: git push origin HEAD:main
+
+      - name: Push tag
+        run: git push origin "v${{ steps.bump.outputs.version }}"
+
+      - name: Trigger PyPI publish
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # GITHUB_TOKEN tag pushes do not start other workflows; dispatch explicitly.
+          # Retry briefly in case the tag is not yet visible as a dispatch ref.
+          for i in 1 2 3 4 5; do
+            gh workflow run publish.yml --ref "v${{ steps.bump.outputs.version }}" && exit 0
+            sleep 2
+          done
+          echo "Failed to dispatch publish.yml for v${{ steps.bump.outputs.version }}" >&2
+          exit 1

icelake-0.5.0/.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+*.db
+*.db-shm
+*.db-wal
+
+.coverage
+
+.bench/
+
+.env
+
+bench_runs/
+
+docs/

icelake-0.5.0/.python-version

@@ -0,0 +1 @@
+3.14

icelake-0.5.0/AGENTS.md

@@ -0,0 +1,76 @@
+# Core Principles (Ordered - Higher Wins on Conflict)
+
+## Code is a liability, not an asset
+
+- Before writing code, answer: (1) Does a dependency or existing module already do
+  this? (2) What breaks upstream? (3) What depends on this downstream?
+- Equal designs -> fewer lines wins. No speculative abstractions, no "just in case"
+  helpers, no unused parameters.
+- Deleting code is a feature. When a module loses its justification, say so.
+- Never add code to appear thorough. Deliberate, minimal additions only.
+
+
+## Adopt proven machinery; never rebuild it
+
+- If a mature, maintained dependency solves the problem, use it — don't hand-roll
+  a weaker version. Check the project's architecture decision records / plan docs
+  for what has been adopted and what is explicitly out of scope.
+- Conversely: if a dependency is deprecated or unmaintained, flag it rather than
+  building deeper on top of it.
+
+## One concern per module
+
+- Each module owns one concern and exposes it through a narrow interface.
+  Reaching into another module's internals is a violation — use its contract.
+
+## Design for the swap you can't predict
+
+- Every external dependency (database, LLM provider, library) is treated as
+  replaceable. The test: "if we swapped X tomorrow, how many files change?"
+  If the answer is more than the adapter plus config, the abstraction has leaked.
+
+
+# Code Quality Standards
+
+## Baseline
+
+- Full type annotations on all public interfaces; strict type-checker clean.
+- Linter + formatter clean before merge; no suppressions without a comment
+  explaining why.
+- All data crossing a boundary (API I/O, persistence, inter-process, LLM I/O)
+  is validated by a schema. No raw dicts at boundaries.
+- Fixed sets of values are enums, never raw strings.
+
+## Clarity
+
+- Names state intent and units (`timeout_seconds`, not `timeout`).
+- Public capability entry points carry user-facing docstrings — treat them as
+  product surface, not developer notes.
+- Async on all I/O paths; never block the event loop.
+
+## Size gates (need explicit justification to exceed)
+
+- Function: ~40 lines. Module: ~300 lines. Justification means a comment or PR
+  note explaining why splitting would be worse.
+
+## Testing
+
+- Business logic must be testable without transport, network, or live services —
+  inject fakes at the seams. Core correctness logic (validation, verification,
+  state transitions) gets exhaustive tests.
+- Test behavior at interfaces, not implementation details.
+
+## Every change passes this checklist
+
+1. Does something that exists already do this?
+2. What breaks upstream? What depends on this downstream?
+3. Can this be fewer lines?
+4. Is this logic duplicated elsewhere (or does it belong in a shared layer)?
+5. Are new boundaries schema-validated?
+6. Are new costs (API calls, storage growth, latency) metered and bounded?
+7. Does this work with N processes, or only one?
+
+## Hygiene
+
+- No commented-out code (git is the history). No TODOs without a linked issue.
+- No dead config knobs, no unused exports.

icelake-0.5.0/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog
+
+All notable changes to icelake are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow
+[PEP 440](https://peps.python.org/pep-0440/).
+
+Release notes are assembled from fragments in `changelog.d/` with
+[towncrier](https://towncrier.readthedocs.io/). To add an entry, drop a
+`<issue-or-name>.<type>.md` fragment into `changelog.d/` where `<type>` is one
+of `security`, `removed`, `deprecated`, `added`, `changed`, `fixed`.
+
+<!-- towncrier release notes start -->
+
+## [0.5.0](https://github.com/nulzo/icelake/tree/v0.5.0) - 2026-09-07
+
+### Removed
+
+- Removed the tag-echo citation path: `Citations.parse`, `MarkerMode`, `ParsedReply`, `UsedSource`, `Citations.instructions`/`source_list`, `PromptContext.resolve_used`/`apply_citations`, `UsedCitation`, and `render_citation_tag`. The injection block no longer carries `[mem:N]` tags, and no regex parses model output — citation-shaped prose the model writes is inert text, while links only ever come from the closed set via attribution or provider-anchored offsets. Migrate: build the set with `Citations.from_prompt_context(ctx)`, call `await memory.attribute_citations(reply, set_, guild_id=...)`, then `set_.apply(reply, attribution)`. ([#citation-tags](https://github.com/nulzo/icelake/issues/citation-tags))
+
+### Added
+
+- Citations are now grounded **post-generation** via structured attribution, replacing model-echoed tags entirely. The answer model sees plain facts (no `[mem:N]` tags, no URLs, no citation contract); after generation, `DiscordMemory.attribute_citations()` maps verbatim reply spans to the closed citation set in one cheap structured call on the small-model tier, and `Citations.apply(text, attribution)` weaves `[[N]](<url>)` jump links at the verified spans. Only claims a registered source actually supports get cited — retrieved-but-unused sources never render, and source-list dumps are structurally impossible. Added `icelake.attribution` (`attribute`, `ReplyAttribution`, `AttributedClaim`), `Citations.citable`, `fact_source_urls`, and a `MeterPurpose.ATTRIBUTION` meter key. ([#citation-attribution](https://github.com/nulzo/icelake/issues/citation-attribution))
+
+
+## [0.4.3](https://github.com/nulzo/icelake/tree/v0.4.3) - 2026-09-07
+
+No significant changes.
+
+
+## [0.4.2](https://github.com/nulzo/icelake/tree/v0.4.2) - 2026-09-07
+
+### Added
+
+- Added `icelake.citations`: a reply-side citation system built on a closed source set with deny-by-default parsing, mirroring how production assistants (ChatGPT, Claude, Perplexity) keep citations reliable. `Citations` seeds from `PromptContext`, registers link sources (`add_source`) and Discord messages (`add_message`) with library-minted `[src:N]` refs, exposes the model-facing `instructions` / `source_list`, and validates with one call — `parse(text, markers=...)` splices provider-anchored offsets, resolves echoed refs, canonicalizes mangled-but-known references, and deletes every citation-shaped token outside the set (invented `[src:9]`, self-written `[1](url)` links, `【…】` artifacts). `parse` returns a structured `ParsedReply` (cleaned `text` + resolved `citations`) so presentation — inline links, footers, or stripped markers — is the consumer's; an `apply(text)` convenience weaves Discord jump links for the common bot path. Also added `MarkerMode`, `CitationSource`, `UsedSource`, `render_fact_list()`, and top-level exports of `Citations`, `MarkerMode`, `ParsedReply`, `UsedSource`, `CitationSource`, `message_url`, and `render_fact_list`. ([#citation-registry](https://github.com/nulzo/icelake/issues/citation-registry))
+
+### Changed
+
+- `PromptContext.apply_citations` now delegates to `Citations.apply` — a single parsing implementation for all citation handling. Behavior tightens deny-by-default: model-written `[N](url)` links whose target is not a registered source and `【…】` artifacts are now removed, while word-attached prose like `array[0]` is preserved. ([#apply-citations-registry](https://github.com/nulzo/icelake/issues/apply-citations-registry))
+
+
+## [0.4.1](https://github.com/nulzo/icelake/tree/v0.4.1) - 2026-09-07
+
+No significant changes.
+
+
+## [0.4.0](https://github.com/nulzo/icelake/tree/v0.4.0) - 2026-09-07
+
+### Added
+
+- Closed-ID citation objects plus an optional OpenRouter L2 reranker after RRF.
+  The generator may only echo advertised `[mem:N]` tags (or structured `fact_id`
+  claims); consumers call `PromptContext.resolve_used` and weave the returned
+  objects. Banter emits no IDs, so `used` is empty and no links are inserted.
+  Rerank degrades to hybrid order on failure, timeout, or score-arity mismatch.
+  `prompt_context` now pair-intersects every combination of mentions and thread
+  participants and enables graph-hop recall whenever anyone else is in the turn.
+  `graph.shared_attributions` returns both members' stances over shared entities
+  so consumers can show agreement and disagreement without a second fetch. ([#citation-objects-reranker](https://github.com/nulzo/icelake/issues/citation-objects-reranker))
+
+
+## [0.3.4](https://github.com/nulzo/icelake/tree/v0.3.4) - 2026-09-06
+
+### Fixed
+
+- Relation endpoints named after a guild member now collapse to that member's user
+  node at write time (no more person-entity twins), and every person-facing graph
+  query (`relations_of`, `between`, `shared`, `similar_users`, `entity_stances`,
+  `neighbors`) follows `entity.linked_user_id` so pre-existing twins still resolve
+  to the member. Reads go through a single seam (`GraphApi._incident`) that unions
+  the member's user node with every entity twin and collapses the result, so edges
+  stored against a twin (a member mentioned by name before they spoke) surface on
+  that member's star. Added `graph.shared(a, b)`: the identity-collapsed,
+  weight-ranked intersection of two members' entity edges, with polarity
+  preserved. Bot IDs are no longer written to `FactRecord.related_user_ids`. ([#identity-collapse](https://github.com/nulzo/icelake/issues/identity-collapse))
+
+
+## [0.3.3](https://github.com/nulzo/icelake/tree/v0.3.3) - 2026-08-31
+
+### Added
+
+- Documented the extraction-model benchmark in the README: ranked OpenRouter
+  models on the e2e sim (quality, spend, latency) with a fixed weighted score
+  so later runs can be appended without rescaling. Includes the 2026-08-30
+  challenger round (GPT-4o-mini, GPT-4.1-mini, Gemini 2.5 Flash, Qwen3 32B). ([#model-bench-readme](https://github.com/nulzo/icelake/issues/model-bench-readme))
+- Documented the name-in-prose lookup pattern ("what do you know about X?" with no
+  @mention): a new README section explains that `prompt_context` is mention-keyed by
+  design and shows the resolve-then-strict-fetch flow (`identity.resolve` →
+  `facts.list_for_subject`, never guessing on ambiguity) across three entry points —
+  slash command (zero LLM), a structured-output router, and native function calling.
+  Added `examples/name_lookup_tool.py`, a runnable LLM-free demo of the shared
+  handler, and wired the pattern into `examples/omni_style_bot.py` (router +
+  `/memory lookup`). ([#name-lookup-docs](https://github.com/nulzo/icelake/issues/name-lookup-docs))
+- `RetrievalConfig.top_k` and `RetrievalConfig.max_per_subject` now bound the
+  `prompt_context` hot path (previously hardcoded to the `RecallQuery` defaults
+  of 8 total / 4 per subject), so consumers can widen per-turn memory injection
+  from configuration. ([#prompt-context-caps](https://github.com/nulzo/icelake/issues/prompt-context-caps))
+
+### Changed
+
+- Bench matrix is a per-model OpenRouter param map (reasoning, temperature,
+  structured_outputs) instead of one global flag. LlmConfig accepts
+  `reasoning=none` to disable thinking on models that allow it. ([#bench-model-params](https://github.com/nulzo/icelake/issues/bench-model-params))
+
+
+## [0.3.2](https://github.com/nulzo/icelake/tree/v0.3.2) - 2026-08-30
+
+### Added
+
+- Added `lifecycle.decay_stability_days` (default 7.0), the Ebbinghaus timescale:
+  retention is now exp(-days / (strength x stability)), so a one-off fact survives
+  ~3 weeks instead of ~3 days. Forgetting policy moved into a single pure selector
+  (`lifecycle.select_forgotten_facts`) shared by all store adapters — mongo/sqlite
+  no longer carry private copies of the decay math, and the sweep is one bulk
+  UPDATE instead of per-fact writes. ([#decay-stability](https://github.com/nulzo/icelake/issues/decay-stability))
+
+
+## [0.3.1](https://github.com/nulzo/icelake/tree/v0.3.1) - 2026-08-29
+
+No significant changes.
+
+
+## [0.3.0](https://github.com/nulzo/icelake/tree/v0.3.0) - 2026-08-29
+
+No significant changes.
+
+
+## [0.2.0](https://github.com/nulzo/icelake/tree/v0.2.0) - 2026-08-29
+
+No significant changes.

icelake-0.5.0/LICENSE

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