Feature: Function Tracking Decorator

This PR adds a straightforward decorator, `@track_function`, that makes it easy to log details about function calls. It works on synchronous and asynchronous functions, generators (sync and async), and class methods—all with a consistent interface.

Key Points:
- Versatile Support: Works with regular functions, async functions, generators, and even class methods.
- Optional Metadata: You can add extra context by passing a dictionary to the decorator. Metadata keys are validated to ensure they’re strings.
- Data Serialization: Automatically serializes input arguments and outputs (or each yield) into a JSON-friendly format. It even handles Pydantic models by calling model_dump() if needed.
- Intermediate Event Logging: The decorator sends tracking events to a reactive stream in three stages:
-- SPAN_START: When the function starts.
-- SPAN_CHUNK: For each yielded item (for generators).
-- SPAN_END: When the function returns (or ends in generators).

Usage Example:

```python
from aiq.profiler.decorators.function_tracking import track_function

@track_function(metadata={"action": "compute", "source": "api"})
def add_numbers(a, b):
    return a + b
```
Just apply `@track_function` to any function (or method) where you need a bit of extra insight into the inputs and outputs. Subscribe to the reactive stream to see the published events and get a better sense of the function’s flow.

## By Submitting this PR I confirm:
- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/AgentIQ/blob/develop/docs/source/advanced/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.

