Merge pull request #92 from CaliLuke/feat/typedb-3.8.0-support

Polymorphic role player type resolution and comprehensive query tests

Author: ds1sqe

docs/SKILL.md

@@ -138,6 +138,40 @@ class Company(Entity):
     name: Name = Flag(Key)
 ```
 
+### Role Cardinality
+
+For relations where the same role has multiple players of the same type:
+
+```python
+from type_bridge import Relation, Role, Card, TypeFlags
+
+# Exactly 2 Memory entities playing the same role
+class IsSimilarTo(Relation):
+    flags = TypeFlags(name="is_similar_to")
+    similar_memory: Role[Memory] = Role("similar_memory", Memory, Card(2, 2))
+
+# Generates: relation is_similar_to, relates similar_memory @card(2..2);
+```
+
+**Card variations for roles:**
+
+| Python       | TypeQL        | Meaning                             |
+| ------------ | ------------- | ----------------------------------- |
+| `Card(2, 2)` | `@card(2..2)` | Exactly 2 players                   |
+| `Card(1, 3)` | `@card(1..3)` | Between 1 and 3 players             |
+| `Card(2)`    | `@card(2..)`  | At least 2 players (no upper bound) |
+
+**Creating instances with multiple role players:**
+
+```python
+memory1 = Memory(content=Content("First memory"))
+memory2 = Memory(content=Content("Second memory"))
+
+# Pass a list for roles with multiple players
+similarity = IsSimilarTo(similar_memory=[memory1, memory2])
+manager.insert(similarity)
+```
+
 ---
 
 ## CRUD Operations
@@ -372,6 +406,41 @@ animal_manager = Animal.manager(db)
 all_animals = animal_manager.all()
 ```
 
+### Polymorphic Role Players
+
+When a relation role uses an abstract type, queried role players are resolved to their concrete types:
+
+```python
+# Abstract base
+class Profile(Entity):
+    flags = TypeFlags(name="profile", abstract=True)
+    profile_id: ProfileId = Flag(Key)
+
+# Concrete subtypes
+class Person(Profile):
+    flags = TypeFlags(name="person")
+    email: Email | None = None
+
+class Organization(Profile):
+    flags = TypeFlags(name="org")
+    website: Website | None = None
+
+# Relation with abstract role type
+class Authorship(Relation):
+    flags = TypeFlags(name="authorship")
+    author: Role[Profile] = Role("author", Profile)  # Abstract!
+    post: Role[Post] = Role("post", Post)
+
+# Query - role players resolved to concrete types
+authorships = Authorship.manager(db).all()
+for auth in authorships:
+    # author is Person or Organization, NOT abstract Profile
+    if isinstance(auth.author, Person):
+        print(f"Person: {auth.author.email}")
+    elif isinstance(auth.author, Organization):
+        print(f"Org: {auth.author.website}")
+```
+
 ### Serialization
 
 ```python

docs/api/crud.md

@@ -900,6 +900,31 @@ for employment in all_employments:
     print(f"{employment.employee.name}: {employment.position}")
 ```
 
+#### Polymorphic Role Player Resolution
+
+When a role accepts an abstract entity type, queried role players are automatically resolved to their **concrete types**:
+
+```python
+# Role accepts abstract type
+class Authorship(Relation):
+    author: Role[Profile] = Role("author", Profile)  # Profile is abstract
+    post: Role[Post] = Role("post", Post)
+
+# Person and Organization both extend Profile
+authorships = Authorship.manager(db).all()
+
+for auth in authorships:
+    # author is resolved to Person or Organization, NOT abstract Profile
+    # Use isinstance() for instance checks, issubclass() for class checks
+    assert issubclass(type(auth.author), Profile)  # Always true
+    if isinstance(auth.author, Person):
+        print(f"Person email: {auth.author.email}")  # Person-specific attr
+    elif isinstance(auth.author, Organization):
+        print(f"Org website: {auth.author.website}")  # Org-specific attr
+```
+
+This works in all query methods: `get()`, `all()`, `get_by_iid()`, and `filter().execute()`.
+
 #### Get Relations with Filters
 
 Filter by both attributes and role players:

docs/api/generator.md

@@ -6,7 +6,7 @@ Generate TypeBridge Python models from TypeDB schema files (`.tql`).
 
 The generator eliminates manual synchronization between TypeDB schemas and Python code. Instead of writing both `.tql` and Python classes, you write the schema once in TypeQL and generate type-safe Python models.
 
-```
+```text
 schema.tql  →  generator  →  attributes.py
                           →  entities.py
                           →  relations.py
@@ -47,7 +47,7 @@ generate_models(schema, "./myapp/models/")
 
 ## CLI Reference
 
-```
+```text
 Usage: python -m type_bridge.generator [OPTIONS] SCHEMA
 
 Arguments:
@@ -65,7 +65,7 @@ The `--output` directory is **required**. We recommend a dedicated directory lik
 
 ## Generated Package Structure
 
-```
+```text
 myapp/models/
 ├── __init__.py      # Package exports, SCHEMA_VERSION, schema_text()
 ├── attributes.py    # Attribute class definitions
