feat: rename app.resource to app.retrieve (#82)

Author: simba-git

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.2] - 2025-06-19
+
+### Changed
+- Renamed `app.resource` decorator to `app.retrieve`. `app.resource` remains
+  as a deprecated alias.
+
+### Added
+- Support for marking fields as mutable with `mutable=True` and CRUD example
+- BigInteger column type handling for SQLAlchemy integration
+- Example smoke tests and improved OpenAI chat example
+- Optional cleanup for SQLAlchemy lifespans
+- Detailed ROBOTS guide and CI improvements
+
 ## [0.4.1] - 2025-06-15
 
 ### Fixed

README.md

@@ -113,7 +113,7 @@ class Order(EnrichModel):
     customer: Customer = Relationship(description="Customer who placed this order")
 
 # Define how to fetch data
-@app.resource
+@app.retrieve
 async def get_customer(customer_id: int) -> Customer:
     """Fetch customer from CRM API."""
     response = await http.get(f"/api/customers/{customer_id}")
@@ -165,7 +165,7 @@ class Segment(EnrichModel):
     users: list[User] = Relationship(description="Users in this segment")
 
 # Complex resource with business logic
-@app.resource
+@app.retrieve
 async def find_high_value_at_risk_users(
     lifetime_value_min: Decimal = 1000,
     churn_risk_min: float = 0.7,
@@ -269,7 +269,7 @@ Handle large datasets elegantly:
 ```python
 from enrichmcp import PageResult
 
-@app.resource
+@app.retrieve
 async def list_orders(
     page: int = 1,
     page_size: int = 50
@@ -290,7 +290,7 @@ See the [Pagination Guide](https://featureform.github.io/enrichmcp/pagination) f
 Pass auth, database connections, or any context:
 
 ```python
-@app.resource
+@app.retrieve
 async def get_user_profile(user_id: int, context: EnrichContext) -> UserProfile:
     # Access context provided by MCP client
     auth_user = context.get("authenticated_user_id")

docs/api.md

@@ -72,7 +72,7 @@ async def get_user_orders(user_id: int) -> list["Order"]:
 Resources are the entry points for AI agents:
 
 ```python
-@app.resource
+@app.retrieve
 async def list_users() -> list[User]:
     """List all users in the system."""
     return fetch_all_users()

docs/api/app.md

@@ -46,9 +46,10 @@ class User(EnrichModel):
     name: str = Field(description="Username")
 ```
 
-### `resource(func=None, *, name=None, description=None)`
+### `retrieve(func=None, *, name=None, description=None)`
 
-Decorator to register a function as an MCP resource.
+Register a function as an MCP resource.
+`app.resource` is deprecated and forwards to this method.
 
 **Parameters:**
 - `func`: The function (when used without parentheses)
@@ -57,15 +58,15 @@ Decorator to register a function as an MCP resource.
 
 **Example:**
 ```python
-@app.resource
+@app.retrieve
 async def list_users() -> list[User]:
     """List all users in the system."""
     return await fetch_all_users()
 ```
 
 ### `create(func=None, *, name=None, description=None)`
 
-Register an entity creation operation. Works like `@app.resource` but
+Register an entity creation operation. Works like `@app.retrieve` but
 indicates a create action.
 
 ```python
@@ -214,7 +215,7 @@ async def get_book_author(book_id: int) -> Author:
 
 
 # Define resources
-@app.resource
+@app.retrieve
 async def list_authors() -> list[Author]:
     """List all authors."""
     # Implementation here

docs/api/context.md

@@ -45,7 +45,7 @@ class MyContext(EnrichContext):
 
 
 # Use in resources
-@app.resource
+@app.retrieve
 async def get_data(context: MyContext) -> dict:
     # Use your custom context
     return await context.db.fetch_data()

docs/api/errors.md

@@ -33,7 +33,7 @@ except ValidationError as e:
 Use Python's standard exceptions:
 
 ```python
-@app.resource
+@app.retrieve
 async def get_user(user_id: int) -> User:
     user = find_user(user_id)
     if not user:

docs/concepts.md

@@ -149,7 +149,7 @@ async def get_orders(customer_id: int, limit: int = 10, offset: int = 0) -> list
 Resources are the entry points for AI agents:
 
 ```python
-@app.resource
+@app.retrieve
 async def get_customer(customer_id: int) -> Customer:
     """Retrieve a customer by ID.
 
@@ -162,7 +162,7 @@ async def get_customer(customer_id: int) -> Customer:
     return customer
 
 
-@app.resource
+@app.retrieve
 async def search_customers(query: str, status: str | None = None) -> list[Customer]:
     """Search for customers by name or email.
 
@@ -194,7 +194,7 @@ class AppContext(EnrichContext):
     user: User | None = None
 
 
-@app.resource
+@app.retrieve
 async def get_customer(customer_id: int, context: AppContext) -> Customer:
     """Get customer using context."""
     # Check cache first
@@ -236,7 +236,7 @@ enrichmcp leverages Pydantic for comprehensive validation:
 
 ```python
 # This automatically validates inputs
-@app.resource
+@app.retrieve
 async def create_customer(
     email: EmailStr,  # Validates email format
     age: int = Field(ge=18, le=150),  # Range validation
@@ -255,7 +255,7 @@ EnrichMCP extends FastMCP's context system to provide automatic injection of log
 Any resource or resolver can receive context by adding a parameter typed as `EnrichContext`:
 
 ```python
-@app.resource
+@app.retrieve
 async def my_resource(param: str, ctx: EnrichContext) -> Result:
     # Context is automatically injected
     await ctx.info("Processing request")
@@ -325,7 +325,7 @@ Use semantic errors that AI agents understand:
 from enrichmcp.errors import NotFoundError, ValidationError, AuthorizationError
 
 
-@app.resource
+@app.retrieve
 async def get_order(order_id: int, context: AppContext) -> Order:
     order = await context.db.get_order(order_id)
 

docs/examples.md

@@ -110,13 +110,13 @@ async def get_book_author(book_id: int) -> "Author":
 
 
 # Define root resources
-@app.resource
+@app.retrieve
 async def list_authors() -> list[Author]:
     """List all authors in the catalog."""
     return [Author(**author_data) for author_data in AUTHORS]
 
 
-@app.resource
+@app.retrieve
 async def get_author(author_id: int) -> Author:
     """Get a specific author by ID."""
     author_data = next((a for a in AUTHORS if a["id"] == author_id), None)
@@ -126,13 +126,13 @@ async def get_author(author_id: int) -> Author:
     return Author(id=-1, name="Not Found", bio="Author not found", birth_date=date(1900, 1, 1))
 
 
-@app.resource
+@app.retrieve
 async def list_books() -> list[Book]:
     """List all books in the catalog."""
     return [Book(**book_data) for book_data in BOOKS]
 
 
-@app.resource
+@app.retrieve
 async def search_books(title_contains: str) -> list[Book]:
     """Search for books by title."""
     matching_books = [book for book in BOOKS if title_contains.lower() in book["title"].lower()]
@@ -283,13 +283,13 @@ async def get_task_project(task_id: int) -> "Project":
 
 
 # Resources
-@app.resource
+@app.retrieve
 async def list_projects() -> list[Project]:
     """List all projects."""
     return [Project(**project_data) for project_data in PROJECTS]
 
 
-@app.resource
+@app.retrieve
 async def list_tasks(status: Status | None = None, priority: Priority | None = None) -> list[Task]:
     """List tasks with optional filtering."""
     filtered_tasks = TASKS
@@ -303,7 +303,7 @@ async def list_tasks(status: Status | None = None, priority: Priority | None = N
     return [Task(**task_data) for task_data in filtered_tasks]
 
 
-@app.resource
+@app.retrieve
 async def get_project_summary(project_id: int) -> dict:
     """Get summary statistics for a project."""
     project_tasks = [t for t in TASKS if t["project_id"] == project_id]
@@ -421,13 +421,13 @@ async def get_ingredient_recipes(ingredient_id: int) -> list["Recipe"]:
 
 
 # Resources
-@app.resource
+@app.retrieve
 async def list_recipes() -> list[Recipe]:
     """List all recipes."""
     return [Recipe(**recipe_data) for recipe_data in RECIPES]
 
 
-@app.resource
+@app.retrieve
 async def search_recipes_by_ingredient(ingredient_name: str) -> list[Recipe]:
     """Find recipes containing a specific ingredient."""
     # Find ingredient
@@ -442,7 +442,7 @@ async def search_recipes_by_ingredient(ingredient_name: str) -> list[Recipe]:
     return await get_ingredient_recipes(ingredient["id"])
 
 
-@app.resource
+@app.retrieve
 async def get_quick_recipes(max_time: int = 30) -> list[Recipe]:
     """Get recipes that can be made quickly."""
     quick_recipes = [
@@ -459,7 +459,7 @@ These examples demonstrate:
 - Basic entity definition with `@app.entity`
 - Relationship definition with `Relationship()`
 - Resolver implementation with `@Entity.field.resolver`
-- Resource creation with `@app.resource`
+- Resource creation with `@app.retrieve`
 - Simple in-memory data storage
 - Filtering and searching patterns
 
@@ -472,4 +472,4 @@ can generate entities and resolvers directly from SQLAlchemy models. It works
 with any async database backend supported by SQLAlchemy (for example
 PostgreSQL with `asyncpg`).
 
-The `examples/shop_api_gateway` project shows how EnrichMCP can act as a simple API gateway in front of another FastAPI service.
+The `examples/shop_api_gateway` project shows how EnrichMCP can act as a simple API gateway in front of another FastAPI service.

docs/getting-started.md

@@ -126,7 +126,7 @@ async def get_book_author(book_id: int) -> Author:
 
 
 # Define root resources
-@app.resource
+@app.retrieve
 async def list_books() -> list[Book]:
     """List all books in the catalog."""
     return [
@@ -140,7 +140,7 @@ async def list_books() -> list[Book]:
     ]
 
 
-@app.resource
+@app.retrieve
 async def get_author(author_id: int) -> Author:
     """Get a specific author by ID."""
     return Author(id=author_id, name="Jane Doe", bio="Bestselling author")
@@ -175,7 +175,7 @@ app = EnrichMCP("My API", "Description", lifespan=lifespan)
 
 
 # Use context in resources and resolvers
-@app.resource
+@app.retrieve
 async def get_user(user_id: int, ctx: EnrichContext) -> User:
     # Logging
     await ctx.info(f"Fetching user {user_id}")

docs/index.md

@@ -45,7 +45,7 @@ async def get_customer_orders(customer_id: int) -> list[Order]:
 
 
 # Create entry points for AI
-@app.resource
+@app.retrieve
 async def get_customer(customer_id: int) -> Customer:
     """Get a customer by ID."""
     return await db.get_customer(customer_id)