Semantic operators fixes

README.md

@@ -58,38 +58,40 @@ uv run python examples/hello_world.py
 ## 🧪 Example Usage
 
 ```python
-from typing import Optional
 from pydantic import BaseModel, Field
+from agentics.core.transducible_functions import transducible, Transduce
+
+class ProductDescription(BaseModel):
+    name: str
+    features: str
+    price: float
+
+class ViralTweet(BaseModel):
+    tweet: str = Field(..., description="Engaging tweet under 280 characters")
+    hashtags: list[str] = Field(..., description="3-5 relevant hashtags")
+    hook: str = Field(..., description="Attention-grabbing opening line")
+
+@transducible()
+async def generate_viral_tweet(product: ProductDescription) -> ViralTweet:
+    """Transform boring product descriptions into viral social media content."""
+    return Transduce(product)
+
+# Transform a product into viral content
+product = ProductDescription(
+    name="Agentics Framework",
+    features="Type-safe AI workflows with LLM-powered transductions",
+    price=0.0  # Open source!
+)
 
-from agentics.core.transducible_functions import Transduce, transducible
-
-
-class Movie(BaseModel):
-    movie_name: Optional[str] = None
-    description: Optional[str] = None
-    year: Optional[int] = None
-
-
-class Genre(BaseModel):
-    genre: Optional[str] = Field(None, description="e.g., comedy, drama, action")
-
-
-@transducible(provide_explanation=True)
-async def classify_genre(state: Movie) -> Genre:
-    """Classify the genre of the source Movie."""
-    return Transduce(state)
-
+tweet = await generate_viral_tweet(product)
+print(f"🔥 {tweet.tweet}")
+print(f"📱 {' '.join(tweet.hashtags)}")
+```
 
-genre, explanation = await classify_genre(
-    Movie(
-        movie_name="The Godfather",
-        description=(
-            "The aging patriarch of an organized crime dynasty transfers control "
-            "of his clandestine empire to his reluctant son."
-        ),
-        year=1972,
-    )
-)
+**Output:**
+```
+🔥 Stop wrestling with unstructured LLM outputs! 🎯 Agentics gives you type-safe AI workflows that just work. Build production-ready agents in minutes, not weeks. And it's FREE! 🚀
+📱 #AI #OpenSource #Python #LLM #DevTools
 ```
 
 ---
@@ -126,16 +128,24 @@ Apache 2.0
 
 ## 👥 Authors
 
-**Principal Investigator**
+**Project Lead and Main Contributor**
 - Alfio Massimiliano Gliozzo (IBM Research) — gliozzo@us.ibm.com
 
 **Core Contributors**
-- Nahuel Defosse (IBM Research) — nahuel.defosse@ibm.com
-- Junkyu Lee (IBM Research) — Junkyu.Lee@ibm.com
-- Naweed Aghmad Khan (IBM Research) — naweed.khan@ibm.com
-- Christodoulos Constantinides (IBM Watson) — Christodoulos.Constantinides@ibm.com
-- Mustafa Eyceoz (Red Hat) — Mustafa.Eyceoz@partner.ibm.com
+- Junkyu Lee (IBM) — Junkyu.Lee@ibm.com
+- Nahuel Defosse (IBM) — nahuel.defosse@ibm.com
+- Naweed Aghmad Khan (IBM) — naweed.khan@ibm.com
 
+**Community Contributors**
+- Christodoulos Constantinides (IBM) — Christodoulos.Constantinides@ibm.com
+- Nandana Mihindukulasooriya (IBM) — nandana@ibm.com
+- Mustafa Eyceoz (Red Hat) — Mustafa.Eyceoz@partner.ibm.com
+- Gaetano Rossiello (IBM) — gaetano.rossiello@ibm.com
+- Agostino Capponi (Columbia University) — ac3827@columbia.edu
+- Chunghyun Han (Columbia University) — ch4005@columbia.edu
+- Abhinav Goel (Columbia University) ag5252@columbia.edu
+- Chaitya Shan (Columbia University) — cs4621@columbia.edu
+- Brian Zi Qi Zhu (Columbia University) — bzz2101@columbia.edu
 ---
 
 

