---
title: "Implementation Plan: Network Executor and iModel Refactor"
by: "@khive-implementer"
created: 2025-05-20
updated: 2025-05-20
version: 1.0
doc_type: IP
output_subdir: ip
description: >
  Implementation plan for the new lionfuncs.network.executor.Executor class,
  the NetworkRequestEvent, and the creation of iModel to use the Executor.
date: 2025-05-20
author: "@khive-implementer"
status: "Draft"
issue_url: "https://github.com/khive-ai/lionfuncs/issues/17"
research_report_url: ".khive/reports/rr/RR-17.md"
technical_design_url: ".khive/reports/tds/TDS-17.md"
---

# Implementation Plan: Network Executor and iModel Refactor

## 1. Overview

This document outlines the implementation plan for Issue #17, which involves
creating a new `Executor` class for managing and rate-limiting API calls, a
`NetworkRequestEvent` class for tracking request lifecycles, and implementing
the `iModel` class to utilize the new `Executor`.

## 2. Implementation Steps

### 2.1. Create Network Events Module

**File:** `src/lionfuncs/network/events.py`

1. Implement `RequestStatus` enum with states:
   - `PENDING`
   - `QUEUED`
   - `PROCESSING`
   - `CALLING`
   - `COMPLETED`
   - `FAILED`
   - `CANCELLED`

2. Implement `NetworkRequestEvent` dataclass with:
   - Request details (ID, URL, method, headers, payload)
   - Status tracking
   - Response details
   - Error details
   - Timing information
   - Logs and metadata
   - Methods for status updates and result/error setting

### 2.2. Create Network Executor Module

**File:** `src/lionfuncs/network/executor.py`

1. Implement `Executor` class with:
   - Constructor that initializes:
     - `WorkQueue` for task management
     - `CapacityLimiter` for concurrency control
     - `TokenBucketRateLimiter` for requests per interval
     - `TokenBucketRateLimiter` for API tokens per interval (optional)
   - Internal worker method for processing tasks
   - Task submission method
   - Start/stop methods
   - Context manager support

### 2.3. Create iModel Class

**File:** `src/lionfuncs/network/imodel.py`

1. Implement `iModel` class with:
   - Constructor that accepts an `Executor` instance and configuration
   - HTTP session management
   - API call methods that use the `Executor`
   - Context manager support

### 2.4. Update Network Package Exports

**File:** `src/lionfuncs/network/__init__.py`

1. Export new classes:
   - `NetworkRequestEvent`
   - `RequestStatus`
   - `Executor`
   - `iModel`

### 2.5. Write Unit Tests

1. Test `NetworkRequestEvent` class:
   - Initialization and default values
   - Status updates and timestamp tracking
   - Result and error setting
   - Log addition

2. Test `Executor` class:
   - Initialization with various configurations
   - Task submission
   - Start/stop functionality
   - Worker behavior with mocked API calls
   - Rate limiting behavior
   - Concurrency limiting behavior
   - Error handling

3. Test `iModel` class:
   - Initialization with `Executor` and configuration
   - API call methods
   - Integration with `Executor`
   - Error handling

## 3. Implementation Details

### 3.1. NetworkRequestEvent Implementation

The `NetworkRequestEvent` class will be implemented as a dataclass with fields
for tracking the lifecycle of an API request. It will include methods for
updating status, setting results, and recording errors.

Key considerations:

- Use `datetime.datetime.utcnow()` for timestamps
- Include detailed error information including traceback
- Maintain a log of status changes and other events

### 3.2. Executor Implementation

The `Executor` class will orchestrate the API call process using existing
`lionfuncs` primitives. It will manage a queue of tasks, control concurrency,
and enforce rate limits.

Key considerations:

- Use `WorkQueue` for task management
- Use `CapacityLimiter` for concurrency control
- Use two instances of `TokenBucketRateLimiter` for rate limiting
- Implement proper error handling and resource cleanup
- Ensure graceful shutdown

### 3.3. iModel Implementation

The `iModel` class will be a client for interacting with API models. It will use
the `Executor` for making API calls with proper rate limiting.

Key considerations:

- Accept an `Executor` instance in the constructor
- Accept configuration as `EndpointConfig` or dictionary
- Manage HTTP session lifecycle
- Implement API call methods that use the `Executor`
- Handle API-specific token consumption

## 4. Testing Strategy

### 4.1. Unit Tests

Unit tests will be written for each class to verify their behavior in isolation.
Mock objects will be used to simulate dependencies.

### 4.2. Integration Tests

Integration tests will verify that the classes work together correctly. These
tests will focus on the interaction between `iModel` and `Executor`.

### 4.3. Test Coverage

The goal is to achieve >80% test coverage for the new code. Tests will cover:

- Normal operation
- Error handling
- Edge cases
- Rate limiting behavior
- Concurrency control

## 5. Implementation Timeline

1. Create `events.py` with `NetworkRequestEvent` and `RequestStatus` - 1 hour
2. Create `executor.py` with `Executor` class - 2 hours
3. Create `imodel.py` with `iModel` class - 1 hour
4. Update package exports - 15 minutes
5. Write unit tests - 2 hours
6. Test and refine - 1 hour

Total estimated time: 7.25 hours

## 6. Potential Challenges and Mitigations

### 6.1. Concurrency Issues

**Challenge:** Ensuring proper coordination between multiple asynchronous
components.

**Mitigation:** Leverage existing tested primitives (`WorkQueue`,
`CapacityLimiter`, `TokenBucketRateLimiter`) and follow established patterns for
asyncio programming.

### 6.2. Rate Limiting Accuracy

**Challenge:** Ensuring rate limits are enforced accurately, especially with
multiple concurrent requests.

**Mitigation:** Use the proven `TokenBucketRateLimiter` implementation and add
comprehensive tests for rate limiting behavior.

### 6.3. Error Handling

**Challenge:** Properly handling and propagating errors from various components.

**Mitigation:** Implement robust error handling in the `Executor` worker and
ensure errors are properly recorded in the `NetworkRequestEvent`.

## 7. Conclusion

This implementation plan outlines the steps to create a robust, configurable,
and observable system for making rate-limited API calls. By following this plan,
we will deliver a solution that meets the requirements specified in the
Technical Design Specification while ensuring code quality and maintainability.
