anchorcast 0.1.0__tar.gz

anchorcast-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Ruff
+        run: python -m ruff check src tests
+      - name: Pytest
+        run: python -m pytest

anchorcast-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Tag matches package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")"
+          test "$tag" = "$version"
+      - name: Build
+        run: |
+          python -m pip install build
+          python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

anchorcast-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.anchorcast/
+.pytest_cache/
+/segments/
+.env*
+.DS_Store

anchorcast-0.1.0/AGENTS.md

@@ -0,0 +1,44 @@
+# Agent notes
+
+This repository is a **Python client** for generative livestreams. It is not a YouTube app, not a character, and not a news show.
+
+## Layout
+
+- `src/anchorcast/` — library
+- `tests/` — pytest, no fal network calls
+- `examples/` — apps that consume the library, including a literary-bear news stream
+
+## Architecture
+
+Keep these boundaries:
+
+| Layer | Owns |
+| --- | --- |
+| `Brief` | What to say next (topic, talking points, citations) |
+| `Model` | `generate(request) -> Segment` |
+| `Source` | `next_brief(playhead) -> Brief \| None` |
+| `Continuity` | Which still starts the next clip |
+| `Session` | Generate-ahead buffer and events |
+
+Do **not** add YouTube, Twitch, TikTok, Stripe, or Super Chat integrations here. Those belong in a later backend that maps platform events into `Brief`s on a `QueueSource`.
+
+Do **not** let `IdleSource` (or any default source) invent news claims. Idle is character bits only.
+
+## Python
+
+- 3.11+
+- Double quotes
+- Type annotations on public functions and dataclasses
+- `gpt-5.6-luna` for OpenAI calls in examples (cheap GPT-5.6 tier)
+
+## Checks
+
+```bash
+python3.11 -m pip install -e ".[dev]"
+python3.11 -m pytest
+python3.11 -m ruff check src tests
+```
+
+New behavior needs a failing test first unless it is config, examples, or generated files.
+
+The H3 Max adapter hits fal. Do not call it from unit tests. Use a fake `Model`.

anchorcast-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-09-03
+
+### Added
+
+- `Session` with a generate-ahead buffer
+- `Brief`, `Character`, `Segment`, and `StreamEvent` types
+- `H3Max` model adapter (`minimax/h3-max/image-to-video`)
+- `QueueSource`, `FeedSource`, and `IdleSource`
+- `LastFrameContinuity` and `IdentityContinuity`
+- MIT license
+- GitHub Actions CI (pytest, ruff) and tag-triggered PyPI publish
+- `Session.pump()` for live apps
+- Follow-up clips prompt the model to continue the take
+- `examples/literary_bear` continuous news stream with continuing spoken lines
+
+`Brief` has no paid/unpaid taxonomy. Use `priority` to order the queue.

anchorcast-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,62 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community 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, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior:
+
+- The use of 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, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Report incidents by opening a private GitHub security advisory on this
+repository or by contacting the maintainer through GitHub. All complaints will
+be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

