[FEATURE] Enhance Admin Analytics API with Advanced Risk Insights

[VarshVishwakarma]

Problem / Motivation

The current admin.py API provides core escalation statistics and session tracking functionality, but lacks advanced analytics capabilities for deeper operational monitoring and large-scale moderation workflows.

Currently, operators can retrieve raw escalation data, but there is limited support for:

trend analysis,
anomaly detection,
comparative time-window analytics,
advanced aggregation,
or real-time monitoring insights.

As HumaneProxy grows into a production-ready AI safety platform, richer analytics endpoints would significantly improve observability and moderation efficiency.

Proposed Solution

Extend the existing humane_proxy/api/admin.py analytics capabilities with advanced monitoring and aggregation endpoints.

Proposed Enhancements
Risk trend analytics
Daily/weekly escalation comparisons
Escalation growth-rate metrics
Top recurring trigger analysis
Category distribution percentages
High-risk session detection
Rolling average risk calculations
Time-range filtering improvements
Optional WebSocket/live monitoring support
Potential New Endpoints
/admin/analytics/trends
/admin/analytics/anomalies
/admin/analytics/top-triggers
/admin/analytics/live
Additional Improvements
Query optimization for large datasets
Optional caching layer
Better pagination support
Response schema standardization

These improvements would create a stronger foundation for future dashboard integrations and enterprise-grade observability tooling.

Alternatives Considered
Relying entirely on external dashboards
Keeping analytics limited to raw SQL aggregations
Using third-party monitoring tools only

However, expanding the native Admin API keeps analytics tightly integrated with HumaneProxy’s moderation pipeline and improves developer experience.

Additional Context

Relevant existing implementation:

humane_proxy/api/admin.py
/admin/stats
/admin/escalations
/admin/sessions/{id}/risk

The project already exposes useful moderation statistics, making advanced analytics a natural extension of the current architecture.

[VarshVishwakarma]

Hi @Vishisht16, I’d like to work on this feature if it gets approved.

I’m planning to enhance the existing admin.py analytics system by introducing advanced risk insights, aggregation improvements, and groundwork for future dashboard integrations.

Proposed work includes:

• advanced analytics endpoints,
• trend and anomaly insights,
• improved filtering/pagination,
• top trigger analysis,
• and better operational observability.

I’ve already reviewed the current Admin API architecture and would love to contribute this feature.

Could you please assign this issue to me?

[Vishisht16]

@VarshVishwakarma I support enhancement of native Admin API but I would suggest you to review the current implementation of admin.py once again and come back with substantial plans. Some things you listed here are already implemented in it to some extent. If possible, mention what's implemented right now and how you're going to enhance that exact endpoint, along with a small walkthrough for any new endpoints.
This issue is coupled with #3 so you'll have to work with @asnaassalam on these. Also, please drop the live monitoring support part for this issue as it can be a big one. A separate issue can be opened for that in the future.

Note: Please make sure you use markdown properly to format your proposal next time onwards. The current plain text approach hurts readability.

[VarshVishwakarma]

@VarshVishwakarma I support enhancement of native Admin API but I would suggest you to review the current implementation of admin.py once again and come back with substantial plans. Some things you listed here are already implemented in it to some extent. If possible, mention what's implemented right now and how you're going to enhance that exact endpoint, along with a small walkthrough for any new endpoints. This issue is coupled with #3 so you'll have to work with @asnaassalam on these. Also, please drop the live monitoring support part for this issue as it can be a big one. A separate issue can be opened for that in the future.

Note: Please make sure you use markdown properly to format your proposal next time onwards. The current plain text approach hurts readability.

Thanks for the detailed feedback, @Vishisht16 — I reviewed admin.py again more carefully and I understand your point now.

You're right that several analytics capabilities are already partially implemented, especially in:

• /admin/stats
• /admin/escalations
• /admin/sessions/{id}/risk

After revisiting the implementation, I’d like to narrow the scope of this issue specifically toward enhancing the existing analytics endpoints instead of introducing overly broad monitoring features.

Current Implementation Review

/admin/stats

Already provides:

• total escalations,
• category breakdown,
• average risk score,
• top sessions,
• stage distribution,
• hourly aggregation.

Planned enhancements:

• percentage-based category distribution,
• rolling 7-day / 30-day trend comparison,
• escalation growth-rate metrics,
• configurable time-window analytics,
• standardized analytics response schema.

---

/admin/escalations

Already supports:

• filtering,
• pagination,
• sorting,
• CSV export.

Planned enhancements:

• trigger-frequency aggregation,
• advanced filtering combinations,
• optimized query handling for larger datasets,
• optional severity-based grouping.

---

/admin/sessions/{id}/risk

Already provides:

• session history replay,
• trajectory reconstruction,
• trend/spike analysis.

Planned enhancements:

• summarized trajectory insights,
• peak-risk timestamps,
• category transition summaries,
• rolling average risk visualization data.

---

Proposed Additional Endpoint

GET /admin/analytics/top-triggers

Purpose:
Aggregate and rank the most frequently triggered escalation patterns across stored escalation records.

Potential response:

{
  "top_triggers": [
    {"trigger": "suicide", "count": 42},
    {"trigger": "bomb", "count": 18}
  ]
}

I’ll also coordinate with @asnaassalam since this issue overlaps with #3.

And agreed on removing live monitoring/WebSocket support from this scope — that definitely deserves a separate issue later.

Thanks again for the guidance — I’ll make sure future proposals are formatted more cleanly and scoped more precisely.

[Vishisht16]

It's much better this time but there are still enhancements that are vaguely described. Things like summarized information, metrics, schema, optimization, grouping, etc. I'm going to change the scope of this issue and I want the following things in your PR:

• /admin/stats: add category distributions as percentage. Also add a period_comparison field that shows escalation counts from current week vs last week.
• GET /admin/analytics/top-triggers: Aggregate trigger keywords from all escalations and rank them by frequency. Accept limit and optional category filter.
• /admin/sessions/{id}/risk: Add peak_risk_score and peak_risk_timestamp fields in response. Also add category_transitions as an ordered list showing when the session's category changed.

Drop the vague items like standardized resonse schema, optimized query handling, advanced filtering, etc. If there are any specific ideas, create detailed issues later for those.

For this, coordinate with @asnaassalam on response schema because since a dashboard is being built for these endpoints. Format your PR description properly later according to these requirements, without changing anything else.

[VarshVishwakarma]

It's much better this time but there are still enhancements that are vaguely described. Things like summarized information, metrics, schema, optimization, grouping, etc. I'm going to change the scope of this issue and I want the following things in your PR:

• /admin/stats: add category distributions as percentage. Also add a period_comparison field that shows escalation counts from current week vs last week.
• GET /admin/analytics/top-triggers: Aggregate trigger keywords from all escalations and rank them by frequency. Accept limit and optional category filter.
• /admin/sessions/{id}/risk: Add peak_risk_score and peak_risk_timestamp fields in response. Also add category_transitions as an ordered list showing when the session's category changed.

Drop the vague items like standardized resonse schema, optimized query handling, advanced filtering, etc. If there are any specific ideas, create detailed issues later for those.

For this, coordinate with @asnaassalam on response schema because since a dashboard is being built for these endpoints. Format your PR description properly later according to these requirements, without changing anything else.

Understood, @Vishisht16 — thanks for refining the scope clearly.

I’ll limit the PR strictly to:

• percentage-based category distributions + weekly period comparison in /admin/stats
• GET /admin/analytics/top-triggers with limit and optional category filter
• peak_risk_score, peak_risk_timestamp, and ordered category_transitions in /admin/sessions/{id}/risk

I’ll avoid introducing unrelated schema or optimization changes and will coordinate with @asnaassalam regarding the response structure for dashboard compatibility.

If possible please add gssoc:approved, level:advanced, quality:exceptional, type:performance, and the NSoC Level 3 labels.

Thanks again for the detailed guidance.

[Vishisht16]

@VarshVishwakarma I've already added the labels for this issue. I'll add gssoc:approved before merging and quality label after analysing your PR. Also, this repository is not listed under NSoC.