@@ -97,26 +97,26 @@ print(schema_text())
 
 The generator supports the full TypeDB 3.0 schema syntax:
 
-| Feature | Status |
-|---------|--------|
-| Attributes with value types | ✓ |
-| `@abstract` types | ✓ |
-| `@independent` attributes | ✓ |
-| `sub` inheritance | ✓ |
-| `@regex` constraints | ✓ |
-| `@values` constraints | ✓ |
-| `@range` constraints | ✓ |
-| `@key` / `@unique` | ✓ |
-| `@card` on owns | ✓ |
-| `@card` on plays | ✓ |
-| `@card` on relates | ✓ |
-| `@cascade` on owns | ✓ |
-| `@subkey` on owns | ✓ |
-| `@distinct` on relates | ✓ |
-| Role overrides (`as`) | ✓ |
-| Functions (`fun`) | ✓ |
-| Structs (`struct`) | ✓ |
-| `#` and `//` comments | ✓ |
+| Feature                     | Status |
+| --------------------------- | ------ |
+| Attributes with value types | ✓      |
+| `@abstract` types           | ✓      |
+| `@independent` attributes   | ✓      |
+| `sub` inheritance           | ✓      |
+| `@regex` constraints        | ✓      |
+| `@values` constraints       | ✓      |
+| `@range` constraints        | ✓      |
+| `@key` / `@unique`          | ✓      |
+| `@card` on owns             | ✓      |
+| `@card` on plays            | ✓      |
+| `@card` on relates          | ✓      |
+| `@cascade` on owns          | ✓      |
+| `@subkey` on owns           | ✓      |
+| `@distinct` on relates      | ✓      |
+| Role overrides (`as`)       | ✓      |
+| Functions (`fun`)           | ✓      |
+| Structs (`struct`)          | ✓      |
+| `#` and `//` comments       | ✓      |
 
 ### Attributes
 
@@ -266,6 +266,16 @@ class Employment(Relation):
     employer: Role[entities.Company] = Role("employer", entities.Company)
     employee: Role[entities.Person] = Role("employee", entities.Person)
 
+class Friendship(SocialRelation):
+    flags = TypeFlags(name="friendship")
+    # Symmetric role - multiple friends allowed per friendship
+    friend: Role[entities.Person] = Role("friend", entities.Person, cardinality=Card(0, 1000))
+
+class Parentship(Relation):
+    flags = TypeFlags(name="parentship")
+    parent: Role[entities.Person] = Role("parent", entities.Person, cardinality=Card(1, 2))
+    child: Role[entities.Person] = Role("child", entities.Person, cardinality=Card(1))
+
 class Contribution(Relation):
     flags = TypeFlags(name="contribution", abstract=True)
     contributor: Role[entities.Contributor] = Role("contributor", entities.Contributor)
@@ -377,15 +387,15 @@ relation friendship,
 
 The following cardinality rules apply to attributes on both **entities** and **relations**:
 
-| TypeQL | Python Type | Default |
-|--------|-------------|---------|
-| `@card(1)` or `@card(1..1)` | `Type` | Required |
-| `@card(0..1)` or no annotation | `Type \| None = None` | Optional |
-| `@card(0..)` | `list[Type] = Flag(Card(min=0))` | Optional list |
-| `@card(1..)` | `list[Type] = Flag(Card(min=1))` | Required list |
-| `@card(2..5)` | `list[Type] = Flag(Card(2, 5))` | Bounded list |
-| `@key` | `Type = Flag(Key)` | Key (implies required) |
-| `@unique` | `Type = Flag(Unique)` | Unique (implies required) |
+| TypeQL                         | Python Type                      | Default                   |
+| ------------------------------ | -------------------------------- | ------------------------- |
+| `@card(1)` or `@card(1..1)`    | `Type`                           | Required                  |
+| `@card(0..1)` or no annotation | `Type \| None = None`            | Optional                  |
+| `@card(0..)`                   | `list[Type] = Flag(Card(min=0))` | Optional list             |
+| `@card(1..)`                   | `list[Type] = Flag(Card(min=1))` | Required list             |
+| `@card(2..5)`                  | `list[Type] = Flag(Card(2, 5))`  | Bounded list              |
+| `@key`                         | `Type = Flag(Key)`               | Key (implies required)    |
+| `@unique`                      | `Type = Flag(Unique)`            | Unique (implies required) |
 
 **Inheritance:** Child types inherit cardinality constraints from parent types. A child can override inherited constraints by redeclaring the attribute with a different `@card`.
 
