awslabs / awslabs/agentcore-samples

Refactor utils.py into a proper Python module for better maintainability

Open
#586 0 comments 0 reactions 0 assignees View on GitHub
01-tutorials
Dominant language
Python
Stars
3.4k
Forks
1.3k
Avg merge
1d 22h
Merged PRs (30d)
30

Description

## Problem

Currently, utility functions are scattered across multiple `utils.py` files throughout the repository, leading to:

1. **Code duplication**: Same functions (`setup_cognito_user_pool`, `reauthenticate_user`, `create_agentcore_role`) exist in multiple locations with potentially different implementations
2. **Maintenance burden**: Bug fixes and improvements must be replicated across multiple files
3. **Inconsistency**: Different versions of the same function may have different behaviors or bugs
4. **No clear ownership**: Unclear which version is canonical

### Current locations with duplicate utils:
- `01-tutorials/utils.py` (shared)
- `01-tutorials/02-AgentCore-gateway/utils.py`
- `01-tutorials/04-AgentCore-memory/03-advanced-patterns/03-memory-identity-runtime-integration/utils.py`
- `01-tutorials/07-AgentCore-E2E/lab_helpers/utils.py`
- `02-use-cases/finance-personal-assistant/utils/agentcore_utils.py`
- `02-use-cases/farm-management-advisor/utils/utils.py`
- `03-integrations/vector-stores/elasticsearch/utils.py`
- And more...

## Proposed Solution

Refactor `01-tutorials/utils.py` into a proper Python module with clear organization:

```
01-tutorials/
├── utils/
│ ├── __init__.py # Public API exports
│ ├── cognito.py # Cognito-related functions
│ │ ├── setup_cognito_user_pool()
│ │ └── reauthenticate_user()
│ ├── iam.py # IAM role management
│ │ └── create_agentcore_role()
│ └── common.py # Shared utilities
└── [other tutorials]/
```

### Benefits

1. **Single source of truth**: One canonical implementation per function
2. **Better organization**: Functions grouped by functionality
3. **Easier maintenance**: Changes in one place benefit all consumers
4. **Clear imports**: `from utils.cognito import setup_cognito_user_pool`
5. **Testability**: Easier to write unit tests for isolated modules
6. **Documentation**: Can add proper docstrings and type hints per module

## Implementation Plan

### Phase 1: Create module structure
- Create `01-tutorials/utils/` directory
- Move functions from `utils.py` to appropriate modules
- Create `__init__.py` with backward-compatible imports
- Add proper docstrings and type hints

### Phase 2: Update notebooks
- Update all notebooks in `01-tutorials/` to use new imports
- Maintain backward compatibility during transition
- Test all affected notebooks

### Phase 3: Consolidate duplicates
- Identify and remove duplicate implementations
- Update other directories to import from shared utils
- Document any intentional variations

### Phase 4: Deprecation (optional)
- Add deprecation warnings for old import patterns
- Provide migration guide
- Eventually remove backward compatibility layer

## Migration Example

**Before:**
```python
from utils import setup_cognito_user_pool, create_agentcore_role
```

**After (with backward compatibility):**
```python
# Still works during transition
from utils import setup_cognito_user_pool, create_agentcore_role

# Or use new explicit imports
from utils.cognito import setup_cognito_user_pool
from utils.iam import create_agentcore_role
```

## Affected Components

### Notebooks using these functions:
- Identity tutorials (Inbound/Outbound Auth)
- Gateway tutorials
- Memory integration tutorials
- Runtime tutorials
- Browser tool tutorials
- Finance personal assistant use case
- Farm management advisor use case

### Functions to organize:
- `setup_cognito_user_pool()` → `utils/cognito.py`
- `reauthenticate_user()` → `utils/cognito.py`
- `create_agentcore_role()` → `utils/iam.py`
- Other shared utilities → `utils/common.py`

## Success Criteria

- [ ] All utility functions organized into logical modules
- [ ] All notebooks updated and tested
- [ ] Duplicate implementations removed or documented
- [ ] Backward compatibility maintained during transition
- [ ] Documentation updated with new import patterns
- [ ] CI/CD passes for all affected notebooks

## Related Issues

This refactoring would also address:
- Security concerns (hardcoded credentials can be fixed once)
- IAM role creation improvements (single place to enhance)
- Consistent error handling across all utilities

---

**Note**: This is a breaking change that requires careful coordination. Suggest implementing with backward compatibility first, then gradually migrating notebooks.

Contributor guide

Open the contributing guide

Research direction

Start by reading 01-tutorials/utils.py and comparing it with the listed duplicate files, especially the AgentCore tutorial utilities. Inventory notebook imports and run the affected notebook or CI checks before changing structure. Done means the planned modules, imports, compatibility behavior, duplicate handling, and documentation are addressed across the listed components.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.