"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
feat(scheduled): ship five research playbooks
Haozhe Wue50f960a0f57
diff --git a/agent/src/scheduled_research/playbooks.py b/agent/src/scheduled_research/playbooks.pynew file mode 100644index 000000000..096bb50bf--- /dev/null+++ b/agent/src/scheduled_research/playbooks.py@@ -0,0 +1,418 @@+"""Ready-to-run research playbooks for the scheduled-research scheduler.++A playbook is a markdown file with a YAML frontmatter header, living in the+``playbooks/`` data directory beside this module. The frontmatter is the+catalogue record (name, description, suggested cadence, the data capabilities+a run needs); the body is the instruction text that becomes+``ScheduledResearchJob.prompt`` verbatim.++Two properties every template is written around, both forced by how the+scheduler actually runs a job (``executor.py`` dispatches ``job.prompt`` through+``src/api/scheduled_routes.py::_dispatch_scheduled_research_job``):++* The prompt is persisted once at creation and re-sent unchanged on every fire,+ so nothing may be baked in that is only true on the authoring day. Every+ template resolves "today" at run time.+* No template names a tool. A playbook states the data *capability* it needs in+ plain language and lets the agent route to whatever tool provides it, so the+ templates survive changes to the tool surface.++Discovery order: the directory named by ``VIBE_TRADING_PLAYBOOK_DIR`` (when+set) is searched before the bundled directory, and a user file wins on slug+collision -- the override rule user skills already follow.++Note on naming: this module and the data directory are both called+``playbooks``. A directory without ``__init__.py`` is only a namespace-package+candidate, which the import system consults *after* file loaders, so+``import src.scheduled_research.playbooks`` always resolves to this module.+``tests/test_research_playbooks.py`` pins that.+"""++from __future__ import annotations++import os+import re+import time+import uuid+from dataclasses import dataclass, field+from pathlib import Path+from typing import Any, Dict, List, Mapping, Optional, Tuple++import yaml++from src.scheduled_research.models import (+ JobStatus,+ ScheduledResearchJob,+ validate_schedule,+ validate_timezone,+ validate_timezone_shape,+)++_PLAYBOOK_DIR_ENV = "VIBE_TRADING_PLAYBOOK_DIR"+_BUNDLED_DIR = Path(__file__).resolve().parent / "playbooks"++# Opening ---, the YAML block, closing ---, then the body. Deliberately stricter+# than src.agent.frontmatter: playbook metadata carries block sequences of+# natural-language phrases (which contain commas), and that parser's inline+# ``[a, b]`` form would shred them.+_FRONTMATTER_RE = re.compile(r"^---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n(.*))?$", re.DOTALL)+_PLACEHOLDER_RE = re.compile(r"\{\{\s*([A-Za-z0-9_]+)\s*\}\}")+_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")+_REQUIRED_META = ("name", "description", "suggested_schedule", "data_capabilities")+# One substituted variable is user text pasted into a prompt that is persisted+# and replayed forever; cap it so a paste accident cannot bloat every run.+_MAX_VARIABLE_CHARS = 4000++# Sentinel for "caller did not pass a timezone", distinct from an explicit None+# (which means UTC and is a legitimate override of a suggested zone).+_KEEP = object()+++class PlaybookError(ValueError):+ """Raised when a playbook file is malformed or used with bad arguments."""+++class PlaybookNotFoundError(PlaybookError):+ """Raised when no playbook matches a requested slug."""+++@dataclass(frozen=True)+class ResearchPlaybook:+ """One parsed playbook template.++ Attributes:+ slug: Filename stem, the stable id used by the CLI and REST layers.+ name: Human-readable title from the frontmatter.+ description: One-line summary for catalogue listings.+ suggested_schedule: Default schedule string, in the scheduler's format+ (interval milliseconds or a 5-field cron expression).+ suggested_timezone: Default IANA timezone key for cron evaluation, or+ ``None`` for UTC.+ markets: Market tags this playbook targets.+ data_capabilities: Plain-language descriptions of the data a run needs.+ Deliberately not tool names -- routing is the agent's job.+ variables: Declared placeholder names mapped to their default text.+ body: Instruction text, with ``{{placeholders}}`` unresolved.+ path: File the playbook was loaded from.+ """++ slug: str+ name: str+ description: str+ suggested_schedule: str+ suggested_timezone: Optional[str]+ markets: Tuple[str, ...]+ data_capabilities: Tuple[str, ...]+ variables: Dict[str, str] = field(default_factory=dict)+ body: str = ""+ path: Optional[Path] = None++ def render(self, variables: Optional[Mapping[str, Any]] = None) -> str:+ """Return the instruction body with placeholders substituted.++ Args:+ variables: Overrides keyed by declared variable name. A key that+ is not declared by this playbook is an error rather than a+ silent no-op. A blank value falls back to the declared default.++ Returns:+ The prompt text to hand to the scheduler.++ Raises:+ PlaybookError: If an undeclared variable is supplied or a value+ exceeds the length cap.+ """+ values = dict(self.variables)+ for key, raw in (variables or {}).items():+ if key not in values:+ raise PlaybookError(+ f"playbook {self.slug!r} has no variable {key!r}; declared: {sorted(values)}"+ )+ text = str(raw).strip()+ if len(text) > _MAX_VARIABLE_CHARS:+ raise PlaybookError(+ f"playbook variable {key!r} is {len(text)} chars; the cap is {_MAX_VARIABLE_CHARS}"+ )+ if text:+ values[key] = text+ # Every placeholder in the body was checked against ``variables`` at+ # load time, so this substitution cannot leave one behind.+ return _PLACEHOLDER_RE.sub(lambda m: values[m.group(1)], self.body)++ def to_job(+ self,+ *,+ job_id: Optional[str] = None,+ schedule: Optional[str] = None,+ timezone: Any = _KEEP,+ variables: Optional[Mapping[str, Any]] = None,+ config: Optional[Mapping[str, Any]] = None,+ next_run_at: Optional[int] = None,+ now_ms: Optional[int] = None,+ ) -> ScheduledResearchJob:+ """Build a schedulable job from this playbook.++ The result is ready for ``ScheduledResearchJobStore.upsert`` and mirrors+ what ``POST /scheduled-runs`` builds, including its first-fire rule: a+ cron job carrying a timezone first fires at its first authored+ occurrence, while interval jobs and timezone-less jobs fire immediately.++ Args:+ job_id: Explicit job id. Defaults to a slug-prefixed unique id.+ schedule: Schedule override. Defaults to ``suggested_schedule``.+ timezone: Timezone override. Omit to keep ``suggested_timezone``;+ pass ``None`` explicitly to force UTC.+ variables: Placeholder overrides, as for :meth:`render`.+ config: Session config forwarded to the agent run. A ``playbook``+ provenance key is added when the caller did not set one;+ ``AgentConfigOverride`` ignores unknown keys+ (``src/config/schema.py`` ``extra="ignore"``), so this is inert+ for config resolution.+ next_run_at: Explicit first-fire epoch-ms, bypassing the rule above.+ now_ms: Injectable clock for tests, in epoch milliseconds.++ Returns:+ A ``PENDING`` :class:`ScheduledResearchJob`.++ Raises:+ PlaybookError: If a supplied variable is invalid.+ ValueError: If the schedule or timezone is malformed, or the cron+ expression has no occurrence within the executor's search+ window.+ """+ resolved_schedule = (schedule if schedule is not None else self.suggested_schedule).strip()+ validate_schedule(resolved_schedule)+ tz = self.suggested_timezone if timezone is _KEEP else timezone+ validate_timezone(tz)++ now = int(time.time() * 1000) if now_ms is None else now_ms+ if next_run_at is None:+ next_run_at = now+ if tz is not None and not resolved_schedule.isdigit():+ # Imported here, not at module scope: the executor pulls in the+ # env config and the tool-redaction module (~0.5s), which a CLI+ # that only lists the catalogue should not pay for.+ from src.scheduled_research.executor import next_due++ next_run_at = next_due(resolved_schedule, now, tz)++ job_config: Dict[str, Any] = dict(config or {})+ job_config.setdefault("playbook", self.slug)++ return ScheduledResearchJob(+ id=job_id or f"playbook-{self.slug}-{uuid.uuid4().hex[:8]}",+ prompt=self.render(variables),+ schedule=resolved_schedule,+ next_run_at=next_run_at,+ status=JobStatus.PENDING,+ created_at=now,+ config=job_config,+ timezone=tz,+ )++ def to_dict(self, include_body: bool = False) -> Dict[str, Any]:+ """Return a JSON-serializable catalogue record.++ Args:+ include_body: Include the raw instruction body. Off by default so+ a catalogue listing stays small.++ Returns:+ A plain dict suitable for a REST response or CLI rendering.+ """+ data: Dict[str, Any] = {+ "slug": self.slug,+ "name": self.name,+ "description": self.description,+ "suggested_schedule": self.suggested_schedule,+ "suggested_timezone": self.suggested_timezone,+ "markets": list(self.markets),+ "data_capabilities": list(self.data_capabilities),+ "variables": dict(self.variables),+ }+ if include_body:+ data["body"] = self.body+ return data+++def _string_list(value: Any, key: str, path: Path) -> Tuple[str, ...]:+ """Coerce a frontmatter value to a tuple of non-empty strings."""+ if isinstance(value, str):+ value = [value]+ if not isinstance(value, list) or not value:+ raise PlaybookError(f"playbook {path}: {key!r} must be a non-empty list of strings")+ items = tuple(str(item).strip() for item in value)+ if any(not item for item in items):+ raise PlaybookError(f"playbook {path}: {key!r} contains an empty entry")+ return items+++def load_playbook_file(path: Path) -> ResearchPlaybook:+ """Parse one playbook markdown file.++ Args:+ path: Path to a ``.md`` playbook file.++ Returns:+ The parsed :class:`ResearchPlaybook`.++ Raises:+ PlaybookError: If the filename is not a valid slug, the file has no+ frontmatter, is missing a required key, declares a malformed+ schedule/timezone, has an empty body, or uses a placeholder it+ never declared.+ OSError: If the file cannot be read.+ """+ # Checked here, not only in get_playbook: the filename IS the slug, so a+ # file that list_playbooks would happily enumerate but get_playbook would+ # refuse (``My_Playbook.md``) must fail loudly at load rather than appear+ # in the catalogue as an entry nobody can select.+ if not _SLUG_RE.fullmatch(path.stem):+ raise PlaybookError(+ f"playbook {path}: filename stem {path.stem!r} is not a valid slug; "+ "use lowercase letters, digits and hyphens (e.g. 'my-playbook.md')"+ )+ # utf-8-sig, not utf-8: a BOM left by a Windows editor would otherwise sit+ # in front of the opening '---' and surface as a bogus "missing frontmatter".+ text = path.read_text(encoding="utf-8-sig")+ match = _FRONTMATTER_RE.match(text)+ if match is None:+ raise PlaybookError(f"playbook {path}: missing '---' YAML frontmatter header")++ try:+ meta = yaml.safe_load(match.group(1) or "") or {}+ except yaml.YAMLError as exc:+ raise PlaybookError(f"playbook {path}: frontmatter is not valid YAML ({exc})") from exc+ if not isinstance(meta, dict):+ raise PlaybookError(f"playbook {path}: frontmatter must be a mapping")++ missing = [key for key in _REQUIRED_META if not meta.get(key)]+ if missing:+ raise PlaybookError(f"playbook {path}: frontmatter is missing {missing}")++ body = (match.group(2) or "").strip()+ if not body:+ raise PlaybookError(f"playbook {path}: body is empty")++ schedule = str(meta["suggested_schedule"]).strip()+ try:+ validate_schedule(schedule)+ except ValueError as exc:+ raise PlaybookError(f"playbook {path}: {exc}") from exc++ tz = meta.get("suggested_timezone")+ tz = str(tz).strip() or None if tz is not None else None+ # Shape only, not resolution: a bundled zone key that this host's tz+ # database lacks must not make the whole catalogue unlistable. to_job()+ # resolves it, the same place POST /scheduled-runs does.+ validate_timezone_shape(tz)++ raw_variables = meta.get("variables") or {}+ if not isinstance(raw_variables, dict):+ raise PlaybookError(f"playbook {path}: 'variables' must be a mapping of name to default")+ variables = {str(k): str(v) for k, v in raw_variables.items()}++ undeclared = sorted(set(_PLACEHOLDER_RE.findall(body)) - set(variables))+ if undeclared:+ raise PlaybookError(f"playbook {path}: body uses undeclared variables {undeclared}")++ return ResearchPlaybook(+ slug=path.stem,+ name=str(meta["name"]).strip(),+ description=str(meta["description"]).strip(),+ suggested_schedule=schedule,+ suggested_timezone=tz,+ markets=_string_list(meta.get("markets") or ["global"], "markets", path),+ data_capabilities=_string_list(meta["data_capabilities"], "data_capabilities", path),+ variables=variables,+ body=body,+ path=path,+ )+++def playbook_dirs(directory: Optional[Path] = None) -> List[Path]:+ """Return the directories searched for playbooks, highest priority first.++ Args:+ directory: When given, the only directory searched.++ Returns:+ A list of directory paths (which may not exist).+ """+ if directory is not None:+ return [Path(directory).expanduser()]+ dirs: List[Path] = []+ override = os.getenv(_PLAYBOOK_DIR_ENV, "").strip()+ if override:+ dirs.append(Path(override).expanduser())+ dirs.append(_BUNDLED_DIR)+ return dirs+++def list_playbooks(directory: Optional[Path] = None) -> List[ResearchPlaybook]:+ """Load every available playbook, sorted by slug.++ A slug found in an earlier directory shadows the same slug later, so a user+ file overrides the bundled one.++ Args:+ directory: Search only this directory instead of the default chain.++ Returns:+ The parsed playbooks, sorted by slug.++ Raises:+ PlaybookError: If any discovered file fails to parse. A broken playbook+ is surfaced, not skipped -- silently dropping it would hide the+ file the user is trying to fix.+ """+ found: Dict[str, ResearchPlaybook] = {}+ for candidate_dir in playbook_dirs(directory):+ if not candidate_dir.is_dir():+ continue+ for path in sorted(candidate_dir.glob("*.md")):+ if path.stem not in found:+ found[path.stem] = load_playbook_file(path)+ return [found[slug] for slug in sorted(found)]+++def get_playbook(slug: str, directory: Optional[Path] = None) -> ResearchPlaybook:+ """Load a single playbook by slug.++ Args:+ slug: Playbook slug (its filename stem).+ directory: Search only this directory instead of the default chain.++ Returns:+ The parsed playbook.++ Raises:+ PlaybookNotFoundError: If the slug is malformed or no file matches.+ PlaybookError: If the matching file fails to parse.+ """+ if not isinstance(slug, str) or not _SLUG_RE.fullmatch(slug):+ raise PlaybookNotFoundError(f"invalid playbook slug: {slug!r}")+ for candidate_dir in playbook_dirs(directory):+ path = candidate_dir / f"{slug}.md"+ if path.is_file():+ return load_playbook_file(path)+ available = ", ".join(p.slug for p in list_playbooks(directory)) or "none"+ raise PlaybookNotFoundError(f"unknown playbook {slug!r}; available: {available}")+++def build_job(slug: str, directory: Optional[Path] = None, **kwargs: Any) -> ScheduledResearchJob:+ """Load a playbook by slug and turn it into a schedulable job.++ Args:+ slug: Playbook slug.+ directory: Search only this directory instead of the default chain.+ **kwargs: Forwarded to :meth:`ResearchPlaybook.to_job`.++ Returns:+ A ``PENDING`` :class:`ScheduledResearchJob`.++ Raises:+ PlaybookNotFoundError: If no playbook matches *slug*.+ PlaybookError: If the file fails to parse or a variable is invalid.+ """+ return get_playbook(slug, directory).to_job(**kwargs)diff --git a/agent/src/scheduled_research/playbooks/a-share-money-flow.md b/agent/src/scheduled_research/playbooks/a-share-money-flow.mdnew file mode 100644index 000000000..c5b764f62--- /dev/null+++ b/agent/src/scheduled_research/playbooks/a-share-money-flow.md@@ -0,0 +1,111 @@+---+name: A-Share Money Flow Review+description: Post-close A-share flow review — exchange public trading disclosures, northbound flows, sector money flow and the limit-up board.+markets: [cn]+suggested_schedule: "0 19 * * 1-5"+suggested_timezone: Asia/Shanghai+data_capabilities:+ - Exchange daily public trading disclosures naming the top buying and selling seats for each listed stock+ - Northbound Stock Connect flow figures for the session+ - Per-stock and per-sector money flow broken down by order size+ - Margin financing and securities lending balances by stock and in aggregate+ - Sector and industry performance rankings for the session+ - Daily price, volume and turnover history for individual A-share tickers+variables:+ watchlist: (no watch list configured)+---++# A-share money flow review++Review where money actually went in the A-share session that just closed.++Resolve the current date from the run environment and confirm the session date+from the retrieved data itself. On a holiday or a half-day the newest available+session may not be today — say which date the report covers, and say it in the+first line.++## Inputs++- Watch list: {{watchlist}}++The watch list only adds a final cross-reference section. The rest of the+report is market-wide and runs with or without it.++## Data to gather++1. The exchange's daily public trading disclosures for the session: which+ stocks qualified, why they qualified, and the top buying and selling seats+ on each, with amounts.+2. Northbound Stock Connect flow for the session, at whatever granularity the+ source actually publishes.+3. Money flow by order size, both at the sector level and for the day's most+ active names.+4. Margin financing and securities lending balances for the session, in+ aggregate and for any name that moved sharply.+5. Sector and industry performance for the session, ranked.+6. The stocks that closed at their daily price limit, up or down, and the+ turnover and time-to-limit information the source provides.+7. For each watch-list symbol, its session return, turnover, and whether it+ appeared in any of the above.++## Method++- A-share boards apply different daily price limits, and stocks under special+ treatment apply a different one again. Determine the applicable limit for a+ stock from the retrieved data rather than assuming one number for the whole+ market, and state which board each limit-up name trades on.+- Seat-level disclosures identify a counterparty channel, not an investor.+ Describe what the disclosure literally shows — this seat bought this amount —+ and do not name or characterise who sat behind it.+- If the northbound source publishes only end-of-day aggregates, use the+ aggregates and say so. Do not reconstruct an intraday path from an end-of-day+ number.+- Cross-check the day's story: a sector leading on performance but not on money+ flow, or a limit-up name with no matching flow, is worth one line as a+ contradiction rather than being smoothed over.+- Report flow in the currency and unit the source used, and label the unit.++## When data is missing++A source that returns nothing, errors out, or is not configured is a fact to+report, not a gap to fill.++- Name every missing item explicitly in a `Data gaps` section, with the reason+ when the failure gave one.+- Continue using only the evidence actually retrieved.+- Never substitute a value from memory, from a general prior, from a+ third-party summary, or from an earlier run of this playbook. A flow number+ that did not come back on this run does not appear in this report.+- Never present a stale figure as current. Several of these disclosures are+ published at different times after the close; if the newest available record+ is from a previous session, print its date beside it and label it as the+ previous session, not as today.+- If a whole section has no evidence, keep its heading and write+ `no data retrieved` under it.+- Every figure carries its session date, its unit, and the source it came from.++## Output++Markdown, in this order:++1. `## Session` — the date this report covers and the index closes for it.+2. `## Northbound` — the flow figures retrieved, with their granularity stated.+3. `## Sector flow` — ranked table: sector, session return, net flow, unit.+4. `## Public trading disclosures` — per stock: reason it qualified, top buy+ seats, top sell seats, net.+5. `## Limit board` — limit-up and limit-down names, board, turnover, and the+ sector they cluster in if they cluster at all.+6. `## Margin balances` — aggregate change and any notable per-stock change.+7. `## Watch list cross-reference` — omit when no watch list was supplied.+8. `## Data gaps` — always present; write `none` when nothing was missing.++## Boundaries++- Factual review of one session. No buy, sell, or hold calls, no price+ targets, no next-day predictions.+- Do not place, modify, or cancel any order, and do not touch a live trading+ connector.+- Do not attribute flows to a named institution, fund, or individual. Report+ the disclosed channel and amount.+- Concentrated buying is an observation, not a signal. Say what was disclosed+ and stop there.diff --git a/agent/src/scheduled_research/playbooks/earnings-season-tracker.md b/agent/src/scheduled_research/playbooks/earnings-season-tracker.mdnew file mode 100644index 000000000..1b5dcc2ff--- /dev/null+++ b/agent/src/scheduled_research/playbooks/earnings-season-tracker.md@@ -0,0 +1,108 @@+---+name: Earnings Season Tracker+description: Upcoming earnings dates for held and watched names, plus what changed in expectations and in the last reported quarter.+markets: [us, cn, hk, global]+suggested_schedule: "0 7 * * 1-5"+suggested_timezone: America/New_York+data_capabilities:+ - Scheduled and confirmed earnings dates for a given list of symbols+ - Reported income-statement and cash-flow lines for recent fiscal periods, with the filing or announcement date+ - Regulatory filings and company announcements covering results, guidance and pre-announcements+ - Analyst estimate and rating changes with the date each change was published+ - Recent daily price and volume history around the reporting dates+variables:+ universe: (no holdings or watch list configured)+ horizon_days: "14"+---++# Earnings season tracker++Track the reporting calendar and the expectation drift for **{{universe}}**+over the next {{horizon_days}} days.++Resolve the current date from the run environment. This text is stored once and+replayed on every fire, so the reporting window must be computed at run time,+never read off this page.++## Inputs++- Universe: {{universe}}+- Horizon: {{horizon_days}} calendar days forward from the run date++If the universe above is empty or says none is configured, stop after saying so+in one line. Do not substitute an index, a sector, or a set of well-known+tickers.++## Data to gather++For each symbol in the universe:++1. The next earnings date, and whether it is confirmed by the company or is an+ estimate. Keep that distinction — it is the single most misread field on+ any earnings calendar.+2. The fiscal period that will be reported, and the date the previous period+ was reported.+3. The revenue, operating income, net income and operating cash flow of the+ last two reported periods, each tagged with the date the figures were filed+ or announced.+4. Any consensus estimate for the coming period, with the date the estimate was+ last revised, plus rating or target changes published since the previous+ report.+5. Company announcements since the previous report that touch guidance:+ pre-announcements, revisions, profit warnings, restatements.+6. The symbol's price change and volume over the twenty sessions before the run+ date.++## Method++- Sort by earnings date ascending. Names reporting inside the horizon come+ first; the rest go into a short tail section.+- Report expectation drift as a delta between two dated observations, never as+ a level. "Consensus EPS revised from X on date A to Y on date B" is usable;+ "consensus is Y" is not.+- Where the last reported period contains a one-off (disposal, impairment,+ tax item) that a filing calls out, say so beside the growth figure.+- Do not compute a surprise number unless both the reported figure and the+ pre-report estimate were actually retrieved on this run.++## When data is missing++A source that returns nothing, errors out, or is not configured is a fact to+report, not a gap to fill.++- Name every missing item explicitly in a `Data gaps` section, with the reason+ when the failure gave one.+- Continue using only the evidence actually retrieved.+- Never substitute a value from memory, from a general prior, from a+ third-party summary, or from an earlier run of this playbook. A number that+ did not come back from a source on this run does not appear in this report.+- Never present a stale figure as current. If the freshest value available is+ older than the window this report covers, print its as-of date beside it.+- If a whole section has no evidence, keep its heading and write+ `no data retrieved` under it.+- Every figure carries its as-of date and the source it came from.+- An earnings date that could not be retrieved is listed as unknown. Do not+ infer it from the previous year's reporting pattern.++## Output++Markdown, in this order:++1. `## Reporting inside the horizon` — a table: symbol, date, confirmed or+ estimated, fiscal period, 20-day price change.+2. `## Expectation changes` — one bullet per dated revision, most recent first.+ Omit the section body and write `none retrieved` if nothing was found.+3. `## Last reported quarter` — per symbol, the two-period comparison of the+ lines gathered above, with filing dates.+4. `## Announcements since last report` — dated, one line each.+5. `## Reporting after the horizon` — symbol and date only.+6. `## Data gaps` — always present; write `none` when nothing was missing.++## Boundaries++- Factual tracking only. No buy, sell, or hold calls, no price targets, no+ view on whether a name will beat or miss.+- Do not place, modify, or cancel any order, and do not touch a live trading+ connector.+- Do not model a future quarter. This playbook reports what has been filed and+ what estimates have been published, and nothing else.diff --git a/agent/src/scheduled_research/playbooks/institutional-holdings-diff.md b/agent/src/scheduled_research/playbooks/institutional-holdings-diff.mdnew file mode 100644index 000000000..d29e7979e--- /dev/null+++ b/agent/src/scheduled_research/playbooks/institutional-holdings-diff.md@@ -0,0 +1,113 @@+---+name: Institutional Holdings Diff+description: Quarter-over-quarter position changes disclosed by institutional managers, diffed for a chosen set of managers or symbols.+markets: [us]+suggested_schedule: "0 9 15 2,5,8,11 *"+suggested_timezone: America/New_York+data_capabilities:+ - Quarterly institutional holdings disclosures filed with the U.S. securities regulator, per manager and per reporting period+ - Filing index lookup that returns the filing date and the period the filing covers+ - Company profile and share-count reference data for the disclosed symbols+ - Daily price history covering the disclosed period and the interval since it ended+variables:+ managers: (no managers specified)+ symbols: (no symbols specified)+---++# Institutional holdings diff++Diff the two most recently disclosed quarters of institutional holdings for+the managers and symbols below.++Resolve the current date from the run environment, then determine which+reporting periods are actually available from the filings you retrieve. Do not+assume a period is available because the calendar says it should be.++## Inputs++- Managers: {{managers}}+- Symbols: {{symbols}}++At least one of the two must be supplied. If both are empty, stop and say so in+one line — do not substitute a list of famous investors or a market-wide scan.+When managers are given, diff each manager's whole book. When only symbols are+given, diff the disclosed holders of those symbols.++## Data to gather++1. For each manager, the two most recent quarterly holdings disclosures: the+ period each one covers, the date each one was filed, and whether it is an+ original filing or an amendment.+2. The full position list from each of those two filings — symbol, share count,+ disclosed value.+3. For symbols that appear in the diff, the current share count and basic+ company reference data.+4. Price history spanning the disclosed period and the interval between the+ period end and the run date.++## Method++- These filings are due within 45 days of the quarter end. Every position+ therefore describes the manager's book **as of the period-end date**, not as+ of today. Print the period-end date in the report header and repeat it in any+ section that states a position size.+- Classify each change as new, exited, increased, reduced, or unchanged, using+ share counts rather than disclosed values — value moves with price and will+ otherwise be mistaken for activity.+- Report value changes separately, and split them into the part explained by+ the price move over the period and the residual.+- Check for share splits between the two periods before comparing share counts.+ If a split occurred and the filings are not adjusted for it, say so and do+ not report a mechanical change as a position change.+- An amended filing supersedes the original for the same period. Use the latest+ amendment and say that you did.+- These disclosures cover only the security types the rule requires — broadly,+ U.S.-listed equity and certain related instruments. Short positions, cash,+ non-U.S. listings and most derivatives are not disclosed here. State this+ limitation once in the report rather than presenting the filing as the+ manager's full book.++## When data is missing++A source that returns nothing, errors out, or is not configured is a fact to+report, not a gap to fill.++- Name every missing item explicitly in a `Data gaps` section, with the reason+ when the failure gave one.+- Continue using only the evidence actually retrieved.+- Never substitute a value from memory, from a general prior, from a+ third-party summary, or from an earlier run of this playbook. A holding that+ did not come back from a filing on this run does not appear in this report.+- Never present a stale figure as current. Every position line carries the+ period-end date of the filing it came from.+- If only one period could be retrieved for a manager, report that single+ period as a snapshot and explicitly state that no diff was possible. Do not+ diff against remembered or assumed prior holdings.+- If a whole section has no evidence, keep its heading and write+ `no data retrieved` under it.++## Output++Markdown, in this order:++1. `## Coverage` — the managers and symbols actually resolved, the two periods+ compared, and each filing's filing date and amendment status.+2. `## New positions` — table: manager, symbol, shares, disclosed value.+3. `## Exited positions` — same columns, from the earlier period.+4. `## Increased` and `## Reduced` — table: manager, symbol, share change,+ percent change in shares, value change, price change over the period.+5. `## Concentration` — each manager's top holdings by disclosed value in the+ later period, and how that share shifted between periods.+6. `## Limitations` — the as-of lag and the instrument-coverage limitation,+ stated in two lines.+7. `## Data gaps` — always present; write `none` when nothing was missing.++## Boundaries++- Factual diff of public filings. No buy, sell, or hold calls, no price+ targets, no reading of intent into a manager's trade.+- Do not place, modify, or cancel any order, and do not touch a live trading+ connector.+- Do not describe a disclosed position as a current position. The lag between+ the period end and the run date is the single most important caveat in this+ report; keep it visible.diff --git a/agent/src/scheduled_research/playbooks/portfolio-checkup.md b/agent/src/scheduled_research/playbooks/portfolio-checkup.mdnew file mode 100644index 000000000..859798ce8--- /dev/null+++ b/agent/src/scheduled_research/playbooks/portfolio-checkup.md@@ -0,0 +1,110 @@+---+name: Portfolio Checkup+description: Periodic risk x-ray of a stated book — exposure, concentration, correlation and drawdown, measured from retrieved prices.+markets: [global, cn, hk, us, crypto]+suggested_schedule: "0 9 * * 6"+suggested_timezone: Asia/Shanghai+data_capabilities:+ - Daily price history long enough to compute volatility, correlation and drawdown for every position+ - Portfolio-level risk decomposition — position weights, volatility contribution, correlation structure, drawdown+ - Sector, industry and listing-venue classification for each holding+ - Benchmark index history for the same window as the holdings+ - Currency reference rates when the book spans more than one currency+variables:+ holdings: (no holdings provided — the report cannot run without them)+ benchmark: the broad index of the book's home market+ lookback_days: "252"+---++# Portfolio checkup++Run a risk x-ray on the book below over a {{lookback_days}}-session lookback,+against **{{benchmark}}**.++Resolve the current date from the run environment; the lookback window ends on+the most recent session for which prices were actually retrieved, not on an+assumed date.++## Inputs++- Holdings: {{holdings}}+- Benchmark: {{benchmark}}+- Lookback: {{lookback_days}} sessions++If no holdings are supplied, stop and say so in one line. Do not invent a book,+do not reuse a book from an earlier run, and do not fall back to an index as a+stand-in portfolio.++## Data to gather++1. Daily closes for every holding covering the full lookback, plus the same+ window for the benchmark.+2. Position weights implied by the supplied quantities and the latest retrieved+ close. If the input gives weights rather than quantities, use them as given+ and say so.+3. A risk decomposition of the book: per-position volatility contribution,+ pairwise correlation structure, realised portfolio volatility, maximum+ drawdown and the dates it ran between.+4. Sector, industry and listing venue for each holding.+5. Where holdings settle in different currencies, the reference rates needed to+ express everything in one currency, with the rate date.++## Method++- Compute every statistic from the price series retrieved on this run. Report+ the exact number of sessions each statistic used.+- A holding whose price history is shorter than the lookback is measured over+ its own available window, and that shorter window is printed beside its+ numbers. Never pad, interpolate, or back-fill a missing series.+- Concentration is reported on three axes at once: single position, sector, and+ listing venue or currency. A book can look diversified on one and be+ concentrated on another.+- Drawdown is stated with both its depth and its date range, and whether the+ book has recovered.+- If the book contains both long and short exposure, say so and state which+ statistics remain meaningful under netting rather than reporting a single+ blended number as if the book were long-only.++## When data is missing++A source that returns nothing, errors out, or is not configured is a fact to+report, not a gap to fill.++- Name every missing item explicitly in a `Data gaps` section, with the reason+ when the failure gave one.+- Continue using only the evidence actually retrieved.+- Never substitute a value from memory, from a general prior, from a+ third-party summary, or from an earlier run of this playbook. A price series+ that did not come back on this run does not enter any calculation.+- Never present a stale figure as current. Print the as-of date of the last+ close used for every holding.+- If a whole section has no evidence, keep its heading and write+ `no data retrieved` under it.+- A holding whose prices could not be retrieved is excluded from the+ statistics, listed by name in `Data gaps`, and its weight is reported as+ unmeasured — never silently dropped and never redistributed across the rest.++## Output++Markdown, in this order:++1. `## Book summary` — number of positions, currencies, as-of date, sessions+ used.+2. `## Exposure` — table of holding, weight, sector, venue, last close, as-of+ date.+3. `## Concentration` — top position weight, top three combined, largest sector+ weight, largest venue or currency weight.+4. `## Risk` — realised volatility, volatility contribution ranking, the most+ correlated pairs, and the same volatility figure for the benchmark.+5. `## Drawdown` — maximum drawdown, its date range, current distance from+ peak; the same for the benchmark.+6. `## Data gaps` — always present; write `none` when nothing was missing.++## Boundaries++- Measurement only. No buy, sell, or hold calls, no price targets, no+ rebalancing instructions, no target weights, no view on any holding.+- Do not place, modify, or cancel any order, and do not touch a live trading+ connector.+- Historical statistics describe the window measured. Do not present them as a+ forecast of future risk.diff --git a/agent/src/scheduled_research/playbooks/premarket-brief.md b/agent/src/scheduled_research/playbooks/premarket-brief.mdnew file mode 100644index 000000000..64e7ebb94--- /dev/null+++ b/agent/src/scheduled_research/playbooks/premarket-brief.md@@ -0,0 +1,99 @@+---+name: Pre-market Brief+description: Overnight global market moves plus today's watch items, assembled before the home session opens.+markets: [global, cn, hk, us]+suggested_schedule: "30 8 * * 1-5"+suggested_timezone: Asia/Shanghai+data_capabilities:+ - Daily index levels and percentage changes for the major overnight equity sessions+ - Overnight moves in benchmark commodities, major FX pairs and government bond yields+ - Headline news published since the previous home-market close, with publication timestamps+ - Recent daily price and volume history for the symbols on the user's watch list+ - Macro releases and corporate events scheduled for the current date+variables:+ home_market: China A-shares+ watchlist: (no watch list configured)+---++# Pre-market brief++Produce a pre-open briefing for **{{home_market}}**.++Resolve the current date and time from the run environment on every run. This+instruction text is stored once and replayed on every fire, so it contains no+date of its own — never assume the day it was written is the day it is running.++## Inputs++- Home market: {{home_market}}+- Watch list: {{watchlist}}++If the watch list above is empty or says none is configured, skip the+per-symbol section entirely and say so in one line rather than inventing a+list of symbols.++## Data to gather++1. Closing level and percentage change of the major equity indices whose+ sessions ran while the home market was shut, plus the home market's own+ previous close.+2. Overnight change in the benchmark energy and metals contracts, the main FX+ pairs relevant to the home market, and the 10-year government bond yield of+ the home market and of the United States.+3. Headlines published since the previous home-market close that name the home+ market, its index, its regulator, or any watch-list symbol. Keep the+ publication timestamp attached to each headline.+4. For each watch-list symbol: the last close, the change over the last five+ sessions, and volume against its recent average.+5. Anything scheduled for today — macro data releases, central bank events,+ earnings dates, index changes — that falls in the home market's session.++## Method++- Order the report by how much it can move the home session, not by how+ interesting the headline is.+- Separate what moved from why it moved. Only assert a cause when a retrieved+ source states that cause; otherwise report the move and the coincident+ headline as two separate facts.+- A move smaller than the instrument's own recent daily range is noise. Say so+ instead of narrating it.++## When data is missing++A source that returns nothing, errors out, or is not configured is a fact to+report, not a gap to fill.++- Name every missing item explicitly in a `Data gaps` section, with the reason+ when the failure gave one.+- Continue using only the evidence actually retrieved.+- Never substitute a value from memory, from a general prior, from a+ third-party summary, or from an earlier run of this playbook. A number that+ did not come back from a source on this run does not appear in this report.+- Never present a stale figure as current. If the freshest value available is+ older than the window this brief covers, print its as-of date beside it.+- If a whole section has no evidence, keep its heading and write+ `no data retrieved` under it.+- Every figure carries its as-of date and the source it came from.++## Output++Markdown, in this order:++1. `## Overnight tape` — a table of index / commodity / FX / yield, level,+ change, as-of timestamp.+2. `## What changed overnight` — at most five bullets, each tied to a dated+ headline.+3. `## Watch list` — one line per symbol: last close, 5-day change, volume vs+ average, and any dated news naming it.+4. `## On today's calendar` — scheduled releases and events, with local times.+5. `## Data gaps` — always present; write `none` when nothing was missing.++Keep the whole brief under roughly 700 words.++## Boundaries++- This is a factual briefing. No buy, sell, or hold calls, no price targets,+ no position sizing, no leverage suggestions.+- Do not place, modify, or cancel any order, and do not touch a live trading+ connector.+- Do not forecast the day's direction. Report the setup; the reader decides.diff --git a/agent/tests/test_research_playbooks.py b/agent/tests/test_research_playbooks.pynew file mode 100644index 000000000..166160dfb--- /dev/null+++ b/agent/tests/test_research_playbooks.py@@ -0,0 +1,425 @@+"""Tests for the scheduled-research playbook catalogue.++Covers: bundled-template invariants (schedule/timezone validity, the+missing-data rule, no tool names in any body), the markdown+frontmatter loader+and its failure modes, variable rendering, the user-directory override, and+job construction against the real job store and the real cron evaluator.++No network is involved: playbooks are local files and job construction is pure.+"""++from __future__ import annotations++import re+from pathlib import Path+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError++import pytest++from src.scheduled_research.executor import next_due+from src.scheduled_research.models import JobStatus, validate_schedule+from src.scheduled_research.playbooks import (+ PlaybookError,+ PlaybookNotFoundError,+ ResearchPlaybook,+ build_job,+ get_playbook,+ list_playbooks,+ load_playbook_file,+ playbook_dirs,+)+from src.scheduled_research.store import ScheduledResearchJobStore++EXPECTED_SLUGS = {+ "a-share-money-flow",+ "earnings-season-tracker",+ "institutional-holdings-diff",+ "portfolio-checkup",+ "premarket-brief",+}++# 2026-08-04T12:00:00Z, fixed so first-fire assertions never depend on the clock.+NOW_MS = 1785585600000++_PLACEHOLDER_RE = re.compile(r"\{\{\s*[A-Za-z0-9_]+\s*\}\}")+_SNAKE_CASE_RE = re.compile(r"\b[a-z]+(?:_[a-z0-9]+)+\b")++[email protected](autouse=True)+def _no_user_playbook_dir(monkeypatch: pytest.MonkeyPatch) -> None:+ """Keep the bundled-catalogue assertions hermetic on a developer machine."""+ monkeypatch.delenv("VIBE_TRADING_PLAYBOOK_DIR", raising=False)+++def _write(directory: Path, slug: str, text: str) -> Path:+ directory.mkdir(parents=True, exist_ok=True)+ path = directory / f"{slug}.md"+ path.write_text(text, encoding="utf-8")+ return path+++_MINIMAL = """---+name: Minimal+description: A minimal playbook.+suggested_schedule: "3600000"+data_capabilities:+ - Daily closing prices for one symbol+variables:+ symbol: AAPL+---++# Minimal++Look at {{symbol}}.+"""+++# ---------------------------------------------------------------------------+# Bundled catalogue invariants+# ---------------------------------------------------------------------------+++class TestBundledCatalogue:+ def test_module_wins_over_same_named_data_directory(self) -> None:+ """``playbooks.py`` and ``playbooks/`` coexist; the module must win."""+ import src.scheduled_research.playbooks as module++ assert module.__file__ is not None+ assert Path(module.__file__).name == "playbooks.py"++ def test_ships_the_expected_five(self) -> None:+ assert {p.slug for p in list_playbooks()} == EXPECTED_SLUGS++ def test_sorted_by_slug(self) -> None:+ slugs = [p.slug for p in list_playbooks()]+ assert slugs == sorted(slugs)++ def test_covers_more_than_us_markets(self) -> None:+ markets = {m for p in list_playbooks() for m in p.markets}+ assert "cn" in markets and "global" in markets++ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))+ def test_suggested_schedule_is_valid(self, slug: str) -> None:+ validate_schedule(get_playbook(slug).suggested_schedule)++ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))+ def test_suggested_timezone_resolves(self, slug: str) -> None:+ tz = get_playbook(slug).suggested_timezone+ if tz is None:+ return+ try:+ ZoneInfo(tz)+ except ZoneInfoNotFoundError: # host without a full IANA database+ pytest.skip(f"host timezone database has no {tz!r}")++ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))+ def test_declares_data_capabilities_not_tool_names(self, slug: str) -> None:+ playbook = get_playbook(slug)+ assert playbook.data_capabilities+ for capability in playbook.data_capabilities:+ assert not _SNAKE_CASE_RE.search(capability), capability++ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))+ def test_body_names_no_tool(self, slug: str) -> None:+ """Bodies describe capabilities; every tool in this repo is snake_case."""+ body = _PLACEHOLDER_RE.sub("", get_playbook(slug).body)+ assert not _SNAKE_CASE_RE.findall(body)++ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))+ def test_body_carries_the_missing_data_rule(self, slug: str) -> None:+ body = get_playbook(slug).body+ assert "## When data is missing" in body+ assert "Data gaps" in body+ assert "from memory" in body+ assert "third-party summary" in body++ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))+ def test_body_states_output_and_boundaries(self, slug: str) -> None:+ body = get_playbook(slug).body+ assert "## Output" in body+ assert "## Boundaries" in body+ # Line wrapping must not decide whether the no-advice rule is present.+ unwrapped = " ".join(body.split())+ assert "No buy, sell, or hold calls" in unwrapped+ assert "no price targets" in unwrapped+ assert "Do not place, modify, or cancel any order" in unwrapped++ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))+ def test_body_resolves_the_run_date_at_run_time(self, slug: str) -> None:+ """The prompt is stored once and replayed, so no date may be baked in."""+ body = get_playbook(slug).body+ assert "run environment" in body+ assert not re.search(r"\b20\d\d-\d\d-\d\d\b", body)++ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))+ def test_renders_and_schedules(self, slug: str) -> None:+ job = build_job(slug, now_ms=NOW_MS)+ assert job.status is JobStatus.PENDING+ assert "{{" not in job.prompt+ assert job.next_run_at > NOW_MS # cron + timezone => first authored fire+++# ---------------------------------------------------------------------------+# Loader+# ---------------------------------------------------------------------------+++class TestLoader:+ def test_parses_block_sequence_capabilities(self, tmp_path: Path) -> None:+ path = _write(+ tmp_path,+ "multi",+ "---\n"+ "name: Multi\n"+ "description: Two capabilities.\n"+ 'suggested_schedule: "0 9 * * 1-5"\n'+ "suggested_timezone: Asia/Shanghai\n"+ "markets: [cn, hk]\n"+ "data_capabilities:\n"+ " - Prices, volumes and turnover for one session\n"+ " - Sector rankings, including the laggards\n"+ "---\n\nBody.\n",+ )+ playbook = load_playbook_file(path)+ assert playbook.data_capabilities == (+ "Prices, volumes and turnover for one session",+ "Sector rankings, including the laggards",+ )+ assert playbook.markets == ("cn", "hk")+ assert playbook.suggested_timezone == "Asia/Shanghai"++ def test_slug_comes_from_the_filename(self, tmp_path: Path) -> None:+ assert load_playbook_file(_write(tmp_path, "some-slug", _MINIMAL)).slug == "some-slug"++ def test_defaults_markets_when_absent(self, tmp_path: Path) -> None:+ assert load_playbook_file(_write(tmp_path, "m", _MINIMAL)).markets == ("global",)++ def test_rejects_file_without_frontmatter(self, tmp_path: Path) -> None:+ path = _write(tmp_path, "bare", "# Just a heading\n")+ with pytest.raises(PlaybookError, match="frontmatter"):+ load_playbook_file(path)++ def test_rejects_non_mapping_frontmatter(self, tmp_path: Path) -> None:+ path = _write(tmp_path, "seq", "---\n- a\n- b\n---\n\nBody.\n")+ with pytest.raises(PlaybookError, match="must be a mapping"):+ load_playbook_file(path)++ def test_rejects_invalid_yaml(self, tmp_path: Path) -> None:+ path = _write(tmp_path, "bad", "---\nname: [unclosed\n---\n\nBody.\n")+ with pytest.raises(PlaybookError, match="not valid YAML"):+ load_playbook_file(path)++ def test_rejects_missing_required_key(self, tmp_path: Path) -> None:+ path = _write(tmp_path, "nodesc", _MINIMAL.replace("description: A minimal playbook.\n", ""))+ with pytest.raises(PlaybookError, match="description"):+ load_playbook_file(path)++ def test_rejects_invalid_schedule(self, tmp_path: Path) -> None:+ path = _write(tmp_path, "badcron", _MINIMAL.replace('"3600000"', '"99 * * * *"'))+ with pytest.raises(PlaybookError, match="out of range"):+ load_playbook_file(path)++ def test_rejects_empty_body(self, tmp_path: Path) -> None:+ path = _write(tmp_path, "empty", _MINIMAL.split("# Minimal")[0].rstrip("\n") + "\n")+ with pytest.raises(PlaybookError, match="body is empty"):+ load_playbook_file(path)++ def test_rejects_undeclared_placeholder(self, tmp_path: Path) -> None:+ path = _write(tmp_path, "typo", _MINIMAL.replace("{{symbol}}", "{{symbal}}"))+ with pytest.raises(PlaybookError, match="undeclared variables"):+ load_playbook_file(path)++ def test_rejects_empty_capability_entry(self, tmp_path: Path) -> None:+ path = _write(+ tmp_path,+ "blank",+ _MINIMAL.replace(" - Daily closing prices for one symbol\n", ' - ""\n'),+ )+ with pytest.raises(PlaybookError, match="empty entry"):+ load_playbook_file(path)+++# ---------------------------------------------------------------------------+# Lookup and directory precedence+# ---------------------------------------------------------------------------+++class TestLookup:+ def test_unknown_slug_lists_available(self) -> None:+ with pytest.raises(PlaybookNotFoundError, match="premarket-brief"):+ get_playbook("does-not-exist")++ @pytest.mark.parametrize("slug", ["../models", "a/b", "Upper", "", "a b"])+ def test_rejects_malformed_slug(self, slug: str) -> None:+ with pytest.raises(PlaybookNotFoundError, match="invalid playbook slug"):+ get_playbook(slug)++ def test_env_directory_is_searched_first(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("VIBE_TRADING_PLAYBOOK_DIR", str(tmp_path))+ assert playbook_dirs()[0] == tmp_path++ def test_user_file_shadows_bundled_slug(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ _write(tmp_path, "premarket-brief", _MINIMAL)+ monkeypatch.setenv("VIBE_TRADING_PLAYBOOK_DIR", str(tmp_path))+ assert get_playbook("premarket-brief").name == "Minimal"+ catalogue = {p.slug: p.name for p in list_playbooks()}+ assert catalogue["premarket-brief"] == "Minimal"+ assert set(catalogue) == EXPECTED_SLUGS # override, not addition++ def test_missing_directory_is_not_an_error(self, tmp_path: Path) -> None:+ assert list_playbooks(directory=tmp_path / "nope") == []++ def test_broken_user_file_surfaces_instead_of_being_skipped(+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ _write(tmp_path, "broken", "no frontmatter here\n")+ monkeypatch.setenv("VIBE_TRADING_PLAYBOOK_DIR", str(tmp_path))+ with pytest.raises(PlaybookError, match="frontmatter"):+ list_playbooks()++ def test_every_listed_slug_is_retrievable(self) -> None:+ """The catalogue must never advertise an entry get_playbook refuses."""+ for playbook in list_playbooks():+ assert get_playbook(playbook.slug).slug == playbook.slug++ @pytest.mark.parametrize("stem", ["My_Playbook", "Upper", "has space", "under_score"])+ def test_badly_named_file_is_rejected_at_load(self, tmp_path: Path, stem: str) -> None:+ """A file whose stem is not a valid slug fails loudly instead of+ becoming a catalogue entry that get_playbook can never return."""+ path = _write(tmp_path, stem, _MINIMAL)+ with pytest.raises(PlaybookError, match="not a valid slug"):+ load_playbook_file(path)+ with pytest.raises(PlaybookError, match="not a valid slug"):+ list_playbooks(directory=tmp_path)++ def test_utf8_bom_does_not_hide_the_frontmatter(self, tmp_path: Path) -> None:+ """A BOM from a Windows editor must not read as 'missing frontmatter'."""+ path = tmp_path / "bom.md"+ path.write_text(_MINIMAL, encoding="utf-8-sig")+ assert load_playbook_file(path).name == "Minimal"+++# ---------------------------------------------------------------------------+# Rendering+# ---------------------------------------------------------------------------+++class TestRender:+ def _minimal(self, tmp_path: Path) -> ResearchPlaybook:+ return load_playbook_file(_write(tmp_path, "minimal", _MINIMAL))++ def test_uses_declared_defaults(self, tmp_path: Path) -> None:+ assert self._minimal(tmp_path).render() == "# Minimal\n\nLook at AAPL."++ def test_override_wins(self, tmp_path: Path) -> None:+ assert "600519.SH" in self._minimal(tmp_path).render({"symbol": "600519.SH"})++ def test_blank_override_falls_back_to_default(self, tmp_path: Path) -> None:+ assert "AAPL" in self._minimal(tmp_path).render({"symbol": " "})++ def test_undeclared_variable_is_an_error(self, tmp_path: Path) -> None:+ with pytest.raises(PlaybookError, match="has no variable"):+ self._minimal(tmp_path).render({"ticker": "AAPL"})++ def test_oversized_value_is_rejected(self, tmp_path: Path) -> None:+ with pytest.raises(PlaybookError, match="the cap is"):+ self._minimal(tmp_path).render({"symbol": "A" * 4001})++ def test_braces_in_a_value_are_not_re_expanded(self, tmp_path: Path) -> None:+ rendered = self._minimal(tmp_path).render({"symbol": "{{symbol}}"})+ assert rendered.endswith("Look at {{symbol}}.")+++# ---------------------------------------------------------------------------+# Job construction+# ---------------------------------------------------------------------------+++class TestToJob:+ def test_defaults_to_the_suggested_cadence(self) -> None:+ playbook = get_playbook("premarket-brief")+ job = playbook.to_job(now_ms=NOW_MS)+ assert job.schedule == playbook.suggested_schedule+ assert job.timezone == playbook.suggested_timezone+ assert job.id.startswith("playbook-premarket-brief-")+ assert job.created_at == NOW_MS++ def test_first_fire_matches_the_cron_evaluator(self) -> None:+ playbook = get_playbook("a-share-money-flow")+ job = playbook.to_job(now_ms=NOW_MS)+ assert job.next_run_at == next_due(+ playbook.suggested_schedule, NOW_MS, playbook.suggested_timezone+ )++ def test_interval_schedule_fires_immediately(self) -> None:+ job = get_playbook("premarket-brief").to_job(schedule="3600000", now_ms=NOW_MS)+ assert job.schedule == "3600000"+ assert job.next_run_at == NOW_MS++ def test_explicit_none_timezone_means_utc_and_immediate_first_fire(self) -> None:+ job = get_playbook("premarket-brief").to_job(timezone=None, now_ms=NOW_MS)+ assert job.timezone is None+ assert job.next_run_at == NOW_MS++ def test_explicit_next_run_at_wins(self) -> None:+ job = get_playbook("premarket-brief").to_job(next_run_at=42, now_ms=NOW_MS)+ assert job.next_run_at == 42++ def test_rejects_a_malformed_schedule_override(self) -> None:+ with pytest.raises(ValueError, match="cron"):+ get_playbook("premarket-brief").to_job(schedule="not a schedule")++ def test_rejects_an_unresolvable_timezone_override(self) -> None:+ with pytest.raises(ValueError, match="not a recognized IANA timezone"):+ get_playbook("premarket-brief").to_job(timezone="Mars/Olympus")++ def test_prompt_is_the_rendered_body(self) -> None:+ playbook = get_playbook("portfolio-checkup")+ variables = {"holdings": "600519.SH 100; AAPL 50"}+ job = playbook.to_job(variables=variables, now_ms=NOW_MS)+ assert job.prompt == playbook.render(variables)+ assert "600519.SH 100; AAPL 50" in job.prompt++ def test_config_records_provenance_but_never_overwrites_the_caller(self) -> None:+ assert build_job("premarket-brief", now_ms=NOW_MS).config == {"playbook": "premarket-brief"}+ job = build_job("premarket-brief", now_ms=NOW_MS, config={"playbook": "mine", "model": "x"})+ assert job.config == {"playbook": "mine", "model": "x"}++ def test_caller_config_is_copied_not_aliased(self) -> None:+ supplied: dict = {}+ build_job("premarket-brief", now_ms=NOW_MS, config=supplied)+ assert supplied == {}++ @pytest.mark.parametrize("slug", sorted(EXPECTED_SLUGS))+ def test_job_survives_the_real_store(self, tmp_path: Path, slug: str) -> None:+ store = ScheduledResearchJobStore(tmp_path / "jobs.json")+ job = build_job(slug, now_ms=NOW_MS)+ store.upsert(job)+ loaded = store.get(job.id)+ assert loaded is not None+ assert loaded.prompt == job.prompt+ assert loaded.schedule == job.schedule+ assert loaded.timezone == job.timezone+++# ---------------------------------------------------------------------------+# Catalogue serialization+# ---------------------------------------------------------------------------+++class TestToDict:+ def test_omits_the_body_by_default(self) -> None:+ data = get_playbook("premarket-brief").to_dict()+ assert "body" not in data+ assert data["slug"] == "premarket-brief"+ assert isinstance(data["data_capabilities"], list)+ assert isinstance(data["markets"], list)+ assert data["variables"]["home_market"]++ def test_includes_the_body_on_request(self) -> None:+ assert get_playbook("premarket-brief").to_dict(include_body=True)["body"]++ def test_every_bundled_record_is_json_serializable(self) -> None:+ import json++ json.dumps([p.to_dict(include_body=True) for p in list_playbooks()])diff --git a/pyproject.toml b/pyproject.tomlindex 355cc7882..e97782f13 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -90,6 +90,7 @@ include = ["src*", "backtest*", "cli*"]"skills/**/*.json","skills/**/*.py","providers/*.json",+ "scheduled_research/playbooks/*.md","swarm/presets/*.yaml","shadow_account/templates/*.j2","shadow_account/templates/*.html",