anchorcast-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+Thanks for looking at Anchorcast. The useful work is the `Session` / `Model` / `Source` / `Brief` interface. Keep that small.
+
+## Setup
+
+```bash
+python3.11 -m pip install -e ".[dev]"
+python3.11 -m pytest
+python3.11 -m ruff check src tests
+```
+
+Python 3.11+ and ffmpeg on `PATH`. Unit tests must not call fal.
+
+## Pull requests
+
+- One idea per PR
+- Tests for behavior changes
+- Do not land YouTube / Twitch / TikTok / payments in this repo
+- Match existing style: double quotes, type hints
+
+Coding agents should read [AGENTS.md](AGENTS.md).
+
+## Releasing
+
+CI runs pytest and ruff on every push and pull request.
+
+PyPI publishes from a version tag via [trusted publishing](https://docs.pypi.org/trusted-publishers/). No API token in GitHub secrets.
+
+1. Bump `version` in `pyproject.toml` and `src/anchorcast/__init__.py`, and add a `CHANGELOG.md` entry.
+2. On PyPI: Publishing → add a trusted publisher (`scrollmark/anchorcast`, workflow `publish.yml`, environment `pypi`). Needed once, before the first release.
+3. Tag and push:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The tag must match the package version (`v0.1.0` for `0.1.0`). The `pypi` GitHub Environment must exist on the repo.
+
+## License
+
+Contributions are MIT, same as the rest of the project.

anchorcast-0.1.0/LICENSE

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

anchorcast-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: anchorcast
+Version: 0.1.0
+Summary: A Python client for real-time media streams generated by pluggable models.
+Project-URL: Homepage, https://github.com/scrollmark/anchorcast
+Project-URL: Repository, https://github.com/scrollmark/anchorcast
+Project-URL: Issues, https://github.com/scrollmark/anchorcast/issues
+Author: Nikhil Sharma
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fal,generative-video,h3-max,livestream
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fal-client>=0.5.0
+Requires-Dist: feedparser>=6.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Anchorcast
+
+A Python client for **real-time media streams generated by pluggable models**.
+
+[![CI](https://github.com/scrollmark/anchorcast/actions/workflows/ci.yml/badge.svg)](https://github.com/scrollmark/anchorcast/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/anchorcast)](https://pypi.org/project/anchorcast/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+> Early (`0.1.0`). The session / model / source interface is the point. Expect it to move.
+
+## Install
+
+```bash
+pip install anchorcast
+```
+
+From git:
+
+```bash
+pip install git+https://github.com/scrollmark/anchorcast.git
+```
+
+For local development:
+
+```bash
+git clone https://github.com/scrollmark/anchorcast.git
+cd anchorcast
+python3.11 -m pip install -e ".[dev]"
+python3.11 -m pytest
+```
+
+**Requirements:** Python 3.11+, [ffmpeg](https://ffmpeg.org/) on `PATH` (for last-frame continuity), and a [fal](https://fal.ai) key if you use the H3 Max adapter (`FAL_KEY` or `FALAI_API_KEY`).
+
+## Quickstart
+
+```python
+from pathlib import Path
+
+from anchorcast import Brief, Character, QueueSource, Session
+from anchorcast.models import H3Max
+
+source = QueueSource()
+session = Session(
+    model=H3Max(),
+    character=Character(
+        name="Bear",
+        image=Path("bear.png"),
+        visual_prompt="Hand-drawn stuffed bear on cream paper.",
+        voice_prompt="warm, unhurried cadence",
+    ),
+    source=source,
+    workdir=Path(".anchorcast"),
+)
+
+source.submit(
+    Brief(
+        id="rates",
+        topic="mortgage rates",
+        talking_points=("Why are mortgage rates still so high?",),
+        citations=("https://example.com/rates",),
+        priority=10,
+    )
+)
+
+for event in session.run(max_segments=1):
+    print(event.segment.path, event.segment.brief.topic)
+```
+
+A `Brief` is the next beat of the stream. The session asks the source for one, asks the model for a clip, and keeps a small generate-ahead buffer so you do not mint faster than the playhead.
+
+## Core types
+
+| Type | Role |
+| --- | --- |
+| **`Brief`** | Topic, talking points, citations, priority |
+| **`Character`** | Seed still, visual prompt, voice description |
+| **`Model`** | `generate(request) -> Segment`. `H3Max` ships first; swap the adapter to change models |
+| **`Source`** | `next_brief(playhead) -> Brief \| None` |
+| **`Continuity`** | Which still starts the next clip (`LastFrameContinuity` or `IdentityContinuity`) |
+| **`Session`** | Buffer, pacing, event stream |
+
+### Sources
+
+- **`QueueSource`** — explicit briefs, ordered by `priority`
+- **`FeedSource`** — RSS/Atom mapped to cited stories
+- **`IdleSource`** — character bits that make **no news claims**
+
+When the queue is empty, pass `idle=IdleSource(character)` so the session can keep breathing without inventing facts.
+
+### Custom model
+
+```python
+from anchorcast.types import GenerateRequest, Segment
+
+class MyModel:
+    def generate(self, request: GenerateRequest) -> Segment:
+        # write a video to request.output_path
+        return Segment(
+            path=request.output_path,
+            duration=15.0,
+            generated_in=1.0,
+            brief=request.brief,
+        )
+```
+
+### Custom source
+
+```python
+from anchorcast.types import Brief, Playhead
+
+class WebhookSource:
+    def next_brief(self, playhead: Playhead | None = None) -> Brief | None:
+        return self._take_from_queue()
+```
+
+YouTube Live, Twitch, TikTok Live, and Super Chats are a later backend. That layer should map platform events into `Brief`s and submit them to a `QueueSource`. It does not belong in this client.
+
+## Status
+
+- Generate-ahead `Session` with a pluggable model and source
+- fal MiniMax H3 Max adapter (`minimax/h3-max/image-to-video`)
+- Feed, queue, and idle sources
+- Last-frame continuity via ffmpeg
+
+Not yet: RTMP output, hosted APIs, or platform chat integrations.
+
+## Example app
+
+`examples/literary_bear` is a continuous 1926 literary-bear news stream (Shepard, not Disney). Each clip is the next fifteen seconds of one monologue, not a fresh "oh bother" cold open.
+
+```bash
+python3.11 -m examples.literary_bear --dry-run   # scripts only
+python3.11 -m examples.literary_bear            # local player at http://127.0.0.1:8765
+```
+
+`--llm` or `OPENAI_API_KEY` writes spoken lines with `gpt-5.6-luna`. `--no-llm` forces the rotating templates.
+
+## Development
+
+```bash
+python3.11 -m pip install -e ".[dev]"
+python3.11 -m pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+The example still under `examples/characters/literary-bear/` is an E. H. Shepard illustration from *Winnie-the-Pooh* (1926), U.S. public domain. It is not Disney, and this project is not affiliated with Disney.

anchorcast-0.1.0/README.md

@@ -0,0 +1,150 @@
+# Anchorcast
+
+A Python client for **real-time media streams generated by pluggable models**.
+
+[![CI](https://github.com/scrollmark/anchorcast/actions/workflows/ci.yml/badge.svg)](https://github.com/scrollmark/anchorcast/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/anchorcast)](https://pypi.org/project/anchorcast/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+> Early (`0.1.0`). The session / model / source interface is the point. Expect it to move.
+
+## Install
+
+```bash
+pip install anchorcast
+```
+
+From git:
+
+```bash
+pip install git+https://github.com/scrollmark/anchorcast.git
+```
+
+For local development:
+
+```bash
+git clone https://github.com/scrollmark/anchorcast.git
+cd anchorcast
+python3.11 -m pip install -e ".[dev]"
+python3.11 -m pytest
+```
+
+**Requirements:** Python 3.11+, [ffmpeg](https://ffmpeg.org/) on `PATH` (for last-frame continuity), and a [fal](https://fal.ai) key if you use the H3 Max adapter (`FAL_KEY` or `FALAI_API_KEY`).
+
+## Quickstart
+
+```python
+from pathlib import Path
+
+from anchorcast import Brief, Character, QueueSource, Session
+from anchorcast.models import H3Max
+
+source = QueueSource()
+session = Session(
+    model=H3Max(),
+    character=Character(
+        name="Bear",
+        image=Path("bear.png"),
+        visual_prompt="Hand-drawn stuffed bear on cream paper.",
+        voice_prompt="warm, unhurried cadence",
+    ),
+    source=source,
+    workdir=Path(".anchorcast"),
+)
+
+source.submit(
+    Brief(
+        id="rates",
+        topic="mortgage rates",
+        talking_points=("Why are mortgage rates still so high?",),
+        citations=("https://example.com/rates",),
+        priority=10,
+    )
+)
+
+for event in session.run(max_segments=1):
+    print(event.segment.path, event.segment.brief.topic)
+```
+
+A `Brief` is the next beat of the stream. The session asks the source for one, asks the model for a clip, and keeps a small generate-ahead buffer so you do not mint faster than the playhead.
+
+## Core types
+
+| Type | Role |
+| --- | --- |
+| **`Brief`** | Topic, talking points, citations, priority |
+| **`Character`** | Seed still, visual prompt, voice description |
+| **`Model`** | `generate(request) -> Segment`. `H3Max` ships first; swap the adapter to change models |
+| **`Source`** | `next_brief(playhead) -> Brief \| None` |
+| **`Continuity`** | Which still starts the next clip (`LastFrameContinuity` or `IdentityContinuity`) |
+| **`Session`** | Buffer, pacing, event stream |
+
+### Sources
+
+- **`QueueSource`** — explicit briefs, ordered by `priority`
+- **`FeedSource`** — RSS/Atom mapped to cited stories
+- **`IdleSource`** — character bits that make **no news claims**
+
+When the queue is empty, pass `idle=IdleSource(character)` so the session can keep breathing without inventing facts.
+
+### Custom model
+
+```python
+from anchorcast.types import GenerateRequest, Segment
+
+class MyModel:
+    def generate(self, request: GenerateRequest) -> Segment:
+        # write a video to request.output_path
+        return Segment(
+            path=request.output_path,
+            duration=15.0,
+            generated_in=1.0,
+            brief=request.brief,
+        )
+```
+
+### Custom source
+
+```python
+from anchorcast.types import Brief, Playhead
+
+class WebhookSource:
+    def next_brief(self, playhead: Playhead | None = None) -> Brief | None:
+        return self._take_from_queue()
+```
+
+YouTube Live, Twitch, TikTok Live, and Super Chats are a later backend. That layer should map platform events into `Brief`s and submit them to a `QueueSource`. It does not belong in this client.
+
+## Status
+
+- Generate-ahead `Session` with a pluggable model and source
+- fal MiniMax H3 Max adapter (`minimax/h3-max/image-to-video`)
+- Feed, queue, and idle sources
+- Last-frame continuity via ffmpeg
+
+Not yet: RTMP output, hosted APIs, or platform chat integrations.
+
+## Example app
+
+`examples/literary_bear` is a continuous 1926 literary-bear news stream (Shepard, not Disney). Each clip is the next fifteen seconds of one monologue, not a fresh "oh bother" cold open.
+
+```bash
+python3.11 -m examples.literary_bear --dry-run   # scripts only
+python3.11 -m examples.literary_bear            # local player at http://127.0.0.1:8765
+```
+
+`--llm` or `OPENAI_API_KEY` writes spoken lines with `gpt-5.6-luna`. `--no-llm` forces the rotating templates.
+
+## Development
+
+```bash
+python3.11 -m pip install -e ".[dev]"
+python3.11 -m pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+The example still under `examples/characters/literary-bear/` is an E. H. Shepard illustration from *Winnie-the-Pooh* (1926), U.S. public domain. It is not Disney, and this project is not affiliated with Disney.

anchorcast-0.1.0/SECURITY.md

@@ -0,0 +1,17 @@
+# Security Policy
+
+## Supported versions
+
+`0.1.x` on `main` is the only supported line.
+
+## Reporting
+
+Please **do not** open a public issue for a vulnerability.
+
+Use GitHub's private reporting:
+
+https://github.com/scrollmark/anchorcast/security/advisories/new
+
+Include what you ran, what you expected, and a minimal reproduction if you have one.
+
+This client talks to third-party generation APIs. Never commit API keys. `FAL_KEY` / `FALAI_API_KEY` stay in the environment.

anchorcast-0.1.0/examples/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

anchorcast-0.1.0/examples/characters/literary-bear/CREDIT.txt

@@ -0,0 +1,3 @@
+E. H. Shepard illustration from Winnie-the-Pooh (1926), U.S. public domain.
+Source: Wikimedia Commons, File:Winnie-the-Pooh_42.png
+Not Disney. Shepard's UK copyright may still apply in the UK until 2046.

anchorcast-0.1.0/examples/feed_session.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from anchorcast import Character, FeedSource, IdleSource, Session
+from anchorcast.continuity import LastFrameContinuity
+from anchorcast.models import H3Max
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def main() -> None:
+    character = Character(
+        name="Bear",
+        image=ROOT / "examples" / "characters" / "literary-bear" / "pooh-1926.png",
+        visual_prompt=(
+            "Hand-drawn 1926 book illustration of a stuffed bear of very little brain. "
+            "Pencil and light watercolor on cream paper. No clothing."
+        ),
+        voice_prompt="warm, soft, slightly posh, unhurried stuffed-bear cadence",
+    )
+    source = FeedSource("https://feeds.bbci.co.uk/news/world/rss.xml")
+    session = Session(
+        model=H3Max(),
+        character=character,
+        source=source,
+        idle=IdleSource(character),
+        workdir=ROOT / ".anchorcast",
+        continuity=LastFrameContinuity(),
+        buffer_clips=2,
+    )
+    for event in session.run(max_segments=2):
+        clip = event.segment
+        print(f"{event.index:02d}  {clip.duration:.1f}s in {clip.generated_in:.1f}s  {clip.brief.topic}")
+
+
+if __name__ == "__main__":
+    main()

anchorcast-0.1.0/examples/literary_bear/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

anchorcast-0.1.0/examples/literary_bear/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from examples.literary_bear.app import main
+
+if __name__ == "__main__":
+    main()