Authors:
  - Dhruv Nandakumar (https://github.com/dnandakumar-nv)

Approvers:
  - Michael Demoret (https://github.com/mdemoret-nv)

URL: NVIDIA#98
Signed-off-by: Yuchen Zhang <134643420+yczhang-nv@users.noreply.github.com>

Feature: Function Tracking Decorator

This PR adds a straightforward decorator, `@track_function`, that makes it easy to log details about function calls. It works on synchronous and asynchronous functions, generators (sync and async), and class methods—all with a consistent interface.

Key Points:
- Versatile Support: Works with regular functions, async functions, generators, and even class methods.
- Optional Metadata: You can add extra context by passing a dictionary to the decorator. Metadata keys are validated to ensure they’re strings.
- Data Serialization: Automatically serializes input arguments and outputs (or each yield) into a JSON-friendly format. It even handles Pydantic models by calling model_dump() if needed.
- Intermediate Event Logging: The decorator sends tracking events to a reactive stream in three stages:
-- SPAN_START: When the function starts.
-- SPAN_CHUNK: For each yielded item (for generators).
-- SPAN_END: When the function returns (or ends in generators).

Usage Example:

```python
from aiq.profiler.decorators.function_tracking import track_function

@track_function(metadata={"action": "compute", "source": "api"})
def add_numbers(a, b):
    return a + b
```
Just apply `@track_function` to any function (or method) where you need a bit of extra insight into the inputs and outputs. Subscribe to the reactive stream to see the published events and get a better sense of the function’s flow.

## By Submitting this PR I confirm:
- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/AgentIQ/blob/develop/docs/source/advanced/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.

Authors:
  - Dhruv Nandakumar (https://github.com/dnandakumar-nv)

Approvers:
  - Michael Demoret (https://github.com/mdemoret-nv)

URL: NVIDIA#98
Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com>

Feature: Function Tracking Decorator

This PR adds a straightforward decorator, `@track_function`, that makes it easy to log details about function calls. It works on synchronous and asynchronous functions, generators (sync and async), and class methods—all with a consistent interface.

Key Points:
- Versatile Support: Works with regular functions, async functions, generators, and even class methods.
- Optional Metadata: You can add extra context by passing a dictionary to the decorator. Metadata keys are validated to ensure they’re strings.
- Data Serialization: Automatically serializes input arguments and outputs (or each yield) into a JSON-friendly format. It even handles Pydantic models by calling model_dump() if needed.
- Intermediate Event Logging: The decorator sends tracking events to a reactive stream in three stages:
-- SPAN_START: When the function starts.
-- SPAN_CHUNK: For each yielded item (for generators).
-- SPAN_END: When the function returns (or ends in generators).

Usage Example:

```python
from aiq.profiler.decorators.function_tracking import track_function

@track_function(metadata={"action": "compute", "source": "api"})
def add_numbers(a, b):
    return a + b
```
Just apply `@track_function` to any function (or method) where you need a bit of extra insight into the inputs and outputs. Subscribe to the reactive stream to see the published events and get a better sense of the function’s flow.

## By Submitting this PR I confirm:
- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/AgentIQ/blob/develop/docs/source/advanced/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.

Authors:
  - Dhruv Nandakumar (https://github.com/dnandakumar-nv)

Approvers:
  - Michael Demoret (https://github.com/mdemoret-nv)

URL: NVIDIA#98
Signed-off-by: Eric Evans <194135482+ericevans-nv@users.noreply.github.com>

Feature: Function Tracking Decorator

This PR adds a straightforward decorator, `@track_function`, that makes it easy to log details about function calls. It works on synchronous and asynchronous functions, generators (sync and async), and class methods—all with a consistent interface.

Key Points:
- Versatile Support: Works with regular functions, async functions, generators, and even class methods.
- Optional Metadata: You can add extra context by passing a dictionary to the decorator. Metadata keys are validated to ensure they’re strings.
- Data Serialization: Automatically serializes input arguments and outputs (or each yield) into a JSON-friendly format. It even handles Pydantic models by calling model_dump() if needed.
- Intermediate Event Logging: The decorator sends tracking events to a reactive stream in three stages:
-- SPAN_START: When the function starts.
-- SPAN_CHUNK: For each yielded item (for generators).
-- SPAN_END: When the function returns (or ends in generators).

Usage Example:

```python
from aiq.profiler.decorators.function_tracking import track_function

@track_function(metadata={"action": "compute", "source": "api"})
def add_numbers(a, b):
    return a + b
```
Just apply `@track_function` to any function (or method) where you need a bit of extra insight into the inputs and outputs. Subscribe to the reactive stream to see the published events and get a better sense of the function’s flow.

## By Submitting this PR I confirm:
- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/AgentIQ/blob/develop/docs/source/advanced/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.

Authors:
  - Dhruv Nandakumar (https://github.com/dnandakumar-nv)

Approvers:
  - Michael Demoret (https://github.com/mdemoret-nv)

URL: NVIDIA#98
Signed-off-by: Yuchen Zhang <134643420+yczhang-nv@users.noreply.github.com>

Feature: Function Tracking Decorator

This PR adds a straightforward decorator, `@track_function`, that makes it easy to log details about function calls. It works on synchronous and asynchronous functions, generators (sync and async), and class methods—all with a consistent interface.

Key Points:
- Versatile Support: Works with regular functions, async functions, generators, and even class methods.
- Optional Metadata: You can add extra context by passing a dictionary to the decorator. Metadata keys are validated to ensure they’re strings.
- Data Serialization: Automatically serializes input arguments and outputs (or each yield) into a JSON-friendly format. It even handles Pydantic models by calling model_dump() if needed.
- Intermediate Event Logging: The decorator sends tracking events to a reactive stream in three stages:
-- SPAN_START: When the function starts.
-- SPAN_CHUNK: For each yielded item (for generators).
-- SPAN_END: When the function returns (or ends in generators).

Usage Example:

```python
from aiq.profiler.decorators.function_tracking import track_function

@track_function(metadata={"action": "compute", "source": "api"})
def add_numbers(a, b):
    return a + b
```
Just apply `@track_function` to any function (or method) where you need a bit of extra insight into the inputs and outputs. Subscribe to the reactive stream to see the published events and get a better sense of the function’s flow.

## By Submitting this PR I confirm:
- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/AgentIQ/blob/develop/docs/source/advanced/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.

Authors:
  - Dhruv Nandakumar (https://github.com/dnandakumar-nv)

Approvers:
  - Michael Demoret (https://github.com/mdemoret-nv)

URL: NVIDIA#98

Feature: Function Tracking Decorator

This PR adds a straightforward decorator, `@track_function`, that makes it easy to log details about function calls. It works on synchronous and asynchronous functions, generators (sync and async), and class methods—all with a consistent interface.

Key Points:
- Versatile Support: Works with regular functions, async functions, generators, and even class methods.
- Optional Metadata: You can add extra context by passing a dictionary to the decorator. Metadata keys are validated to ensure they’re strings.
- Data Serialization: Automatically serializes input arguments and outputs (or each yield) into a JSON-friendly format. It even handles Pydantic models by calling model_dump() if needed.
- Intermediate Event Logging: The decorator sends tracking events to a reactive stream in three stages:
-- SPAN_START: When the function starts.
-- SPAN_CHUNK: For each yielded item (for generators).
-- SPAN_END: When the function returns (or ends in generators).

Usage Example:

```python
from aiq.profiler.decorators.function_tracking import track_function

@track_function(metadata={"action": "compute", "source": "api"})
def add_numbers(a, b):
    return a + b
```
Just apply `@track_function` to any function (or method) where you need a bit of extra insight into the inputs and outputs. Subscribe to the reactive stream to see the published events and get a better sense of the function’s flow.

## By Submitting this PR I confirm:
- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/AgentIQ/blob/develop/docs/source/advanced/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.

Authors:
  - Dhruv Nandakumar (https://github.com/dnandakumar-nv)

Approvers:
  - Michael Demoret (https://github.com/mdemoret-nv)

URL: NVIDIA#98