pulse-engine 0.2.16__tar.gz → 0.2.17__tar.gz

{pulse_engine-0.2.16 → pulse_engine-0.2.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pulse-engine
-Version: 0.2.16
+Version: 0.2.17
 Summary: Pulse Engine — Hybrid framework for building Pulse products
 Author: Pulse Team
 Requires-Python: >=3.11,<3.13
@@ -13,17 +13,20 @@ Requires-Dist: apprise (==1.11.0)
 Requires-Dist: asyncpg (>=0.30.0,<0.31.0)
 Requires-Dist: asyncssh (>=2.23.0,<3.0.0)
 Requires-Dist: beautifulsoup4 (>=4.12.0,<5.0.0)
+Requires-Dist: bedrock-agentcore (>=1.17.0,<2.0.0)
 Requires-Dist: boto3 (>=1.35.0,<2.0.0)
 Requires-Dist: celery-redbeat (>=2.2.0)
 Requires-Dist: celery[redis] (>=5.4.0,<6.0.0)
 Requires-Dist: cookiecutter (>=2.6.0,<3.0.0)
 Requires-Dist: curl-cffi (>=0.15.0,<0.16.0)
+Requires-Dist: deepagents (>=0.6,<0.7)
 Requires-Dist: deepgram-sdk (>=3.7.0,<4.0.0)
 Requires-Dist: email-validator (>=2.3.0,<3.0.0)
 Requires-Dist: fastapi (>=0.115.0,<0.116.0)
 Requires-Dist: httpx (>=0.28.0,<0.29.0)
 Requires-Dist: importlib-metadata (>=9.0.0,<10.0.0)
 Requires-Dist: langchain (>=1.2.13,<2.0.0)
+Requires-Dist: langchain-agentcore-codeinterpreter (>=0.0.5,<0.0.6)
 Requires-Dist: langchain-anthropic (>=1.4.0,<2.0.0)
 Requires-Dist: langchain-openai (>=1.1.11,<2.0.0)
 Requires-Dist: langdetect (>=1.0.9,<2.0.0)

{pulse_engine-0.2.16 → pulse_engine-0.2.17}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pulse-engine"
-version = "0.2.16"
+version = "0.2.17"
 description = "Pulse Engine — Hybrid framework for building Pulse products"
 authors = ["Pulse Team"]
 readme = "README.md"
@@ -49,6 +49,9 @@ apprise = "1.11.0"
 asyncssh = "^2.23.0"
 importlib-metadata = "^9.0.0"
 prefect = {version = "==3.7.1", optional = true}
+deepagents = "^0.6"
+langchain-agentcore-codeinterpreter = "^0.0.5"
+bedrock-agentcore = "^1.17.0"
 
 
 [tool.poetry.extras]
@@ -107,7 +110,7 @@ module = ["langdetect.*", "tiktoken.*", "bs4.*", "jose", "jose.*", "boto3", "bot
 ignore_missing_imports = true
 
 [[tool.mypy.overrides]]
-module = ["prefect", "prefect.*", "entrypoint", "fitz", "twikit", "twikit.*", "yt_dlp", "yt_dlp.*", "google", "google.*", "apprise", "apprise.*"]
+module = ["prefect", "prefect.*", "entrypoint", "fitz", "twikit", "twikit.*", "yt_dlp", "yt_dlp.*", "google", "google.*", "apprise", "apprise.*", "deepagents", "deepagents.*", "langchain_agentcore_codeinterpreter", "langchain_agentcore_codeinterpreter.*", "bedrock_agentcore", "bedrock_agentcore.*"]
 ignore_missing_imports = true
 
 [[tool.mypy.overrides]]

{pulse_engine-0.2.16 → pulse_engine-0.2.17}/src/pulse_engine/adapters/__init__.py

@@ -5,6 +5,7 @@ from .batcher import BatcherAdapter
 from .digital_news import DigitalNewsAdapter
 from .digital_news_metadata import DigitalNewsMetadataAdapter
 from .exceptions import SitemapDiscoveryError
+from .mart_export import MartExportAdapter
 from .models import (
     ArticleContent,
     ArticleResult,
@@ -19,7 +20,9 @@ from .models import (
     VideoMetadata,
     VideoResult,
 )
+from .opensearch_sql import OpenSearchSqlAdapter
 from .opensearch_storage import OpenSearchStorageAdapter
+from .report_generator import ReportGeneratorAdapter
 from .speech_content import SpeechContentAdapter
 from .speech_metadata import SpeechMetadataAdapter
 from .transcription import TranscriptionService, TranscriptionSource
@@ -31,6 +34,9 @@ __all__ = [
     # Utilities
     "BatcherAdapter",
     "OpenSearchStorageAdapter",
+    "OpenSearchSqlAdapter",
+    "MartExportAdapter",
+    "ReportGeneratorAdapter",
     # Digital news
     "DigitalNewsMetadataAdapter",
     "DigitalNewsAdapter",

pulse_engine-0.2.17/src/pulse_engine/adapters/mart_export.py

@@ -0,0 +1,122 @@
+"""MartExportAdapter — query OpenSearch via SQL and stage the rows as an S3 mart.
+
+This is the upstream half of reporting: it runs an OpenSearch SQL query and writes
+the rows to ``s3://<bucket>/tenants/<tenant_id>/<prefix>/<mart_name>.json``. The
+``report_generator`` run then reads those fixtures back.
+
+The output is **tenant-scoped** to mirror the engine's fixture-reader layout
+(``reporting.wiring.make_reader`` reads ``tenants/<tenant_id>/fixtures/latest/``), so
+the mart must be written under the same tenant segment or the report finds nothing.
+The tenant is passed in by the caller (derived from the authenticated token) — it is
+never taken from a config arg, so it can't drift from the tenant the report runs as.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+
+from pulse_engine.adapters.opensearch_sql import OpenSearchSqlAdapter
+
+logger = logging.getLogger(__name__)
+
+# tenant_id becomes an S3 key segment; keep it to a safe pattern (no slashes / ``..``).
+_SAFE_TENANT = re.compile(r"^[A-Za-z0-9._-]+$")
+# run_date also becomes a key segment; require a strict ISO date (no slashes / ``..``).
+_ISO_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+class MartExportAdapter:
+    """Run an OpenSearch SQL query and stage the result JSON at a tenant-scoped S3 key.
+
+    Args:
+        os_url: OpenSearch endpoint URL.
+        os_username: OpenSearch HTTP basic auth username (optional).
+        os_password: OpenSearch HTTP basic auth password (optional).
+        use_ssl: Whether the OpenSearch client uses SSL. Default True.
+        verify_certs: Whether the OpenSearch client verifies certs. Default True.
+        s3_client: boto3 S3 client. Defaults to ``boto3.client("s3")`` (from the
+            ambient VM/compute role) on first use; inject a fake in tests.
+
+    Usage::
+
+        adapter = MartExportAdapter(os_url="https://...", os_username="admin")
+        result = await adapter.export(
+            sql="SELECT source AS platform, COUNT(*) AS posts FROM sm_posts GROUP BY 1",
+            mart_name="mart_engagement",
+            bucket="dev-pulse-engine-artifacts",
+            tenant_id="org-123",
+            run_date="2026-07-09",
+        )
+        # key -> tenants/org-123/fixtures/2026-07-09/mart_engagement.json
+    """
+
+    def __init__(
+        self,
+        os_url: str,
+        os_username: str = "",
+        os_password: str = "",
+        use_ssl: bool = True,
+        verify_certs: bool = True,
+        s3_client: Any | None = None,
+    ) -> None:
+        self._sql = OpenSearchSqlAdapter(
+            url=os_url,
+            username=os_username,
+            password=os_password,
+            use_ssl=use_ssl,
+            verify_certs=verify_certs,
+        )
+        self._s3_client = s3_client
+
+    def _s3(self) -> Any:
+        if self._s3_client is None:
+            import boto3
+
+            self._s3_client = boto3.client("s3")
+        return self._s3_client
+
+    @staticmethod
+    def _resolve_prefix(run_date: str | None, prefix: str | None) -> str:
+        """Prefix precedence: explicit ``prefix`` > ``fixtures/{run_date}`` > latest."""
+        if prefix:
+            return prefix.strip("/")
+        if run_date:
+            if not _ISO_DATE.fullmatch(run_date):
+                raise ValueError(f"run_date must be ISO YYYY-MM-DD: {run_date!r}")
+            return f"fixtures/{run_date}"
+        return "fixtures/latest"
+
+    async def export(
+        self,
+        *,
+        sql: str,
+        mart_name: str,
+        bucket: str,
+        tenant_id: str,
+        run_date: str | None = None,
+        prefix: str | None = None,
+    ) -> dict[str, Any]:
+        """Query OpenSearch and stage the mart JSON in S3.
+
+        Returns:
+            {"mart_key": str, "rows": int, "bucket": str}
+        """
+        if not _SAFE_TENANT.fullmatch(tenant_id):
+            raise ValueError(f"unsafe tenant_id for S3 path: {tenant_id!r}")
+        resolved = self._resolve_prefix(run_date, prefix)
+
+        rows = await self._sql.query(sql)
+
+        # Tenant-scoped key mirrors the engine's fixture reader layout.
+        key = f"tenants/{tenant_id}/{resolved}/{mart_name}.json"
+        self._s3().put_object(
+            Bucket=bucket,
+            Key=key,
+            Body=json.dumps(rows).encode("utf-8"),
+            ContentType="application/json",
+        )
+        logger.info("mart_export: %d rows -> s3://%s/%s", len(rows), bucket, key)
+        return {"mart_key": key, "rows": len(rows), "bucket": bucket}

pulse_engine-0.2.17/src/pulse_engine/adapters/opensearch_sql.py

@@ -0,0 +1,78 @@
+"""OpenSearchSqlAdapter — run OpenSearch SQL-plugin queries and map rows to dicts.
+
+Wraps the OpenSearch SQL plugin (``POST /_plugins/_sql``) so products don't hand-roll
+the HTTP call. Connection config is caller-supplied (constructor args), mirroring
+``OpenSearchStorageAdapter`` — both wrap ``opensearchpy.AsyncOpenSearch``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class OpenSearchSqlAdapter:
+    """Run SQL against the OpenSearch SQL plugin and return rows as dicts.
+
+    Args:
+        url: OpenSearch endpoint URL.
+        username: HTTP basic auth username (optional).
+        password: HTTP basic auth password (optional).
+        use_ssl: Whether to use SSL. Default True.
+        verify_certs: Whether to verify SSL certificates. Default True.
+        timeout: Per-request timeout in seconds. Default 60.
+
+    Usage::
+
+        adapter = OpenSearchSqlAdapter(url="https://...", username="admin")
+        rows = await adapter.query(
+            "SELECT source AS platform, COUNT(*) AS posts FROM sm_posts GROUP BY source"
+        )
+        # rows == [{"platform": "tweet", "posts": 42}, ...]
+    """
+
+    def __init__(
+        self,
+        url: str,
+        username: str = "",
+        password: str = "",
+        use_ssl: bool = True,
+        verify_certs: bool = True,
+        timeout: int = 60,
+    ) -> None:
+        self._url = url.rstrip("/")
+        self._username = username
+        self._password = password
+        self._use_ssl = use_ssl
+        self._verify_certs = verify_certs
+        self._timeout = timeout
+
+    def _client(self) -> Any:
+        from opensearchpy import AsyncOpenSearch
+
+        kwargs: dict[str, Any] = {
+            "hosts": [self._url],
+            "use_ssl": self._use_ssl,
+            "verify_certs": self._verify_certs,
+            "timeout": self._timeout,
+        }
+        if self._username and self._password:
+            kwargs["http_auth"] = (self._username, self._password)
+        return AsyncOpenSearch(**kwargs)
+
+    async def query(self, sql: str) -> list[dict[str, Any]]:
+        """Run ``sql`` via the SQL plugin; map schema+datarows to a list of dicts.
+
+        Prefers each column's AS-alias so mart columns stay clean (``likes`` rather
+        than ``SUM(metadata.like_count)``), falling back to the raw column name.
+        """
+        async with self._client() as client:
+            body = await client.transport.perform_request(
+                "POST", "/_plugins/_sql", body={"query": sql}
+            )
+        cols = [c.get("alias") or c["name"] for c in body.get("schema", [])]
+        rows = [dict(zip(cols, row, strict=False)) for row in body.get("datarows", [])]
+        logger.info("opensearch_sql: %d rows", len(rows))
+        return rows

pulse_engine-0.2.17/src/pulse_engine/adapters/report_generator.py

@@ -0,0 +1,130 @@
+"""ReportGeneratorAdapter — run skill-driven report generation in-process.
+
+Report generation is a **library function call**, not a REST round-trip: this adapter
+assembles a ``ReportingService`` from engine ``Settings`` and runs it directly in the
+caller's process. Product modules call ``generate(...)`` the same way they call any
+other adapter (``TwitterAdapter.fetch()`` etc.) — there is no ``/reports/generate`` API
+in the path.
+
+The heavy collaborators are reached directly from the caller's environment:
+    * skills catalog  -> Postgres (``DATABASE_URL``)
+    * report artifact -> S3 (``REPORTS_S3_BUCKET`` / ``SKILLS_S3_BUCKET``)
+    * agent LLM       -> ``PULSE_LLM_PROVIDER`` + ``PULSE_LLM_API_KEY``
+    * sandbox         -> a Lambda microVM provisioned via the engine's AWS control-plane
+                         config in ``Settings`` (``MICROVM_*``); the caller's IAM role
+                         must be entitled to the ``lambda-microvms`` service.
+
+So the microVM configuration stays engine-owned (``Settings``) while the generation
+itself is a plain in-process call.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date
+from typing import Any, cast
+
+logger = logging.getLogger(__name__)
+
+
+class ReportGeneratorAdapter:
+    """Assemble a ReportingService from env and run report generation in-process.
+
+    Args:
+        settings: Engine ``Settings``. Defaults to ``Settings()`` (loaded from env).
+        s3_client: boto3 S3 client. Defaults to ``boto3.client("s3", region=...)``.
+        db_session_factory: async SQLAlchemy sessionmaker for the skills catalog.
+            Defaults to one built from ``settings.database_url``.
+
+    Usage::
+
+        adapter = ReportGeneratorAdapter()
+        result = await adapter.generate(
+            run_date="2026-07-09",
+            prompt="Produce the daily report for {run_date}.",
+            tenant_id="org-123",
+        )
+        # result["artifact_url"] ->
+        #   "s3://.../snapshots/org-123/2026-07-09/report-20260709T101500Z.html"
+    """
+
+    def __init__(
+        self,
+        settings: Any | None = None,
+        s3_client: Any | None = None,
+        db_session_factory: Any | None = None,
+    ) -> None:
+        if settings is None:
+            from pulse_engine.config import Settings
+
+            settings = Settings()
+        self._settings = settings
+        self._s3_client = s3_client
+        self._db_session_factory = db_session_factory
+
+    def _build_service(self) -> Any:
+        import boto3
+
+        from pulse_engine.database import build_async_engine, build_session_factory
+        from pulse_engine.reporting.wiring import build_reporting_service
+
+        s3_client = self._s3_client
+        if s3_client is None:
+            s3_client = boto3.client("s3", region_name=self._settings.aws_region)
+
+        db_session_factory = self._db_session_factory
+        if db_session_factory is None:
+            if not self._settings.database_url:
+                raise RuntimeError(
+                    "DATABASE_URL is required for report generation "
+                    "(the skills catalog is read from Postgres)"
+                )
+            engine = build_async_engine(self._settings.database_url)
+            db_session_factory = build_session_factory(engine)
+
+        return build_reporting_service(
+            settings=self._settings,
+            s3_client=s3_client,
+            db_session_factory=db_session_factory,
+        )
+
+    async def generate(
+        self,
+        *,
+        run_date: str | date,
+        prompt: str,
+        tenant_id: str,
+        skill_ref: dict[str, Any] | None = None,
+        marts: list[str] | None = None,
+        artifact_type: str | None = None,
+    ) -> dict[str, Any]:
+        """Run report generation for ``tenant_id``; return the ReportResult as a dict.
+
+        ``run_date`` and ``prompt`` are required. ``skill_ref`` ({skill_id,
+        version_number?}) pins a skill; omit it to let the engine's agent auto-select
+        from the tenant's active catalog. ``marts`` (list of mart-name stems) restricts
+        which staged fixtures the agent may read; omit for all. ``artifact_type``
+        (html|pdf|docx|xlsx|pptx) pins the output format; omit to let the agent decide.
+        The fixture source is derived from ``tenant_id`` inside the service — never
+        caller-supplied.
+        """
+        from pulse_engine.reporting.models import ReportRequest
+
+        # model_validate coerces run_date (str->date), skill_ref (dict->SkillRef),
+        # and validates artifact_type against the Literal — all from a plain dict.
+        request = ReportRequest.model_validate(
+            {
+                "run_date": run_date,
+                "prompt": prompt,
+                "skill_ref": skill_ref,
+                "marts": marts,
+                "artifact_type": artifact_type,
+            }
+        )
+
+        service = self._build_service()
+        result = await service.generate_report(request, tenant_id)
+        logger.info(
+            "report_generator: tenant=%s artifact=%s", tenant_id, result.artifact_url
+        )
+        return cast(dict[str, Any], result.model_dump(mode="json"))

{pulse_engine-0.2.16 → pulse_engine-0.2.17}/src/pulse_engine/config.py

@@ -91,6 +91,7 @@ class Settings(BaseSettings):
     pulse_llm_model: str = "gpt-4o-mini"
     pulse_llm_api_key: str = ""
     pulse_llm_temperature: float = 0.0
+    pulse_llm_max_tokens: int = 8192  # output cap; rich HTML reports need headroom
     pulse_default_chunk_size: int = 512
     pulse_default_chunk_strategy: str = "token_count"
     pulse_job_callback_timeout: int = 10
@@ -100,6 +101,25 @@ class Settings(BaseSettings):
     pulse_engine_url: str = ""  # public URL containers use to call back
     pulse_job_token_secret: str = ""  # HMAC secret for job-scoped JWTs
     pulse_s3_bucket: str = ""  # S3 bucket for inter-stage data
+
+    # Reporting / skills
+    reports_s3_bucket: str = ""  # S3 bucket for report fixtures + rendered artifacts
+    skills_s3_bucket: str = ""  # S3 bucket for skill files (defaults to reports bucket)
+
+    # Lambda MicroVM sandbox (ephemeral per-run execution env; see DD-054).
+    microvm_region: str = ""  # AWS region for the microVM (defaults to aws_region)
+    microvm_image_identifier: str = ""  # built MicroVM image name/ARN to run from
+    microvm_ingress_connector: str = ""  # ARN; blank → managed ALL_INGRESS for region
+    microvm_egress_connector: str = ""  # ARN; blank → managed INTERNET_EGRESS
+    microvm_idle_max_seconds: int = 900  # suspend after this idle window
+    microvm_suspended_seconds: int = 300  # terminate after this long suspended
+    microvm_auth_token_ttl_minutes: int = 30  # endpoint auth-token lifetime
+    microvm_ready_timeout_seconds: int = 120  # max wait for RUNNING state
+    microvm_log_group: str = ""  # CloudWatch log group for VM stdout; blank → off
+    microvm_execution_role_arn: str = ""  # role the VM assumes; required for logging
+
+    report_agent_max_steps: int = 80  # ainvoke recursion_limit
+    report_agent_timeout_seconds: float = 600.0
     pulse_chain_grace_period_seconds: int = (
         300  # seconds before auto-triggering next stage
     )

{pulse_engine-0.2.16 → pulse_engine-0.2.17}/src/pulse_engine/processor/llm/provider.py

@@ -12,6 +12,7 @@ def get_llm(
     model: str | None = None,
     api_key: str | None = None,
     temperature: float | None = None,
+    max_tokens: int | None = None,
 ) -> Any:
     """Return a LangChain chat model, using Settings as defaults.
 
@@ -28,6 +29,8 @@ def get_llm(
     api_key = api_key or settings.pulse_llm_api_key
     if temperature is None:
         temperature = settings.pulse_llm_temperature
+    if max_tokens is None:
+        max_tokens = settings.pulse_llm_max_tokens
 
     if provider == "openai":
         from langchain_openai import ChatOpenAI
@@ -36,14 +39,17 @@ def get_llm(
             model=model,
             api_key=api_key,  # type: ignore[arg-type]
             temperature=temperature,
+            max_tokens=max_tokens,  # type: ignore[call-arg]
         )
     elif provider == "anthropic":
         from langchain_anthropic import ChatAnthropic
 
+        # The Claude 5 family deprecates `temperature` (400 if sent); omit it and
+        # let Anthropic use its default. Older models are unaffected by omission.
         _llm_instance = ChatAnthropic(  # type: ignore[call-arg]
             model=model,
             api_key=api_key,  # type: ignore[arg-type]
-            temperature=temperature,
+            max_tokens=max_tokens,
         )
     else:
         msg = f"Unsupported LLM provider: {provider!r}. Use 'openai' or 'anthropic'."

pulse_engine-0.2.17/src/pulse_engine/reporting/__init__.py

@@ -0,0 +1,6 @@
+"""Skill-driven report generation subsystem.
+
+A deepagents agent (bound to a microVM sandbox backend) reads mart fixtures and
+a report skill, then writes a report artifact to S3. See
+specs/milestone_reporting_v1_spec.md.
+"""

pulse_engine-0.2.17/src/pulse_engine/reporting/agent.py

@@ -0,0 +1,41 @@
+"""Build the deepagents report agent bound to a microVM sandbox backend.
+
+Skill selection uses the platform Agent Skills pattern (DD-055): the
+``<available_skills>`` catalog is injected into the system prompt and the agent
+drives progressive disclosure through our ``activate_skill`` / ``read_skill_file``
+/ ``execute_skill_script`` tools — so we do **not** use deepagents'
+``SkillsMiddleware`` or pre-sync skills. ``create_deep_agent(backend=…)`` still
+supplies FilesystemMiddleware (write_file/read_file/execute) for building the
+report artifact and running skill scripts in the sandbox.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from deepagents import create_deep_agent
+
+from pulse_engine.reporting.prompts import BASE_SYSTEM_PROMPT
+
+
+def build_report_agent(
+    model: Any,
+    tools: list[Any],
+    backend: Any,
+    catalog_suffix: str,
+    *,
+    _create: Any = create_deep_agent,
+) -> Any:
+    """Return a compiled deepagents agent for report generation.
+
+    ``model`` is a LangChain chat model (e.g. from ``get_llm()``) or a
+    ``provider:model`` string. ``tools`` are the report + skill tools; ``backend``
+    is the sandbox backend; ``catalog_suffix`` is the ``<available_skills>``
+    section appended to the base system prompt.
+    """
+    return _create(
+        model=model,
+        tools=tools,
+        system_prompt=BASE_SYSTEM_PROMPT + catalog_suffix,
+        backend=backend,
+    )

pulse_engine-0.2.17/src/pulse_engine/reporting/fixtures.py

@@ -0,0 +1,60 @@
+"""Read mart_export JSON fixtures from S3.
+
+One file per mart (``<name>.json`` holding a JSON array of row objects). The
+mart name is the filename stem. ``list()`` returns a self-describing summary
+(name, row_count, fields) per mart and is safe on empty (0-row) fixtures.
+
+An optional ``names`` allowlist restricts which marts are exposed: with it set,
+only those named fixtures are listed/readable (the agent sees a deterministic
+input set); without it, every ``.json`` under the prefix is exposed.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from typing import Any
+
+
+class MartFixtureReader:
+    def __init__(
+        self,
+        s3_client: Any,
+        bucket: str,
+        prefix: str,
+        names: Iterable[str] | None = None,
+    ) -> None:
+        self._s3 = s3_client
+        self._bucket = bucket
+        self._prefix = prefix.rstrip("/") + "/"
+        self._names = set(names) if names is not None else None
+
+    def _keys(self) -> dict[str, str]:
+        resp = self._s3.list_objects_v2(Bucket=self._bucket, Prefix=self._prefix)
+        out: dict[str, str] = {}
+        for obj in resp.get("Contents", []):
+            key = obj["Key"]
+            if key.endswith(".json"):
+                name = key.rsplit("/", 1)[-1][: -len(".json")]
+                if self._names is not None and name not in self._names:
+                    continue  # restrict to the requested marts
+                out[name] = key
+        return out
+
+    def _rows(self, key: str) -> list[dict[str, Any]]:
+        body = self._s3.get_object(Bucket=self._bucket, Key=key)["Body"].read()
+        data = json.loads(body)
+        return data if isinstance(data, list) else [data]
+
+    def summaries(self) -> list[dict[str, Any]]:
+        """One {name, row_count, fields} summary per mart (empty-safe)."""
+        result: list[dict[str, Any]] = []
+        for name, key in sorted(self._keys().items()):
+            rows = self._rows(key)
+            fields = list(rows[0].keys()) if rows else []  # never index [0] on empty
+            result.append({"name": name, "row_count": len(rows), "fields": fields})
+        return result
+
+    def read(self, name: str) -> list[dict[str, Any]]:
+        key = self._keys().get(name)
+        return self._rows(key) if key else []

pulse_engine-0.2.17/src/pulse_engine/reporting/models.py

@@ -0,0 +1,62 @@
+"""Pydantic models for the reporting subsystem."""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+# The artifact formats the reporting pipeline can emit (mirrors wiring._CONTENT_TYPES).
+ArtifactType = Literal["html", "pdf", "docx", "xlsx", "pptx"]
+
+
+class SkillRef(BaseModel):
+    """Which skill (and optionally which pinned version) drives the report."""
+
+    skill_id: str
+    version_number: int | None = None  # None => active version
+
+
+class ReportRequest(BaseModel):
+    run_date: date
+    # None => auto-select: the agent picks from the full active-skill catalog.
+    # Set => pin: only that skill is offered (deterministic for scheduled runs).
+    skill_ref: SkillRef | None = None
+    prompt: str = Field(
+        ...,
+        min_length=1,
+        description="Kickoff user message from config; {run_date} is templated in",
+    )
+    # None => the agent reads every mart fixture staged under the tenant prefix.
+    # Set => only these named marts are exposed to the agent (deterministic inputs).
+    marts: list[str] | None = Field(
+        default=None,
+        description="Mart-name stems to expose (e.g. ['mart_top_authors']); None = all",
+    )
+    # None => the agent chooses the output format. Set => pin it: the format is
+    # injected into the kickoff and the run fails if the agent emits a different type.
+    artifact_type: ArtifactType | None = Field(
+        default=None,
+        description="Output format (html|pdf|docx|xlsx|pptx); None = agent decides",
+    )
+    # NOTE: the fixture source is derived server-side from the authenticated tenant
+    # (see wiring.make_reader). It is deliberately NOT caller-supplied — accepting a
+    # path here was a cross-tenant read (IDOR): org A could point at org B's prefix.
+
+    @field_validator("marts")
+    @classmethod
+    def _non_empty_marts(cls, v: list[str] | None) -> list[str] | None:
+        if v is not None and (not v or not all(isinstance(m, str) and m for m in v)):
+            raise ValueError("marts must be a non-empty list of non-empty strings")
+        return v
+
+
+class ReportResult(BaseModel):
+    artifact_url: str
+    artifact_type: str  # "html" (v1 default) | "pdf" | "docx" | "xlsx" | "pptx"
+    skill_id: str
+    skill_version: int | None
+    tokens: int
+    tool_calls: int
+    run_date: date

pulse_engine-0.2.17/src/pulse_engine/reporting/prompts.py

@@ -0,0 +1,18 @@
+"""Static, generic prompts for the reporting agent.
+
+The base system prompt carries *behaviour only* — never report logic (that lives
+in the skill). The kickoff *user* prompt comes from pipeline config
+(``ReportRequest.prompt``).
+"""
+
+BASE_SYSTEM_PROMPT = (
+    "You are a report-generation agent running with a sandboxed filesystem and "
+    "shell. Available skills are listed in the <available_skills> catalog; when "
+    "the task matches one, call activate_skill with its id to load its full "
+    "instructions, then follow them. Read mart data with list_marts / read_mart, "
+    "load referenced skill files with read_skill_file, and run any scripts the "
+    "skill provides with execute_skill_script. Build one complete report artifact "
+    "(write it to a file under /work with write_file), then call write_report "
+    "exactly once with its path. Do not call write_report until the artifact is "
+    "complete."
+)