# This file was auto-generated by Fern from our API Definition.

import typing

from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
from ..core.request_options import RequestOptions
from ..types.neurons_analytics_dashboard_response import NeuronsAnalyticsDashboardResponse
from ..types.neurons_benchmarks_response import NeuronsBenchmarksResponse
from ..types.neurons_heatmap_response import NeuronsHeatmapResponse
from ..types.neurons_optimization_response import NeuronsOptimizationResponse
from ..types.neurons_trends_response import NeuronsTrendsResponse
from ..types.usage_analytics_response import UsageAnalyticsResponse
from ..types.usage_summary_response import UsageSummaryResponse
from .raw_client import AsyncRawAnalyticsUsageClient, RawAnalyticsUsageClient


class AnalyticsUsageClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawAnalyticsUsageClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> RawAnalyticsUsageClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        RawAnalyticsUsageClient
        """
        return self._raw_client

    def get_yearly_usage(
        self,
        org_id: str,
        *,
        years: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UsageAnalyticsResponse:
        """
        Get yearly usage analytics for graphing.

        Returns multi-year trends showing usage patterns over time.

        **Perfect for:**
        - Executive dashboards - Long-term usage trends
        - Budget planning - Annual cost forecasting
        - Growth analysis - Year-over-year comparisons

        Parameters
        ----------
        org_id : str

        years : typing.Optional[int]
            Number of years to include

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UsageAnalyticsResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.analytics_usage.get_yearly_usage(
            org_id="org_id",
        )
        """
        _response = self._raw_client.get_yearly_usage(org_id, years=years, request_options=request_options)
        return _response.data

    def get_monthly_usage(
        self,
        org_id: str,
        *,
        year: int,
        month: typing.Optional[int] = None,
        months: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UsageAnalyticsResponse:
        """
        Get monthly usage analytics for graphing.

        Returns month-by-month breakdown for detailed trend analysis.

        **Perfect for:**
        - Monthly reports - Detailed usage tracking
        - Trend analysis - Seasonal usage patterns
        - Budget monitoring - Monthly cost tracking

        Parameters
        ----------
        org_id : str

        year : int

        month : typing.Optional[int]
            Month for validation

        months : typing.Optional[int]
            Number of months to include

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UsageAnalyticsResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.analytics_usage.get_monthly_usage(
            org_id="org_id",
            year=1,
        )
        """
        _response = self._raw_client.get_monthly_usage(
            org_id, year=year, month=month, months=months, request_options=request_options
        )
        return _response.data

    def get_daily_usage(
        self, org_id: str, *, year: int, month: int, request_options: typing.Optional[RequestOptions] = None
    ) -> UsageAnalyticsResponse:
        """
        Get daily usage analytics for graphing.

        Returns day-by-day breakdown for detailed analysis.

        **Perfect for:**
        - Operational dashboards - Daily usage monitoring
        - Pattern analysis - Usage behavior insights
        - Anomaly detection - Unusual usage spikes

        Parameters
        ----------
        org_id : str

        year : int

        month : int

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UsageAnalyticsResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.analytics_usage.get_daily_usage(
            org_id="org_id",
            year=1,
            month=1,
        )
        """
        _response = self._raw_client.get_daily_usage(org_id, year=year, month=month, request_options=request_options)
        return _response.data

    def get_hourly_usage(
        self, org_id: str, *, date: str, request_options: typing.Optional[RequestOptions] = None
    ) -> UsageAnalyticsResponse:
        """
        Get hourly usage analytics for graphing.

        Returns hour-by-hour breakdown for detailed analysis.

        **Perfect for:**
        - Real-time dashboards - Live usage monitoring
        - Performance optimization - Peak load analysis
        - Capacity planning - Hour-based scaling decisions

        Parameters
        ----------
        org_id : str

        date : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UsageAnalyticsResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.analytics_usage.get_hourly_usage(
            org_id="org_id",
            date="date",
        )
        """
        _response = self._raw_client.get_hourly_usage(org_id, date=date, request_options=request_options)
        return _response.data

    def get_usage_summary(
        self, org_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> UsageSummaryResponse:
        """
        Get comprehensive usage summary across all time periods.

        Returns complete overview with all-time totals, current month, and top models.

        **Perfect for:**
        - Executive dashboards - High-level overview
        - Quick insights - At-a-glance usage metrics
        - Trend indicators - Growth and usage patterns

        Parameters
        ----------
        org_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UsageSummaryResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.analytics_usage.get_usage_summary(
            org_id="org_id",
        )
        """
        _response = self._raw_client.get_usage_summary(org_id, request_options=request_options)
        return _response.data

    def get_usage_dashboard(
        self,
        org_id: str,
        *,
        days: typing.Optional[int] = None,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> NeuronsAnalyticsDashboardResponse:
        """
        Get comprehensive analytics dashboard with optional metric filtering.

        Executive-level analytics with comprehensive insights, trends,
        and optimization recommendations.

        **Metric Filtering:**
        - `metric=neurons` - Analyze only neurons usage
        - `metric=synapses` - Analyze only synapses usage
        - `metric=null` or omit - Analyze combined metrics

        **What You Get:**
        - Current Period Summary - Key metrics for the analysis period
        - Daily Trends - Day-by-day usage patterns and trends
        - Usage Patterns - Peak hours, weekday/weekend analysis
        - Efficiency Metrics - Cost efficiency and optimization scores
        - Predictive Projections - Monthly usage and cost forecasts
        - Actionable Insights - AI-generated recommendations

        **Perfect for:**
        - Executive Dashboards - High-level usage overview
        - Cost Management - Track spending and efficiency
        - Capacity Planning - Forecast future requirements
        - Performance Monitoring - Monitor generation efficiency

        Parameters
        ----------
        org_id : str

        days : typing.Optional[int]
            Number of days to analyze (7-90)

        metric : typing.Optional[str]
            Metric type to analyze: 'neurons', 'synapses', or null for combined

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NeuronsAnalyticsDashboardResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.analytics_usage.get_usage_dashboard(
            org_id="org_id",
        )
        """
        _response = self._raw_client.get_usage_dashboard(
            org_id, days=days, metric=metric, request_options=request_options
        )
        return _response.data

    def get_usage_trends(
        self,
        org_id: str,
        *,
        months: typing.Optional[int] = None,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> NeuronsTrendsResponse:
        """
        Get trends analysis with optional metric filtering.

        Multi-month trend analysis for usage patterns, growth trajectories,
        and seasonal insights.

        **Metric Filtering:**
        - `metric=neurons` - Analyze only neurons trends
        - `metric=synapses` - Analyze only synapses trends
        - `metric=null` or omit - Analyze combined metrics

        **Deep Trend Analysis:**
        - Monthly Progression - Month-over-month usage evolution
        - Growth Patterns - Identify growth stages and acceleration trends
        - Seasonal Analysis - Detect seasonal usage patterns and cycles
        - Pattern Recognition - Identify recurring usage patterns
        - Growth Forecasting - Predictive modeling for future growth

        **Perfect for:**
        - Strategic Planning - Long-term usage strategy
        - Financial Forecasting - Budget planning and cost projections
        - Product Roadmaps - Feature prioritization based on usage trends

        Parameters
        ----------
        org_id : str

        months : typing.Optional[int]
            Number of months to analyze (3-12)

        metric : typing.Optional[str]
            Metric type to analyze: 'neurons', 'synapses', or null for combined

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NeuronsTrendsResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.analytics_usage.get_usage_trends(
            org_id="org_id",
        )
        """
        _response = self._raw_client.get_usage_trends(
            org_id, months=months, metric=metric, request_options=request_options
        )
        return _response.data

    def get_usage_optimization(
        self,
        org_id: str,
        *,
        days: typing.Optional[int] = None,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> NeuronsOptimizationResponse:
        """
        Get cost optimization report with optional metric filtering.

        Comprehensive cost optimization analysis with actionable recommendations
        for reducing costs while maintaining or improving performance.

        **Metric Filtering:**
        - `metric=neurons` - Optimize neurons usage
        - `metric=synapses` - Optimize synapses usage
        - `metric=null` or omit - Optimize combined metrics

        **Optimization Analysis:**
        - Cost Breakdown - Detailed analysis of cost components
        - Efficiency Metrics - Performance vs. cost efficiency analysis
        - Optimization Opportunities - Specific areas for cost reduction
        - Savings Potential - Quantified savings opportunities
        - Implementation Roadmap - Prioritized optimization recommendations

        **Business Impact:**
        - Cost Reduction - Direct cost savings
        - Efficiency Gains - Improved generation efficiency
        - Performance Optimization - Better performance at lower cost

        Parameters
        ----------
        org_id : str

        days : typing.Optional[int]
            Number of days to analyze (7-90)

        metric : typing.Optional[str]
            Metric type to analyze: 'neurons', 'synapses', or null for combined

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NeuronsOptimizationResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.analytics_usage.get_usage_optimization(
            org_id="org_id",
        )
        """
        _response = self._raw_client.get_usage_optimization(
            org_id, days=days, metric=metric, request_options=request_options
        )
        return _response.data

    def get_usage_heatmap(
        self,
        org_id: str,
        *,
        days: typing.Optional[int] = None,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> NeuronsHeatmapResponse:
        """
        Get usage heatmap with optional metric filtering.

        Visual usage pattern analysis showing generation patterns
        by hour and day of week.

        **Metric Filtering:**
        - `metric=neurons` - Heatmap for neurons usage
        - `metric=synapses` - Heatmap for synapses usage
        - `metric=null` or omit - Heatmap for combined metrics

        **Heatmap Visualization:**
        - 24-Hour Analysis - Usage patterns across all hours of the day
        - 7-Day Analysis - Weekly usage patterns (Monday-Sunday)
        - Peak Detection - Identify peak usage hours and days
        - Low Usage Periods - Find opportunities for maintenance windows

        **Perfect for:**
        - Infrastructure Planning - Right-size infrastructure based on usage
        - Cost Management - Schedule expensive operations during low-usage periods
        - User Experience - Ensure adequate capacity during peak usage times

        Parameters
        ----------
        org_id : str

        days : typing.Optional[int]
            Number of days to analyze (7-90)

        metric : typing.Optional[str]
            Metric type to analyze: 'neurons', 'synapses', or null for combined

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NeuronsHeatmapResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.analytics_usage.get_usage_heatmap(
            org_id="org_id",
        )
        """
        _response = self._raw_client.get_usage_heatmap(
            org_id, days=days, metric=metric, request_options=request_options
        )
        return _response.data

    def get_usage_benchmarks(
        self,
        org_id: str,
        *,
        month: int,
        year: int,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> NeuronsBenchmarksResponse:
        """
        Get performance benchmarks with optional metric filtering.

        Competitive benchmarking analysis comparing your organization's usage
        against industry averages and best practices.

        **Metric Filtering:**
        - `metric=neurons` - Benchmark neurons usage
        - `metric=synapses` - Benchmark synapses usage
        - `metric=null` or omit - Benchmark combined metrics

        **Benchmark Categories:**
        - Industry Averages - Anonymous comparison with similar organizations
        - Percentile Rankings - Your position relative to all organizations
        - Efficiency Benchmarks - Cost efficiency vs. industry standards
        - Usage Pattern Benchmarks - Comparison of usage patterns

        **Perfect for:**
        - Competitive Positioning - Understand your market position
        - Performance Goals - Set realistic improvement targets
        - Best Practice Adoption - Learn from top performers

        Parameters
        ----------
        org_id : str

        month : int

        year : int

        metric : typing.Optional[str]
            Metric type to analyze: 'neurons', 'synapses', or null for combined

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NeuronsBenchmarksResponse
            Successful Response

        Examples
        --------
        from aitronos import Aitronos

        client = Aitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )
        client.analytics_usage.get_usage_benchmarks(
            org_id="org_id",
            month=1,
            year=1,
        )
        """
        _response = self._raw_client.get_usage_benchmarks(
            org_id, month=month, year=year, metric=metric, request_options=request_options
        )
        return _response.data


class AsyncAnalyticsUsageClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawAnalyticsUsageClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> AsyncRawAnalyticsUsageClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        AsyncRawAnalyticsUsageClient
        """
        return self._raw_client

    async def get_yearly_usage(
        self,
        org_id: str,
        *,
        years: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UsageAnalyticsResponse:
        """
        Get yearly usage analytics for graphing.

        Returns multi-year trends showing usage patterns over time.

        **Perfect for:**
        - Executive dashboards - Long-term usage trends
        - Budget planning - Annual cost forecasting
        - Growth analysis - Year-over-year comparisons

        Parameters
        ----------
        org_id : str

        years : typing.Optional[int]
            Number of years to include

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UsageAnalyticsResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.analytics_usage.get_yearly_usage(
                org_id="org_id",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get_yearly_usage(org_id, years=years, request_options=request_options)
        return _response.data

    async def get_monthly_usage(
        self,
        org_id: str,
        *,
        year: int,
        month: typing.Optional[int] = None,
        months: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UsageAnalyticsResponse:
        """
        Get monthly usage analytics for graphing.

        Returns month-by-month breakdown for detailed trend analysis.

        **Perfect for:**
        - Monthly reports - Detailed usage tracking
        - Trend analysis - Seasonal usage patterns
        - Budget monitoring - Monthly cost tracking

        Parameters
        ----------
        org_id : str

        year : int

        month : typing.Optional[int]
            Month for validation

        months : typing.Optional[int]
            Number of months to include

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UsageAnalyticsResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.analytics_usage.get_monthly_usage(
                org_id="org_id",
                year=1,
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get_monthly_usage(
            org_id, year=year, month=month, months=months, request_options=request_options
        )
        return _response.data

    async def get_daily_usage(
        self, org_id: str, *, year: int, month: int, request_options: typing.Optional[RequestOptions] = None
    ) -> UsageAnalyticsResponse:
        """
        Get daily usage analytics for graphing.

        Returns day-by-day breakdown for detailed analysis.

        **Perfect for:**
        - Operational dashboards - Daily usage monitoring
        - Pattern analysis - Usage behavior insights
        - Anomaly detection - Unusual usage spikes

        Parameters
        ----------
        org_id : str

        year : int

        month : int

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UsageAnalyticsResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.analytics_usage.get_daily_usage(
                org_id="org_id",
                year=1,
                month=1,
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get_daily_usage(
            org_id, year=year, month=month, request_options=request_options
        )
        return _response.data

    async def get_hourly_usage(
        self, org_id: str, *, date: str, request_options: typing.Optional[RequestOptions] = None
    ) -> UsageAnalyticsResponse:
        """
        Get hourly usage analytics for graphing.

        Returns hour-by-hour breakdown for detailed analysis.

        **Perfect for:**
        - Real-time dashboards - Live usage monitoring
        - Performance optimization - Peak load analysis
        - Capacity planning - Hour-based scaling decisions

        Parameters
        ----------
        org_id : str

        date : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UsageAnalyticsResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.analytics_usage.get_hourly_usage(
                org_id="org_id",
                date="date",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get_hourly_usage(org_id, date=date, request_options=request_options)
        return _response.data

    async def get_usage_summary(
        self, org_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> UsageSummaryResponse:
        """
        Get comprehensive usage summary across all time periods.

        Returns complete overview with all-time totals, current month, and top models.

        **Perfect for:**
        - Executive dashboards - High-level overview
        - Quick insights - At-a-glance usage metrics
        - Trend indicators - Growth and usage patterns

        Parameters
        ----------
        org_id : str

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UsageSummaryResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.analytics_usage.get_usage_summary(
                org_id="org_id",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get_usage_summary(org_id, request_options=request_options)
        return _response.data

    async def get_usage_dashboard(
        self,
        org_id: str,
        *,
        days: typing.Optional[int] = None,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> NeuronsAnalyticsDashboardResponse:
        """
        Get comprehensive analytics dashboard with optional metric filtering.

        Executive-level analytics with comprehensive insights, trends,
        and optimization recommendations.

        **Metric Filtering:**
        - `metric=neurons` - Analyze only neurons usage
        - `metric=synapses` - Analyze only synapses usage
        - `metric=null` or omit - Analyze combined metrics

        **What You Get:**
        - Current Period Summary - Key metrics for the analysis period
        - Daily Trends - Day-by-day usage patterns and trends
        - Usage Patterns - Peak hours, weekday/weekend analysis
        - Efficiency Metrics - Cost efficiency and optimization scores
        - Predictive Projections - Monthly usage and cost forecasts
        - Actionable Insights - AI-generated recommendations

        **Perfect for:**
        - Executive Dashboards - High-level usage overview
        - Cost Management - Track spending and efficiency
        - Capacity Planning - Forecast future requirements
        - Performance Monitoring - Monitor generation efficiency

        Parameters
        ----------
        org_id : str

        days : typing.Optional[int]
            Number of days to analyze (7-90)

        metric : typing.Optional[str]
            Metric type to analyze: 'neurons', 'synapses', or null for combined

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NeuronsAnalyticsDashboardResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.analytics_usage.get_usage_dashboard(
                org_id="org_id",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get_usage_dashboard(
            org_id, days=days, metric=metric, request_options=request_options
        )
        return _response.data

    async def get_usage_trends(
        self,
        org_id: str,
        *,
        months: typing.Optional[int] = None,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> NeuronsTrendsResponse:
        """
        Get trends analysis with optional metric filtering.

        Multi-month trend analysis for usage patterns, growth trajectories,
        and seasonal insights.

        **Metric Filtering:**
        - `metric=neurons` - Analyze only neurons trends
        - `metric=synapses` - Analyze only synapses trends
        - `metric=null` or omit - Analyze combined metrics

        **Deep Trend Analysis:**
        - Monthly Progression - Month-over-month usage evolution
        - Growth Patterns - Identify growth stages and acceleration trends
        - Seasonal Analysis - Detect seasonal usage patterns and cycles
        - Pattern Recognition - Identify recurring usage patterns
        - Growth Forecasting - Predictive modeling for future growth

        **Perfect for:**
        - Strategic Planning - Long-term usage strategy
        - Financial Forecasting - Budget planning and cost projections
        - Product Roadmaps - Feature prioritization based on usage trends

        Parameters
        ----------
        org_id : str

        months : typing.Optional[int]
            Number of months to analyze (3-12)

        metric : typing.Optional[str]
            Metric type to analyze: 'neurons', 'synapses', or null for combined

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NeuronsTrendsResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.analytics_usage.get_usage_trends(
                org_id="org_id",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get_usage_trends(
            org_id, months=months, metric=metric, request_options=request_options
        )
        return _response.data

    async def get_usage_optimization(
        self,
        org_id: str,
        *,
        days: typing.Optional[int] = None,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> NeuronsOptimizationResponse:
        """
        Get cost optimization report with optional metric filtering.

        Comprehensive cost optimization analysis with actionable recommendations
        for reducing costs while maintaining or improving performance.

        **Metric Filtering:**
        - `metric=neurons` - Optimize neurons usage
        - `metric=synapses` - Optimize synapses usage
        - `metric=null` or omit - Optimize combined metrics

        **Optimization Analysis:**
        - Cost Breakdown - Detailed analysis of cost components
        - Efficiency Metrics - Performance vs. cost efficiency analysis
        - Optimization Opportunities - Specific areas for cost reduction
        - Savings Potential - Quantified savings opportunities
        - Implementation Roadmap - Prioritized optimization recommendations

        **Business Impact:**
        - Cost Reduction - Direct cost savings
        - Efficiency Gains - Improved generation efficiency
        - Performance Optimization - Better performance at lower cost

        Parameters
        ----------
        org_id : str

        days : typing.Optional[int]
            Number of days to analyze (7-90)

        metric : typing.Optional[str]
            Metric type to analyze: 'neurons', 'synapses', or null for combined

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NeuronsOptimizationResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.analytics_usage.get_usage_optimization(
                org_id="org_id",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get_usage_optimization(
            org_id, days=days, metric=metric, request_options=request_options
        )
        return _response.data

    async def get_usage_heatmap(
        self,
        org_id: str,
        *,
        days: typing.Optional[int] = None,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> NeuronsHeatmapResponse:
        """
        Get usage heatmap with optional metric filtering.

        Visual usage pattern analysis showing generation patterns
        by hour and day of week.

        **Metric Filtering:**
        - `metric=neurons` - Heatmap for neurons usage
        - `metric=synapses` - Heatmap for synapses usage
        - `metric=null` or omit - Heatmap for combined metrics

        **Heatmap Visualization:**
        - 24-Hour Analysis - Usage patterns across all hours of the day
        - 7-Day Analysis - Weekly usage patterns (Monday-Sunday)
        - Peak Detection - Identify peak usage hours and days
        - Low Usage Periods - Find opportunities for maintenance windows

        **Perfect for:**
        - Infrastructure Planning - Right-size infrastructure based on usage
        - Cost Management - Schedule expensive operations during low-usage periods
        - User Experience - Ensure adequate capacity during peak usage times

        Parameters
        ----------
        org_id : str

        days : typing.Optional[int]
            Number of days to analyze (7-90)

        metric : typing.Optional[str]
            Metric type to analyze: 'neurons', 'synapses', or null for combined

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NeuronsHeatmapResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.analytics_usage.get_usage_heatmap(
                org_id="org_id",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get_usage_heatmap(
            org_id, days=days, metric=metric, request_options=request_options
        )
        return _response.data

    async def get_usage_benchmarks(
        self,
        org_id: str,
        *,
        month: int,
        year: int,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> NeuronsBenchmarksResponse:
        """
        Get performance benchmarks with optional metric filtering.

        Competitive benchmarking analysis comparing your organization's usage
        against industry averages and best practices.

        **Metric Filtering:**
        - `metric=neurons` - Benchmark neurons usage
        - `metric=synapses` - Benchmark synapses usage
        - `metric=null` or omit - Benchmark combined metrics

        **Benchmark Categories:**
        - Industry Averages - Anonymous comparison with similar organizations
        - Percentile Rankings - Your position relative to all organizations
        - Efficiency Benchmarks - Cost efficiency vs. industry standards
        - Usage Pattern Benchmarks - Comparison of usage patterns

        **Perfect for:**
        - Competitive Positioning - Understand your market position
        - Performance Goals - Set realistic improvement targets
        - Best Practice Adoption - Learn from top performers

        Parameters
        ----------
        org_id : str

        month : int

        year : int

        metric : typing.Optional[str]
            Metric type to analyze: 'neurons', 'synapses', or null for combined

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NeuronsBenchmarksResponse
            Successful Response

        Examples
        --------
        import asyncio

        from aitronos import AsyncAitronos

        client = AsyncAitronos(
            api_key="YOUR_API_KEY",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.analytics_usage.get_usage_benchmarks(
                org_id="org_id",
                month=1,
                year=1,
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get_usage_benchmarks(
            org_id, month=month, year=year, metric=metric, request_options=request_options
        )
        return _response.data
