Description

Logs/metrics → Python statistics → LLM interpretation → Notion reports. Use when: generating daily/weekly/monthly operational insights from AI system logs, p...

README (SKILL.md)

Last used: 2026-03-24 Memory references: 18 Status: Active

insight-engine

Name: Insight Engine
Author: nissan

Data-driven insights from operational logs: collect → stats → LLM interpretation → Notion.

Architecture

collect (Python stats only)
  ├── Langfuse OTEL traces/scores/observations
  ├── OpenClaw/gateway logs
  ├── Git activity
  └── Control plane scores
↓
build_*_data_packet()  ← all stats computed in Python before LLM call
↓
call_claude(system_prompt, structured_json)  ← LLM interprets, doesn't compute
↓
write_*_reflection() → Notion

See references/architecture.md for full design rationale.

Quick start

# Install deps
pip install anthropic requests pyyaml

# Configure
cp scripts/config/analyst.yaml.example config/analyst.yaml
# Edit config/analyst.yaml — set langfuse URL, notion IDs, model choices

# Dry run (local Ollama, no Notion write)
python3 scripts/src/engine.py --mode daily --dry-run

# Print data packet + prompt to stdout (for agent consumption, no API calls)
python3 scripts/src/engine.py --mode daily --data-only

# Live run
python3 scripts/src/engine.py --mode daily
python3 scripts/src/engine.py --mode weekly
python3 scripts/src/engine.py --mode monthly

Required env vars

ANTHROPIC_API_KEY=sk-ant-...    # Anthropic API key
NOTION_API_KEY=secret_...       # Notion integration token
LANGFUSE_BASE_URL=http://localhost:3100   # Langfuse server URL
LANGFUSE_PUBLIC_KEY=pk-lf-...   # Langfuse public key
LANGFUSE_SECRET_KEY=sk-lf-...   # Langfuse secret key
NOTION_ROOT_PAGE_ID=\x3Cuuid>      # Root Notion page for reports
NOTION_DAILY_DB_ID=\x3Cuuid>       # Notion database for daily entries

Or configure in config/analyst.yaml.

Key design principles

Stats before LLM — Python computes all numbers. The LLM interprets, doesn't aggregate.
Citation-enforcing prompts — System prompts require every claim to cite a specific number.
No hallucinated trends — \x3C 7 data points → report "insufficient data (n=X)"
Dry-run mode — Uses local Ollama (free) to preview output; skip Notion write.
Data-only mode — Outputs the full data packet + prompts for agent/subagent use.

Cron setup (LaunchAgent example)

\x3C!-- ~/Library/LaunchAgents/com.yourname.insight-engine-daily.plist -->
\x3Ckey>StartCalendarInterval\x3C/key>
\x3Cdict>
  \x3Ckey>Hour\x3C/key>\x3Cinteger>23\x3C/integer>
  \x3Ckey>Minute\x3C/key>\x3Cinteger>0\x3C/integer>
\x3C/dict>
\x3Ckey>ProgramArguments\x3C/key>
\x3Carray>
  \x3Cstring>/usr/bin/python3\x3C/string>
  \x3Cstring>/path/to/insight-engine/scripts/src/engine.py\x3C/string>
  \x3Cstring>--mode\x3C/string>\x3Cstring>daily\x3C/string>
\x3C/array>

Extending to new data sources

Add a collector in scripts/src/collectors/:

Create my_source.py with a fetch_*() function returning a plain dict
Import and call it in build_daily_data_packet() in engine.py
Reference the new key in prompts/daily_analyst.md under "Data sources"