@@ -420,14 +430,14 @@ entity user,
     owns username @key;
 ```
 
-| Annotation | Effect |
-|------------|--------|
-| `# @prefix(XXX)` | Adds `prefix: ClassVar[str] = "XXX"` |
-| `# @internal` | Sets `internal = True` on the spec |
-| `# @case(SNAKE_CASE)` | Uses specified case for type name |
-| `# @transform(xxx)` | Adds `transform = "xxx"` attribute |
-| `# @tags(a, b, c)` | Adds list annotation |
-| `# Any other comment` | Becomes the class docstring |
+| Annotation            | Effect                               |
+| --------------------- | ------------------------------------ |
+| `# @prefix(XXX)`      | Adds `prefix: ClassVar[str] = "XXX"` |
+| `# @internal`         | Sets `internal = True` on the spec   |
+| `# @case(SNAKE_CASE)` | Uses specified case for type name    |
+| `# @transform(xxx)`   | Adds `transform = "xxx"` attribute   |
+| `# @tags(a, b, c)`    | Adds list annotation                 |
+| `# Any other comment` | Becomes the class docstring          |
 
 ## Functions
 
@@ -479,14 +489,14 @@ fun karma_sum_and_squares() -> double, double:
 
 ### Function Return Types
 
-| TypeQL | Parsed `return_type` |
-|--------|---------------------|
-| `-> { type }` | `"{ type }"` |
-| `-> { t1, t2 }` | `"{ t1, t2 }"` |
-| `-> type` | `"type"` |
-| `-> t1, t2` | `"t1, t2"` |
-| `-> t1, t2?` | `"t1, t2?"` |
-| `-> bool` | `"bool"` |
+| TypeQL          | Parsed `return_type` |
+| --------------- | -------------------- |
+| `-> { type }`   | `"{ type }"`         |
+| `-> { t1, t2 }` | `"{ t1, t2 }"`       |
+| `-> type`       | `"type"`             |
+| `-> t1, t2`     | `"t1, t2"`           |
+| `-> t1, t2?`    | `"t1, t2?"`          |
+| `-> bool`       | `"bool"`             |
 
 ## API Reference
 
@@ -582,7 +592,7 @@ class ParameterSpec:
 
 ### 1. Keep Generated Code Separate
 
-```
+```text
 myapp/
 ├── models/          # Generated (don't edit!)
 │   ├── __init__.py

docs/api/relations.md

@@ -103,6 +103,7 @@ class Employment(Relation):
 ```
 
 **Components**:
+
 - `field_name`: Python field name (e.g., `employee`, `employer`)
 - `Role[EntityType]`: Type hint for role player type
 - `Role("role_name", EntityType)`: Role definition with TypeDB role name and player type
@@ -173,10 +174,12 @@ results = manager.filter(
 ### Available Methods
 
 **Numeric fields**:
+
 - `.gt(value)`, `.lt(value)`, `.gte(value)`, `.lte(value)`
 - `.eq(value)`, `.neq(value)`
 
 **String fields**:
+
 - `.contains(value)` - Substring match
 - `.like(value)` - Regex pattern
 - `.regex(value)` - Regex pattern (alias)
@@ -242,6 +245,7 @@ email plays trace:origin;
 ```
 
 ### CRUD and queries
+
 - Filtering or deleting by a multi-player role uses the actual player’s key attributes and works across all allowed entity types.
 - Role uniqueness rules still apply: keep role names distinct (TypeDB requirement).
 
@@ -277,6 +281,7 @@ class Employment(Relation):
 ```
 
 **When explicit flags ARE needed:**
+
 - `abstract=True` - Abstract relations
 - `base=True` - Python-only base classes
 - Custom `name` - Override type name
@@ -641,6 +646,43 @@ person plays authorship:author;
 content plays authorship:content;  # Abstract type in role player definition
 ```
 
+### Polymorphic Role Player Type Resolution
+
+When querying relations with polymorphic role players, TypeBridge resolves each role player to its **concrete type**, not the abstract declared type. This enables type-safe access to subtype-specific attributes:
+
+```python
+# Query authorships - role players are resolved to concrete types
+authorships = Authorship.manager(db).all()
+
+for authorship in authorships:
+    content = authorship.content
+
+    # content is Article, Video, or other concrete subtype - NOT abstract Content
+    if isinstance(content, Article):
+        print(f"Article body: {content.body}")
+    elif isinstance(content, Video):
+        print(f"Video URL: {content.url}")
+
+    # Common attributes from abstract type are always accessible
+    print(f"Title: {content.title}")
+```
+
+**How it works**:
+
+TypeBridge uses TypeDB's `label()` built-in function to fetch the actual type of each role player, then resolves it to the correct Python class. This happens automatically in:
+
+- `RelationManager.get()` - filter-based queries
+- `RelationManager.all()` - fetch all relations
+- `RelationManager.get_by_iid()` - IID-based lookup
+- `RelationQuery.execute()` - chainable query execution
+
+**Benefits**:
+
+- Access concrete type-specific attributes directly
+- Use `isinstance()` for type-safe branching
+- Proper Python type inference in IDEs
+- No need to manually resolve types from IIDs
+
 ## Best Practices
 
 ### 1. Use Descriptive Role Names

pyproject.toml

@@ -90,7 +90,7 @@ ignore = [
 [tool.ruff.lint.per-file-ignores]
 "examples/*.py" = ["F841", "E402"]
   # Allow unused variables, Function level import in examples for demonstration
-"tests/*.py" = ["F841"]  # Allow unused variables in tests
+"tests/*.py" = ["F841", "N806"]  # Allow unused variables and PascalCase class types in tests
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]