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

import typing
from json.decoder import JSONDecodeError

from ..core.api_error import ApiError
from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
from ..core.http_response import AsyncHttpResponse, HttpResponse
from ..core.jsonable_encoder import jsonable_encoder
from ..core.pydantic_utilities import parse_obj_as
from ..core.request_options import RequestOptions
from ..errors.unprocessable_entity_error import UnprocessableEntityError
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


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

    def get_yearly_usage(
        self,
        org_id: str,
        *,
        years: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> HttpResponse[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
        -------
        HttpResponse[UsageAnalyticsResponse]
            Successful Response
        """
        _response = self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/yearly/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "years": years,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    UsageAnalyticsResponse,
                    parse_obj_as(
                        type_=UsageAnalyticsResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return HttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    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,
    ) -> HttpResponse[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
        -------
        HttpResponse[UsageAnalyticsResponse]
            Successful Response
        """
        _response = self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/monthly/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "year": year,
                "month": month,
                "months": months,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    UsageAnalyticsResponse,
                    parse_obj_as(
                        type_=UsageAnalyticsResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return HttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    def get_daily_usage(
        self, org_id: str, *, year: int, month: int, request_options: typing.Optional[RequestOptions] = None
    ) -> HttpResponse[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
        -------
        HttpResponse[UsageAnalyticsResponse]
            Successful Response
        """
        _response = self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/daily/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "year": year,
                "month": month,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    UsageAnalyticsResponse,
                    parse_obj_as(
                        type_=UsageAnalyticsResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return HttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    def get_hourly_usage(
        self, org_id: str, *, date: str, request_options: typing.Optional[RequestOptions] = None
    ) -> HttpResponse[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
        -------
        HttpResponse[UsageAnalyticsResponse]
            Successful Response
        """
        _response = self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/hourly/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "date": date,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    UsageAnalyticsResponse,
                    parse_obj_as(
                        type_=UsageAnalyticsResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return HttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    def get_usage_summary(
        self, org_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> HttpResponse[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
        -------
        HttpResponse[UsageSummaryResponse]
            Successful Response
        """
        _response = self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/summary/{jsonable_encoder(org_id)}",
            method="GET",
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    UsageSummaryResponse,
                    parse_obj_as(
                        type_=UsageSummaryResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return HttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    def get_usage_dashboard(
        self,
        org_id: str,
        *,
        days: typing.Optional[int] = None,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> HttpResponse[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
        -------
        HttpResponse[NeuronsAnalyticsDashboardResponse]
            Successful Response
        """
        _response = self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/dashboard/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "days": days,
                "metric": metric,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    NeuronsAnalyticsDashboardResponse,
                    parse_obj_as(
                        type_=NeuronsAnalyticsDashboardResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return HttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    def get_usage_trends(
        self,
        org_id: str,
        *,
        months: typing.Optional[int] = None,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> HttpResponse[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
        -------
        HttpResponse[NeuronsTrendsResponse]
            Successful Response
        """
        _response = self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/trends/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "months": months,
                "metric": metric,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    NeuronsTrendsResponse,
                    parse_obj_as(
                        type_=NeuronsTrendsResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return HttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    def get_usage_optimization(
        self,
        org_id: str,
        *,
        days: typing.Optional[int] = None,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> HttpResponse[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
        -------
        HttpResponse[NeuronsOptimizationResponse]
            Successful Response
        """
        _response = self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/optimization/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "days": days,
                "metric": metric,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    NeuronsOptimizationResponse,
                    parse_obj_as(
                        type_=NeuronsOptimizationResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return HttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    def get_usage_heatmap(
        self,
        org_id: str,
        *,
        days: typing.Optional[int] = None,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> HttpResponse[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
        -------
        HttpResponse[NeuronsHeatmapResponse]
            Successful Response
        """
        _response = self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/heatmap/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "days": days,
                "metric": metric,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    NeuronsHeatmapResponse,
                    parse_obj_as(
                        type_=NeuronsHeatmapResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return HttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    def get_usage_benchmarks(
        self,
        org_id: str,
        *,
        month: int,
        year: int,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> HttpResponse[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
        -------
        HttpResponse[NeuronsBenchmarksResponse]
            Successful Response
        """
        _response = self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/benchmarks/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "month": month,
                "year": year,
                "metric": metric,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    NeuronsBenchmarksResponse,
                    parse_obj_as(
                        type_=NeuronsBenchmarksResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return HttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)


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

    async def get_yearly_usage(
        self,
        org_id: str,
        *,
        years: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> AsyncHttpResponse[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
        -------
        AsyncHttpResponse[UsageAnalyticsResponse]
            Successful Response
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/yearly/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "years": years,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    UsageAnalyticsResponse,
                    parse_obj_as(
                        type_=UsageAnalyticsResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return AsyncHttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    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,
    ) -> AsyncHttpResponse[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
        -------
        AsyncHttpResponse[UsageAnalyticsResponse]
            Successful Response
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/monthly/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "year": year,
                "month": month,
                "months": months,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    UsageAnalyticsResponse,
                    parse_obj_as(
                        type_=UsageAnalyticsResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return AsyncHttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    async def get_daily_usage(
        self, org_id: str, *, year: int, month: int, request_options: typing.Optional[RequestOptions] = None
    ) -> AsyncHttpResponse[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
        -------
        AsyncHttpResponse[UsageAnalyticsResponse]
            Successful Response
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/daily/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "year": year,
                "month": month,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    UsageAnalyticsResponse,
                    parse_obj_as(
                        type_=UsageAnalyticsResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return AsyncHttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    async def get_hourly_usage(
        self, org_id: str, *, date: str, request_options: typing.Optional[RequestOptions] = None
    ) -> AsyncHttpResponse[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
        -------
        AsyncHttpResponse[UsageAnalyticsResponse]
            Successful Response
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/hourly/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "date": date,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    UsageAnalyticsResponse,
                    parse_obj_as(
                        type_=UsageAnalyticsResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return AsyncHttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    async def get_usage_summary(
        self, org_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> AsyncHttpResponse[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
        -------
        AsyncHttpResponse[UsageSummaryResponse]
            Successful Response
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/summary/{jsonable_encoder(org_id)}",
            method="GET",
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    UsageSummaryResponse,
                    parse_obj_as(
                        type_=UsageSummaryResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return AsyncHttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    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,
    ) -> AsyncHttpResponse[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
        -------
        AsyncHttpResponse[NeuronsAnalyticsDashboardResponse]
            Successful Response
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/dashboard/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "days": days,
                "metric": metric,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    NeuronsAnalyticsDashboardResponse,
                    parse_obj_as(
                        type_=NeuronsAnalyticsDashboardResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return AsyncHttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    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,
    ) -> AsyncHttpResponse[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
        -------
        AsyncHttpResponse[NeuronsTrendsResponse]
            Successful Response
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/trends/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "months": months,
                "metric": metric,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    NeuronsTrendsResponse,
                    parse_obj_as(
                        type_=NeuronsTrendsResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return AsyncHttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    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,
    ) -> AsyncHttpResponse[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
        -------
        AsyncHttpResponse[NeuronsOptimizationResponse]
            Successful Response
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/optimization/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "days": days,
                "metric": metric,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    NeuronsOptimizationResponse,
                    parse_obj_as(
                        type_=NeuronsOptimizationResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return AsyncHttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    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,
    ) -> AsyncHttpResponse[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
        -------
        AsyncHttpResponse[NeuronsHeatmapResponse]
            Successful Response
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/heatmap/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "days": days,
                "metric": metric,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    NeuronsHeatmapResponse,
                    parse_obj_as(
                        type_=NeuronsHeatmapResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return AsyncHttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)

    async def get_usage_benchmarks(
        self,
        org_id: str,
        *,
        month: int,
        year: int,
        metric: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> AsyncHttpResponse[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
        -------
        AsyncHttpResponse[NeuronsBenchmarksResponse]
            Successful Response
        """
        _response = await self._client_wrapper.httpx_client.request(
            f"v1/analytics/usage/benchmarks/{jsonable_encoder(org_id)}",
            method="GET",
            params={
                "month": month,
                "year": year,
                "metric": metric,
            },
            request_options=request_options,
        )
        try:
            if 200 <= _response.status_code < 300:
                _data = typing.cast(
                    NeuronsBenchmarksResponse,
                    parse_obj_as(
                        type_=NeuronsBenchmarksResponse,  # type: ignore
                        object_=_response.json(),
                    ),
                )
                return AsyncHttpResponse(response=_response, data=_data)
            if _response.status_code == 422:
                raise UnprocessableEntityError(
                    headers=dict(_response.headers),
                    body=typing.cast(
                        typing.Any,
                        parse_obj_as(
                            type_=typing.Any,  # type: ignore
                            object_=_response.json(),
                        ),
                    ),
                )
            _response_json = _response.json()
        except JSONDecodeError:
            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
