Gemini Added Memories

My Role and Operating Principles

I am an interactive CLI agent assisting with software engineering tasks for One Sky IT, LLC, primarily on the Aether API project. My core mandates include:

Adhering to project conventions and existing code style.
Never assuming library/framework availability; always verifying project usage.
Implementing changes idiomatically and with minimal, high-value comments.
Being proactive, including adding tests for new features/fixes.
Confirming ambiguity or actions beyond clear scope with the user.
Prioritizing user control and project conventions.
Strictly adhering to instructions and utilizing available tools effectively.
Awaiting explicit user instructions for significant architectural changes or critical decisions.

Project Context - Aether API (FastAPI)

Owner/Developer: Scott Idem (user).
System Name: Aether (AE).
Purpose: Events Presentation Management, Events Badge Printing, Leads, Attendee Tracking, Presentation Launcher, Journals, Archives, Posts.
Started: Mid-2018.
Frontend History: Python Flask -> Svelte (current: SvelteKit). This explains legacy API calls.
Current API Version (FastAPI): Roughly v2.5.
Target API Version: v3.

API Versioning & Strategy

/crud (v1): Legacy, still used by some older frontend parts. Defined in app/routers/api_crud.py. Remains untouched.
/v2/crud (v2.5): Modern, preferred, and mostly functional endpoint. Defined in app/routers/api_crud_v2.py. Remains untouched.
/v3/crud: The goal of this project phase. A new, parallel implementation with a refined structure. Will run alongside v1 and v2.

V3 Architectural Goals

Nested URL Structure: Enforce hierarchical relationships (e.g., /v3/crud/{parent_type}/{parent_id}/{child_type}/...).
Dedicated Router: All v3 functionality will reside in app/routers/api_crud_v3.py.
Data-Driven Configuration: Leverage obj_type_kv_li in app/ae_obj_types_def.py for object definitions (tables, models).

Session Learnings & Progress (December 3, 2025)

Strategy Shift & V3 Development

Initial Plan Shift: The strategy shifted from migrating/replacing existing v1/v2 routes to building a new, parallel v3 implementation from scratch. All existing v1/v2 routes will remain untouched.
V3 Stub Endpoint (Phase 1 Completed): Successfully created app/routers/api_crud_v3.py and mounted it at /v3/crud in app/main.py with a working /health endpoint.

V3 CRUD Proof-of-Concept (Journal & Journal Entry - Phase 2 & 3 Completed)

Implemented the full CRUD functionality for journal (top-level) and journal_entry (nested child object), demonstrating the v3 nested URL structure and its underlying logic:

Top-Level Journal CRUD:
- GET /v3/crud/journal/{journal_id}
- GET /v3/crud/journal/ (list, with filtering via for_obj_type, for_obj_id, and jp)
- POST /v3/crud/journal/
- PATCH /v3/crud/journal/{journal_id}
- DELETE /v3/crud/journal/{journal_id}
Nested Journal Entry CRUD:
- GET /v3/crud/journal/{journal_id}/journal_entry/ (list)
- POST /v3/crud/journal/{journal_id}/journal_entry/
- GET /v3/crud/journal/{journal_id}/journal_entry/{entry_id}
- PATCH /v3/crud/journal/{journal_id}/journal_entry/{entry_id}
- DELETE /v3/crud/journal/{journal_id}/journal_entry/{entry_id}

Soft-Delete Functionality: DELETE endpoints now support a method query parameter (delete, disable, hide) for soft-deleting (setting enable=False or hide=True) or hard-deleting records, mirroring v2 behavior.
Optional Delay Parameter: All v3 CRUD functions include x_delay_ms (header) and delay_ms (query) parameters for simulating network latency or rate limiting via time.sleep().

Current Task: Common Parameters Refactoring (Reverted)

Goal: Refactor the current monolithic commons: Common_Route_Params dependency into smaller, more granular FastAPI dependencies.
Status: A full-scale refactoring was attempted, introducing a new app/lib_general_v3.py file and modifying api_crud_v3.py, main.py, and models/response_models.py. This resulted in persistent "Worker failed to boot" errors that were difficult to debug without direct log access. The changes were reverted to a known working commit (98b980cf) to restore application functionality.

Operational Learnings

File Location: The GEMINI.md file must always be located in the project root directory.
Communication for Major Refactoring: For significant architectural changes, explicit user approval of a detailed proposal is required before implementation begins.
Documentation Strategy: Major proposals will be documented in dedicated Markdown files within the documentation/ directory to facilitate clear communication and asynchronous feedback.
Startup Errors & Logging: The "worker failed to boot" error is highly indicative of an import-time error (e.g., circular dependency, missing module, or misconfiguration). A common cause is the logging configuration in app/log.py failing due to an uninitialized setting or file path issue.
Refactoring Strategy - Incremental Approach Required: The "big bang" approach to refactoring proved difficult to debug. A more incremental strategy is required for the next attempt:
1. Isolate Logging: First, refactor all modules (e.g., main.py, models/response_models.py) to instantiate their own module-level logger (logger = logging.getLogger(__name__)) instead of importing a global log instance from app.log. This will break potential circular dependencies related to logging.
2. Introduce Dependencies One-by-One: Introduce new dependencies from lib_general_v3.py one at a time.
3. Apply to One Endpoint: Apply each new dependency to a single, simple endpoint (like health_check) and confirm the application boots.
4. Verify at Each Step: This incremental verification is crucial in an environment without direct, real-time log access.
Preservation of Work: The attempted refactoring work has been preserved in .snapshot files for future reference.

Learnings from previous session (December 2, 2025):

Docker Environment Challenges: Debugging issues in a Dockerized FastAPI environment when running locally (outside the container's execution context) is significantly more challenging due to environment mismatches and symlinked executables. Direct uvicorn execution for debugging is not viable in this setup. This necessitates an approach that can either:
- Execute Python code snippets directly (e.g., for import validation).
- Rely on external tools (like curl or requests from another script) to interact with the Dockerized API for runtime testing.
- Assume that the Docker container provides the authoritative runtime environment, and local checks are primarily for static analysis (syntax, imports).
Need for Incremental Verification: Given the complexity of the project and the debugging constraints, future changes must be exceptionally small, incremental, and verified through a robust testing strategy that can be executed, ideally, within the Docker environment or through isolated Python scripts.
Pydantic BaseModel Import: Simple Pydantic BaseModel imports can be forgotten, leading to NameError. This highlights the need for automated linting or a minimal test harness that can quickly validate new model definitions in isolation.
Legacy Code vs. New Code: When encountering errors, it's crucial to distinguish whether the error is in the new code being introduced or in existing legacy code that might have subtle interactions. The 422 Unprocessable Entity errors were occurring in the legacy /crud/ endpoints. This indicates that while our new factory code itself didn't cause those specific runtime errors, interactions or an underlying pre-existing issue became apparent when the application was loading.
parent_table_name for Nested CRUD: The implementation detail of passing parent_table_name (or similar context) to child CRUD operations is essential for correctly linking nested resources in the database layer. The router factory's child object creation needs to pass this context explicitly.
API Endpoint Naming Convention: The user prefers singular nouns for API endpoints (e.g., /journal, /journal_entry) over plural forms (e.g., /journals, /journal_entries). This convention will be followed for all new router creations.

8.6 KiB Raw Blame History