This skill does what it says (collect local logs, compute stats, ask an LLM to interpret, and write a Notion report), but several practical cautions: - Metadata is incomplete: although only ANTHROPIC_API_KEY and NOTION_API_KEY are declared as required, the tool uses many other env vars (LANGFUSE_PUBLIC_KEY / SECRET_KEY, NOTION_ROOT_PAGE_ID / NOTION_DAILY_DB_ID, OPENCLAW log/memory dirs, GIT_REPOS, CP_API_URL, OLLAMA_*). Do not supply extra secrets unless you intend the skill to access those services. - Inspect what will be sent to the LLM/Notion: run the tool in data-only mode (python3 scripts/src/engine.py --mode daily --data-only) or dry-run to print the JSON data packet and the system prompt so you can confirm no sensitive raw logs, secrets, or private repo contents are included. The code truncates memory_context to 6000 chars but can still contain sensitive text. - Limit scope of sources: set GIT_REPOS to explicit repository paths you trust (avoid defaulting to current dir), and point OPENCLAW_LOG_DIR and OPENCLAW_MEMORY_DIR to directories that don't contain secrets. If you don't use Langfuse, avoid setting LANGFUSE_* secrets — the code will attempt calls if configured. - Notion token scope: create a Notion integration with minimal page/database access (not full workspace admin) so pages created/modified are limited to a specific area. - Secrets and network: Anthropic and Notion API keys are used to send data off-host. If you can't risk any outbound transmission of certain content, don't run live mode. Dry-run with a local Ollama is safer for previews. - Prompt review: because the skill includes assertive system prompts (the scanner flagged a system-prompt pattern), read scripts/prompts/*.md to ensure no prompt instructs the model to exfiltrate data beyond producing the report. If after these checks the data sources and token scopes look appropriate, the skill appears functionally coherent. If you are unsure which env vars to set or what data will be included, treat this as a red flag and test in an isolated environment first.

Capability Analysis

Type: OpenClaw Skill Name: insight-engine Version: 1.0.4 The 'insight-engine' skill bundle is a legitimate tool designed for operational log analysis and reporting. It collects data from local sources (Git history, OpenClaw logs) and external APIs (Langfuse, Control Plane), aggregates statistics in Python, and uses an LLM (Claude or Ollama) to generate narrative reports which are then written to the user's Notion workspace. The code follows its stated purpose, implements clear separation of concerns, and includes security-conscious features like local data processing and dry-run modes. No evidence of malicious intent, unauthorized data exfiltration, or harmful prompt injection was found across the codebase (engine.py, collectors, and prompts).

Capability Assessment

ℹ Purpose & Capability

The name/description (logs → local Python stats → LLM → Notion) matches the included code: collectors, statistical aggregation, LLM calls, and Notion writer are present. Minor mismatch: registry metadata lists required binaries as python3 and ollama — ollama is used only for the dry-run local path (call_ollama), while live runs use Anthropic. The metadata's declared required env vars only list ANTHROPIC_API_KEY and NOTION_API_KEY, but the SKILL.md and code use many additional env vars (LANGFUSE_* keys, NOTION_ROOT_PAGE_ID, NOTION_DAILY_DB_ID, OPENCLAW_* dirs, GIT_REPOS, CP_API_URL, OLLAMA_BASE_URL, etc.). The functional capability is plausible, but the metadata under-declares environment requirements.

⚠ Instruction Scope

Runtime instructions and code read local gateway logs and daily memory markdowns, run git commands on repo paths (defaults to current dir), call Langfuse and Control Plane endpoints, build a JSON data packet (including memory_context truncated to 6000 chars) and send that packet to an LLM (Anthropic or local Ollama) and then write the LLM output to the user's Notion workspace. This scope is consistent with the stated purpose but broad: it can access arbitrary repo histories and local memory files and include their content in requests to external services — verify you want those sources transmitted to Anthropic/Notion.

✓ Install Mechanism

No installation spec is provided (instruction-only). All code is included in the skill bundle, and there are no remote downloads or extract steps. This is low-risk from an install vector perspective.

⚠ Credentials

Declared required env vars (metadata) are only ANTHROPIC_API_KEY and NOTION_API_KEY, but the SKILL.md and code rely on many additional env vars and secrets (LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, NOTION_ROOT_PAGE_ID, NOTION_DAILY_DB_ID, OPENCLAW_* directories, GIT_REPOS, CP_API_URL, OLLAMA_MODEL/BASE_URL). Some of these are sensitive (Langfuse secret key, Notion integration token, Anthropic API key). The fact that the metadata omits these other variables is a mismatch and increases the chance a user supplies sensitive secrets without realizing which ones are used.

✓ Persistence & Privilege

The skill is not marked always:true and does not request elevated platform privileges. It will write to the user's Notion workspace (expected). It can create Notion databases/pages in the user's workspace when needed. Autonomous invocation is allowed by default (not flagged here), which combined with the broad data-access scope is something to consider but is not unusual for skills.

Version History

v1.0.4

Add security_notes: LLM calls use user's own API keys, raw logs stay local, only structured packets sent to LLM

v1.0.3

- Added a security_notes field to metadata in SKILL.md, clarifying the use of "system prompt" and '_KEY' patterns. - Bumped version to 1.0.3 in SKILL.md. - No code or behavior changes; documentation/metadata only.

v1.0.2

Added primaryEnv, ollama in bins, full network disclosure

v1.0.1

- Added a metadata section to SKILL.md with OpenClaw-specific requirements and network configuration. - No changes to code or core functionality; documentation only update.

v1.0.0

Initial release of insight-engine. - Automates the pipeline from operational logs to data-driven Notion reports. - Collects raw data (Langfuse, gateway logs, Git, control scores), computes all stats in Python, and submits structured packets to an LLM for interpretation. - Enforces citation of specific data in every insight, preventing hallucinated claims and reporting insufficient data when necessary. - Supports dry-run and data-only modes for previewing output and agent consumption. - Easy cron integration and modular collector extension for new data sources. - Full setup and configuration details included.

Metadata

Slug insight-engine

Version 1.0.4

License MIT-0

All-time Installs 1

Active Installs 1

Total Versions 5

Frequently Asked Questions

What is Insight Engine?

Logs/metrics → Python statistics → LLM interpretation → Notion reports. Use when: generating daily/weekly/monthly operational insights from AI system logs, p... It is an AI Agent Skill for Claude Code / OpenClaw, with 512 downloads so far.

How do I install Insight Engine?

Run "/install insight-engine" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Insight Engine free?

Yes, Insight Engine is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Insight Engine support?

Insight Engine is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Insight Engine?

It is built and maintained by Nissan Dookeran (@nissan); the current version is v1.0.4.

More Skills

Insight Engine