docs/agentics.md

@@ -1,11 +1,20 @@
-# Agentics
+# AG (Agentics)
 
-Agentics objects are wrappers around list of objects having the same Pydantic Type.
+**AG** (short for "Agentics") objects are wrappers around lists of objects having the same Pydantic type.
 They are designed to enable async logical transduction among their instances.
-Agentics enable us to think about AI workflows in terms of structured data transformations rather than agent behaviours, knowledge and tasks. 
+AG containers enable us to think about AI workflows in terms of structured data transformations rather than agent behaviors, knowledge, and tasks.
 
-## The Agentics class
-Agentics is a Python class that wraps a list of Pydantic objects and enables structured, type-driven logical transduction between them.
+## The AG Class
+
+AG (Agentics) is a Python class that wraps a list of Pydantic objects and enables structured, type-driven logical transduction between them.
+
+**Import and Usage:**
+```python
+from agentics import AG  # Recommended: use AG alias
+
+# Create a typed container
+movies = AG(atype=Movie)
+```
 
 Internally, Agentics is implemented as a Pydantic model. It holds:
 	•	atype: a reference to the Pydantic class shared by all objects in the list.
@@ -105,15 +114,16 @@ print(movies.states[0])
 
 ```
 
-You can also modify and rebind an exiting Agentic. Similarly can also remove attributes. The following code is equivalent to the code before
+You can also modify and rebind an exiting Agentic. Similarly can also remove attributes. The following code is equivalent to the code before.
 
 ```python
 movies = AG.from_csv("data/orders.csv")
+print(movies[0])
 movies.add_attribute("review",str)
 movies.add_attribute("quality_score",int,description="The quality of the movies in a scale 0 to 10")
 print(movies[0])
 movies.subset_atype("title","genre","description")
-print(movies[0]) ## note that movies[0] is equivalent to 
+print(movies[0]) ## note that movies[0] is a shorthand for movies.states[0]
 ```
 
 
@@ -138,8 +148,7 @@ async def main():
         "What is the best F1 team in history?",
     ]
 
-    answers = await (AG(atype=Answer) \
-                     << input_questions)
+    answers = await (AG(atype=Answer) << input_questions)
 
     answers.pretty_print()
 
@@ -149,9 +158,10 @@ asyncio.run(main())
 
 ## Reference code
 
-[explore this example](src/agentics/examples/agentics_basics.py)
-
+See the [examples directory](../examples/) for practical demonstrations of AG usage, including:
+- `hello_world.py` - Basic transduction example
+- `generate_tweets.py` - Content generation
+- `emotion_extractor.py` - Text analysis
 
-## See Next: Transduction
-
-Wrapping pydantic types into Agentics provides them with the ability to perform transduction, as described in the [next section](transduction.md)
+## Go to Index
+- 👉 [Index](index.md)

docs/core_concepts.md

@@ -6,7 +6,7 @@ Agentics is built around a small set of concepts that work together:
 - **Transducible functions** – LLM-powered, type-safe transformations  
 - **Typed state containers (AGs)** – collections of typed rows/documents  
 - **Logical Transduction Algebra (LTA)** – the formal backbone  
-- **Map–Reduce** – the execution pattern for large workloads  
+- **Map–Reduce** – the programming model used to execute large-scale workloads
 
 This page gives you the mental model you need before diving into code.
 
@@ -20,12 +20,13 @@ You describe your data using **Pydantic models**:
 
 ```python
 from pydantic import BaseModel
+fromp typing import Optional
 
 class Product(BaseModel):
