@c3-oss/prosa 0.3.2 → 0.5.0

package/README.md

@@ -19,6 +19,7 @@ original raw data.
 - Lists and filters sessions by source and timestamp.
 - Exports individual sessions as Markdown.
 - Exports canonical tables to Parquet for DuckDB analytics.
+- Runs built-in analytics reports over Parquet with DuckDB.
 - Provides an Ink-based terminal UI for browsing sessions and search results.
 - Serves a read-only MCP server over the local bundle for agent memory access.
 
@@ -55,6 +56,7 @@ prosa search "package.json"
 prosa export session <session-id> --format markdown --out session.md
 prosa export parquet
 prosa query duckdb "select source_tool, count(*) from sessions group by 1"
+prosa analytics tools --refresh
 prosa tui
 prosa mcp serve
 ```
@@ -93,12 +95,10 @@ Imports are idempotent for already-seen source files. Each import reports counts
 for source files, sessions, messages, tool calls, tool results, artifacts,
 edges, and errors.
 
-For large imports, you can defer FTS5 index updates and rebuild later:
-
-```bash
-prosa compile codex --defer-index
-prosa index fts5
-```
+`prosa compile` always disables FTS5 triggers during the import loop and
+rebuilds the FTS5 index in bulk at the end (mirroring how the Tantivy sidecar
+is rebuilt). Sidecars stay in sync without a manual step. For recovery, the
+standalone `prosa index fts5` command is still available.
 
 ## CLI reference
 
@@ -147,7 +147,6 @@ Options:
 |---|---|
 | `--sessions-path <path>` | Root of the selected provider's session history |
 | `--store <path>` | Bundle directory |
-| `--defer-index` | Skip immediate FTS5 updates; run `prosa index fts5` later |
 | `--verbose` | Emit debug logs during compilation |
 | `--json-logs` | Emit raw JSON logs instead of pretty logs |
 
@@ -165,8 +164,9 @@ prosa index fts5
 prosa index tantivy
 ```
 
-`fts5` is the default SQLite full-text index. It is updated during normal
-imports unless `--defer-index` is used.
+`fts5` is the default SQLite full-text index. `prosa compile` rebuilds it in
+bulk at the end of every import; `prosa index fts5` is a standalone recovery
+path that repopulates the index from `search_docs`.
 
 `tantivy` is an optional sidecar search index. Build it before searching with
 `--engine tantivy`:
@@ -297,6 +297,40 @@ prosa query duckdb "select count(*) as n from sessions" --output-format json
 prosa query duckdb "select * from sessions limit 10" --output-format csv
 ```
 
+`prosa query duckdb` also exposes derived analytics views:
+
+```text
+session_facts, tool_usage_facts, error_facts, model_usage, project_activity
+```
+
+See [`docs/recipes/duckdb.md`](./docs/recipes/duckdb.md) for copy-pasteable
+queries.
+
+### `prosa analytics`
+
+Run built-in reports over exported Parquet files:
+
+```bash
+prosa analytics sessions --refresh
+prosa analytics tools --source codex
+prosa analytics errors --output-format json
+prosa analytics models --since 2026-01-01
+prosa analytics projects --project /Users/me/app
+```
+
+Reports require Parquet files. Add `--refresh` to export Parquet before running
+the report. All reports support `--store`, `--parquet-dir`, `--source`,
+`--since`, `--until`, `--limit`, and `--output-format table|json|csv`.
+
+Additional filters:
+
+```bash
+prosa analytics tools --tool-name Bash --errors-only
+prosa analytics tools --canonical-type shell
+prosa analytics errors --category tool_result
+prosa analytics models --model gpt-5.4
+```
+
 ### `prosa tui`
 
 Open the Ink-based interactive explorer:
@@ -359,18 +393,16 @@ By default, HTTP mode listens at:
 http://127.0.0.1:7331/mcp
 ```
 
-Registered MCP tools include:
+Registered MCP tools (six in total):
 
 | Tool | Purpose |
 |---|---|
-| `list_sessions` | List recent sessions with optional source/date filters |
-| `get_session` | Return metadata and timeline events for one session |
-| `search_sessions` | Full-text search over indexed session content |
-| `export_session_markdown` | Render a selected session as Markdown |
-| `list_tool_calls` | Audit commands and tool usage |
-| `find_touched_files` | Find sessions that touched a file/path |
-| `get_artifact` | Retrieve stored artifact text when available |
-| `index_status` | Show derived search index status |
+| `search` | Full-text search over messages, commands, paths, diffs, and previews. Optional `engine`, `field_kind`, `since`/`until`, `raw`, `limit`. |
+| `sessions` | Without `session_id`, lists candidates filtered by source/time/limit. With `session_id`, opens it: `format=detail` (default) returns metadata + timeline, `format=summary` returns the row only, `format=markdown` renders the transcript. |
+| `tool_calls` | Audit commands and tool usage by tool_name, canonical_type, session_id, errors_only, time bounds. When `path_substring` is set, also returns matching artifacts. |
+| `analytics` | Built-in aggregate reports backed by SQLite views: `report=sessions\|tools\|errors\|models\|projects` with the matching filters. |
+| `artifact` | Fetch full text for an `artifact_id`. Binary artifacts return a placeholder. |
+| `compile` | Without args, returns a status snapshot (search index health). With `source` (and optional `sessions_path`), imports that provider into the bundle. |
 
 Registered MCP prompts include:
 
@@ -380,7 +412,7 @@ Registered MCP prompts include:
 | `find_file_history` | Investigate history for a file or path |
 | `audit_tool_failures` | Group and explain failed tool calls |
 
-All MCP tools are read-only and use the same services as the CLI.
+Five tools are read-only; `compile` is dual-mode (status without args, mutating import with args). All tools use the same services as the CLI.
 
 ## Common workflows
 
@@ -402,7 +434,15 @@ prosa export session <session-id> --format markdown
 
 ### Audit failed or suspicious tool usage
 
-Use MCP `list_tool_calls` for the richest tool-call filtering, or query Parquet:
+Use the built-in analytics report for quick aggregates:
+
+```bash
+prosa analytics tools --refresh --errors-only
+prosa analytics errors --output-format json
+```
+
+Use MCP `tool_calls` for the richest session-level filtering, or query
+Parquet directly when you need custom SQL:
 
 ```bash
 prosa export parquet
@@ -414,6 +454,14 @@ prosa query duckdb "
 "
 ```
 
+### Summarize a custom session store through MCP
+
+After compiling a non-default sessions path, use MCP `analytics report=sessions`
+with `source_path_substring` to keep analysis inside prosa instead of reading
+the source JSONL directly. This is useful for stores such as
+`~/.codex-mz/sessions` that share the same provider name as the default Codex
+store.
+
 ### Search faster with a sidecar index
 
 ```bash