fulcra-analytics

Files (24)

• .gitignore
• README.md
• SKILL.md
• architecture.md · docs/
• cli.md · docs/
• client.md · docs/
• loader.md · docs/
• statistics.md · docs/
• pyproject.toml
• validate_e2e.py · scripts/
• __init__.py · src/fulcra_analytics/
• __main__.py · src/fulcra_analytics/
• cli.py · src/fulcra_analytics/
• client.py · src/fulcra_analytics/
• loader.py · src/fulcra_analytics/
• schemas.py · src/fulcra_analytics/
• statistics.py · src/fulcra_analytics/
• first_olympiad_ml_stats_synthetic_v1.json · tests/fixtures/
• test_advanced_statistics.py · tests/
• test_cli.py · tests/
• test_client.py · tests/
• test_loader.py · tests/
• test_statistics.py · tests/
• uv.lock

SKILL.md (first lines)

# Fulcra Analytics

Use this skill when a user wants to inspect, summarize, or statistically analyze Fulcra data such as health metrics, calendar records, location visits, annotations, activity records, or team/agent activity logs.

Fulcra Analytics is an early-stage modular Python skill template. It provides a CLI-backed Fulcra client, record normalization utilities, DataFrame descriptive statistics, and a command-line entrypoint for quickly producing JSON summaries.

The core principle is privacy-respecting analysis: keep raw personal data local by default, compute summaries and aggregates, and only upload sanitized reports or explicitly approved artifacts.

## When to Use

Use this skill when the user asks to:

- Analyze a Fulcra data type, metric, export, or time range.
- Summarize records from `fulcra-api get-records` or `fulcra-api metric-time-series`.
- Inspect JSON, JSONL/NDJSON, or CSV exports from Fulcra.
- Compute missingness, numeric summaries, categorical frequencies, boolean ratios, datetime ranges, or grouped summaries.
- Build an OKF-ready report from aggregate findings.
- Create a repeatable local analysis workflow for Fulcra data.

Do not use this skill when:

- The user only wants to create or configure custom data types; use Fulcra onboarding/tracking workflows instead.
- The task requires publishing raw health, location, calendar, or personal annotation data to a shared space without explicit authorization.
- The user needs advanced modeling, causal inference, forecasting, or visualization beyond descriptive summaries. This package can be a starting point, but the current implementation is intentionally lightweight.

## Installed Package Layout

The skill directory contains a Python package under `skills/fulcra-analytics/`:

```text
skills/fulcra-analytics/
  SKILL.md
  README.md
  pyproject.toml
  docs/
    architecture.md
    cli.md
    client.md
    loader.md
    statistics.md
  src/fulcra_analytics/
    __init__.py
    __main__.py
    cli.py
    client.py
    loader.py
    schemas.py
    statistics.py
  tests/
    test_cli.py
    test_client.py
    test_loader.py
    test_statistics.py
```

## Main Interfaces

### Command-line entrypoint

Use the CLI for routine analysis. It writes JSON to stdout.

```bash
uv tool run fulcra-analytics records StepCount "1 week" --pretty
uv tool run fulcra-analytics metrics HeartRate "1 day" --pretty
uv tool run fulcra-analytics file path/to/export.json --pretty
uv tool run fulcra-analytics catalog --base-types-only --pretty
uv tool run fulcra-analytics user-info --pretty
```

You can also run the package module directly inside a checkout or installed environment:

```bash
python -m fulcra_analytics records StepCount "1 week"
```

### Python modules

Use the Python API when composing analysis workflows in scripts or notebooks:

```python
from fulcra_analytics import FulcraClient, summarize_dataframe

client = FulcraClient()
df = client.get_records_dataframe("StepCount", "1 week")
summary = summarize_dataframe(df, group_by="source")
print(summary.to_dict())
```

Key modules:

- `fulcra_analytics.client`: CLI-backed Fulcra API wrapper.
- `fulcra_analytics.loader`: load JSON/JSONL/CSV exports and normalize Fulcra payloads into DataFrames.
- `fulcra_analytics.statistics`: descriptive statistics over DataFrames.
- `fulcra_analytics.cli`: Typer CLI for `uv tool run fulcra-analytics`.

## Recommended Workflow

1. Clarify the user's analysis question.
   - Example: "How did my steps vary over the last week?"
   - Identify data type, date/time range, grouping dimensions, and desired output.

2. Prefer local or CLI-backed data access.
   - Fetch records with `FulcraClient` or the CLI commands.
   - Keep raw data local unless the user explicitly authorizes upload.

3. Normalize records into a DataFrame.
   - Use `fulcra_analytics.loader` or CLI commands.
   - Supported local formats: `.json`, `.jsonl`, `.ndjson`, `.csv`.

4. Compute summaries.
   - Use `summarize_dataframe(df)`.
   - Add `group_by=<column>` when grouping by source, category, day, device, or another column is meaningful.

5. Report aggregate findings.
   - Use JSON for machine-readable output.
   - Convert findings to OKF markdown when storing in Fulcra File Store.
   - Include the question, data used, methods, findings, caveats, and next steps.

6. Verify outputs.

From fulcradynamics/agent-skills, MIT.

More from fulcradynamics/agent-skills