-    id: str | None = None
-    title: str | None = None
-    description: str | None = None
-    price: float | None = None
+    id: Optional[str] = None
+    title: Optional[str] = None
+    description: Optional[str] = None
+    price: Optional[float] = None
 ```
 
 These models serve three roles:
@@ -64,17 +65,17 @@ Example:
 from pydantic import BaseModel
 
 class Review(BaseModel):
-    text: str
+    text: Optional[str] = None
 
 class ReviewSummary(BaseModel):
-    sentiment: str
-    summary: str
+    sentiment: Optional[str] = None
+    summary: Optional[str] = None
 ```
 
 A transducible function might be:
 
 ```python
-fn: (Review) -> ReviewSummary
+fn: Review -> ReviewSummary
 ```
 
 with instructions like:
@@ -92,39 +93,44 @@ You don’t call the LLM directly; you **call the transducible function**, which
 
 ---
 
-## 3. Typed State Containers (AGs): Working with Collections 🗂️
+## 3. Typed State Containers (AG): Working with Collections 🗂️
 
 Transformations rarely happen on a single object. You typically work with **collections** of items (rows, documents, events, etc.).
 
-Agentics introduces **typed state containers** (AG) to:
+Agentics introduces **typed state containers** (called **AG**, short for "Agentics") to:
 
-- Hold a collection of instances of a given Pydantic type  
-- Preserve that type information across operations  
+- Hold a collection of instances of a given Pydantic type
+- Preserve that type information across operations
 - Provide a uniform interface for Map–Reduce, filtering, joining, etc.
 
 
 Conceptually, you can think of an `AG[Source]` like a type-aware table:
 
-
 ```text
 AG[Review]
   ├─ row 0: Review(text="…")
   ├─ row 1: Review(text="…")
   └─ row n: Review(text="…")
 ```
 
-Applying a transducible function `(Review) -> ReviewSummary` over an `AG[Review]` conceptually yields an `AG[ReviewSummary]`.
+Applying a transducible function `Review -> ReviewSummary` over an `AG` with atype `Review` conceptually yields an `AG` of type `ReviewSummary`. 
 
 Typed state containers give you:
 
-- **Clarity** – you always know what type you’re holding.  
-- **Safety** – operations can check types and schemas instead of guessing.  
+- **Clarity** – you always know what type you're holding.
+- **Safety** – operations can check types and schemas instead of guessing.
 - **Composability** – containers can flow between functions and stages.
 
-You can think of state containers as the **data plane** of Agentics.
+You can think of state containers (AGs) as the **data plane** of Agentics.
+
+
+```python
+from agentics import AG  # Recommended alias
 
+movies = AG(atype=Movie)  # Create a typed container
+```
 
-Note: The name Agentics is derived as a legacy from the first version of Agentics, in which data models and transformations were blended into the same object. By introducing transducible functions as first class citizens, Agentics 2.0 uses AGs primarily as a data structure, although it is still possible to use them directly for transformations. See agentics v1.0 documentation to learn more. 
+**Historical Note:** In Agentics 1.0, data models and transformations were blended into the same object. Agentics 2.0 separates concerns by introducing transducible functions as first-class citizens, while AG containers focus on data management. The v1.0 API is still supported for backward compatibility.
 
 
 ---
@@ -158,7 +164,7 @@ In short:
 
 Once you have:
 
-- Typed collections (`AG[Source]`), and  
+- Typed collections (`AG[Source]`) and  
 - Typed transformations (`Source -> Target`),
 
 you need a way to run these at scale. Agentics uses a familiar pattern: **Map–Reduce**.
@@ -248,8 +254,9 @@ A typical workflow looks like this:
 - **Logical Transduction Algebra (LTA)** explains why these transformations compose and remain interpretable.  
 - **Map–Reduce** provides the pattern for scaling these transductions to large datasets.
 
-From here, you can explore:
 
+## Next
 - 👉 [Transducible Functions](transducible_functions.md) for concrete examples of defining and using transducible functions
-- 👉 `types_and_states.md` for data modeling patterns  
-- 👉 `mapreduce.md` to see how large-scale execution works in practice  
+
+## Go to Index
+- 👉 [Index](index.md)