Database Models

Our RDBMS layer is very interesting: obviously it incorporates all of the traditional elements - all SQLAlchemy, but in order to be resiliant, we’ve a lot of JSON fields. These all have Pydantic models associated with them, so everything is deeply Pythonic.

class lbn.aidoc.models.Application(*, cv: Any = <factory>, letter: Any = <factory>, url: HttpUrl | None = None, **data: Any)

Bases: BaseModel

Structured JSON layout for a complete job application document set.

class CVProfile(*, sections: List[str] = <factory>, title: str = '', keywords: List[str] = <factory>, subject: str | None = None, required: List[str] = <factory>, **extra_data: Any)

Bases: BaseModel

keywords: List[str]

model_config = {'arbitrary_types_allowed': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

required: List[str]

sections: List[str]

subject: str | None

title: str

class LetterProfile(*, title: str = '', sections: List[str] = <factory>, freetext: str = '', marketplace: List[str] = <factory>, required: List[str] = <factory>, **extra_data: Any)

Bases: BaseModel

freetext: str

marketplace: List[str]

model_config = {'arbitrary_types_allowed': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

required: List[str]

sections: List[str]

title: str

cv: Any

letter: Any

model_config = {'arbitrary_types_allowed': True, 'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

url: HttpUrl | None

class lbn.aidoc.models.Archetype(*values)

Bases: StyledEnum

BOSS = 'boss'

OTHER = 'other'

PEER = 'peer'

RECRUITER = 'recruiter'

SCHEDULER = 'scheduler'

SCOUT = 'scout'

SOURCE = 'source'

class lbn.aidoc.models.Comment(*, id: ~typing.Annotated[int | None, ~sqlmodel.main.FieldInfoMetadata(primary_key=True, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=PydanticUndefined, index=PydanticUndefined, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)] = None, parent_type: ~typing.Annotated[str, ~sqlmodel.main.FieldInfoMetadata(primary_key=PydanticUndefined, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=PydanticUndefined, index=True, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)], parent_id: ~typing.Annotated[int, ~sqlmodel.main.FieldInfoMetadata(primary_key=PydanticUndefined, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=PydanticUndefined, index=True, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)], category: ~typing.Annotated[str, ~sqlmodel.main.FieldInfoMetadata(primary_key=PydanticUndefined, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=PydanticUndefined, index=PydanticUndefined, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)] = 'note', content: str, timestamp: ~typing.Annotated[~datetime.datetime, ~sqlmodel.main.FieldInfoMetadata(primary_key=PydanticUndefined, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=PydanticUndefined, index=PydanticUndefined, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)] = <factory>)

Bases: SQLModel

as_str()

category: str

content: str

id: int | None

model_config = {'from_attributes': True, 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property parent

Automatically extracts the database session from itself to find the parent model.

property parent_class

parent_id: int

parent_type: str

timestamp: datetime

class lbn.aidoc.models.Company(*, id: Annotated[int | None, FieldInfoMetadata(primary_key=True, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=PydanticUndefined, index=PydanticUndefined, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)] = None, name: Annotated[str, FieldInfoMetadata(primary_key=PydanticUndefined, nullable=False, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=True, index=True, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)], is_agency: Annotated[bool, FieldInfoMetadata(primary_key=PydanticUndefined, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=PydanticUndefined, index=PydanticUndefined, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)] = False, website: str | None = None)

Bases: SQLModel

as_str()

property employees: List[Person]

The genuine internal team: Bosses, Peers, Talent, etc.

id: int | None

is_agency: bool

jobs: Mapped[List[Job]]

model_config = {'from_attributes': True, 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

property recruiters: List[Person]

The external agency partners linked to this company.

stints: Mapped[List[EmploymentHistory]]

website: str | None

class lbn.aidoc.models.CompanyAlias(*, name: Annotated[str, FieldInfoMetadata(primary_key=True, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=PydanticUndefined, index=PydanticUndefined, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)], company_id: Annotated[int, FieldInfoMetadata(primary_key=PydanticUndefined, nullable=PydanticUndefined, foreign_key=company.id, ondelete=PydanticUndefined, unique=PydanticUndefined, index=PydanticUndefined, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)])

Bases: SQLModel

company_id: int

model_config = {'from_attributes': True, 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

class lbn.aidoc.models.EmploymentHistory

Bases: SQLModel

The Ledger: Tracks who works (or worked) where.

archetype: Archetype

company: Mapped[Company]

company_id: int

end_date: datetime | None

id: int | None

model_config = {'from_attributes': True, 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

person: Mapped[Person]

person_id: int

start_date: datetime | None

classmethod validate_styled_enums(v, info)

The ‘Inhale Handshake’: Forces Pydantic to use the StyledEnum constructor. This re-attaches the .style metadata lost during AI extraction.

class lbn.aidoc.models.History

Bases: SQLModel

for state machine transition histories

id: int | None

model_config = {'from_attributes': True, 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

new_status: str | None

note: str

old_status: str | None

parent_id: int

parent_type: str

timestamp: datetime

class lbn.aidoc.models.Interview

Bases: SQLModel

as_ical() → str

Surgical Export: Generates a valid iCalendar byte string using the icalendar library.

as_str()

attendee_ids: List[int]

property attendees: List[Person]

Surgical Lookahead: Direct session query to resolve the JSON list of IDs. Returns a list of Person objects matching the internal array registry.

history: Mapped[List[History]]

id: int | None

job: Mapped[Job | None]

job_id: int | None

location: str

model_config = {'from_attributes': True, 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

predecessor: Mapped[Interview | None]

predecessor_id: int | None

predecessors() → List[Interview]

Walks backwards up the chain of predecessor links. Returns a list of all prior interview objects, sorted chronologically.

scheduled_at: datetime

state: MeetingStatus

title: str

classmethod validate_styled_enums(v, info)

The ‘Inhale Handshake’: Forces Pydantic to use the StyledEnum constructor. This re-attaches the .style metadata lost during AI extraction.

class lbn.aidoc.models.Job

Bases: SQLModel

analytics: Any

annual_equivalent

applicants: int | None

application: Any

as_str()

closes: datetime | None

company: Mapped[Company | None]

company_id: int | None

description: str | None

expired_at: datetime | None

external_id: str | None

geo: str | None

history: Mapped[List[History]]

id: int | None

ingested

SQL-side expression: Generates a correlated scalar subquery. Locates the absolute oldest History timestamp for this Job.

interviews: Mapped[List[Interview]]

job_style: JobStyle

job_type: JobType

keywords: List[str]

listed: datetime | None

location: str | None

model_config = {'from_attributes': True, 'ignored_types': (<class 'sqlalchemy.ext.hybrid.hybrid_property'>,), 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

priority: Priority

recruiter: Mapped[Person | None]

recruiter_id: int | None

salary_currency: str

salary_max: int | None

salary_min: int | None

salary_period: SalaryPeriod

score: float | None

source: Mapped[Source | None]

source_id: int | None

state: JobStatus

title: str

url: str | None

classmethod validate_styled_enums(v, info)

The ‘Inhale Handshake’: Forces Pydantic to use the StyledEnum constructor. This re-attaches the .style metadata lost during AI extraction.

version: int

class lbn.aidoc.models.JobStatus(*values)

Bases: StyledEnum

APPLIED = 'applied'

ARCHIVED = 'archived'

DISMISSED = 'dismissed'

HIRED = 'hired'

INTERVIEW = 'interview'

OFFER = 'offer'

QUALIFIED = 'qualified'

RAW = 'raw'

REJECTED = 'rejected'

SCREENING = 'screening'

class lbn.aidoc.models.JobStyle(*values)

Bases: StyledEnum

HYBRID = 'hybrid'

ONSITE = 'on-site'

REMOTE = 'remote'

class lbn.aidoc.models.JobType(*values)

Bases: StyledEnum

CONTRACT = 'contract'

FIXED = 'fixed-term'

PERM = 'permanent'

TEMPORARY = 'temporary'

class lbn.aidoc.models.MeetingStatus(*values)

Bases: StyledEnum

CANCELLED = 'cancelled'

COMPLETED = 'completed'

PROPOSED = 'proposed'

RESCHEDULING = 'rescheduling'

SCHEDULED = 'scheduled'

class lbn.aidoc.models.ModelFlattener(model: Any, relationships: List[str] = None, mappings: Dict[str, str] = None, extras: Dict[str, Any] = None, excludes: List[str] = None)

Bases: object

The ‘Surgical’ Proxy: Collapses FK relationships into a flat namespace. Strips internal IDs and resolves built-in collisions (like ‘id’).

property model_fields: Dict[str, Any]

Spoofing for DisplayWidget’s attribute discovery logic.

class lbn.aidoc.models.MutablePydantic

Bases: Mutable

Framework-Native Mutation Tracker: Enables SQLAlchemy to accept rich Pydantic objects directly onto the column field without type crashes.

changed()

Subclasses should call this method whenever change events occur.

classmethod coerce(key, value)

Given a value, coerce it into the target type.

Can be overridden by custom subclasses to coerce incoming data into a particular type.

By default, raises ValueError.

This method is called in different scenarios depending on if the parent class is of type Mutable or of type MutableComposite. In the case of the former, it is called for both attribute-set operations as well as during ORM loading operations. For the latter, it is only called during attribute-set operations; the mechanics of the composite() construct handle coercion during load operations.

Parameters:

• key – string name of the ORM-mapped attribute being set.

• value – the incoming value.

Returns:

the method should return the coerced value, or raise ValueError if the coercion cannot be completed.

class lbn.aidoc.models.Person(*, id: Annotated[int | None, FieldInfoMetadata(primary_key=True, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=PydanticUndefined, index=PydanticUndefined, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)] = None, name: Annotated[str, FieldInfoMetadata(primary_key=PydanticUndefined, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=PydanticUndefined, index=True, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)], email: Annotated[str | None, FieldInfoMetadata(primary_key=PydanticUndefined, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=True, index=True, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)] = None, phone: str | None = None, linkedin: str | None = None, website: str | None = None, location: str | None = None, geo: str | None = None, jobtitle: str | None = None)

Bases: SQLModel

The Master Address Book: Purely digital presence. Independence: No relationships or back-links defined here.

as_str()

email: str | None

first_name()

geo: str | None

id: int | None

jobtitle: str | None

last_name()

linkedin: str | None

location: str | None

model_config = {'from_attributes': True, 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

phone: str | None

stints: Mapped[List[EmploymentHistory]]

website: str | None

class lbn.aidoc.models.PersonAlias(*, name: Annotated[str, FieldInfoMetadata(primary_key=True, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=PydanticUndefined, index=PydanticUndefined, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)], person_id: Annotated[int, FieldInfoMetadata(primary_key=PydanticUndefined, nullable=PydanticUndefined, foreign_key=person.id, ondelete=PydanticUndefined, unique=PydanticUndefined, index=PydanticUndefined, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)])

Bases: SQLModel

model_config = {'from_attributes': True, 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

person_id: int

class lbn.aidoc.models.Priority(*values)

Bases: StyledEnum

HIGH = 'high'

LOW = 'low'

MEDIUM = 'medium'

NONE = 'none'

UNKNOWN = 'unknown'

URGENT = 'urgent'

class lbn.aidoc.models.Prompt

Bases: SQLModel

an LLM instruction, with well defined inputs and outputs

compile(**kwargs) → List[Dict[str, str]]

The ‘Inhale’: Uses the input_model to resolve defaults and satisfy ‘required’ constraints before the slurp.

id: int | None

input_model() → Type[BaseModel]

The ‘Inhale Contractor’: Dynamic validation block for input parameters. Recursively compiles a genuine Pydantic model contract straight from the stored input_schema JSON dictionary.

input_schema: Dict[str, Any]

inputs() → Dict[str, List[str]]

Decomposes the input JSONSchema.

link(data: Any) → Any

The ‘Linker’: turns dicts, etc into our pydantic output schema structure

model_config = {'from_attributes': True, 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

output_model() → Type[BaseModel]

The ‘Inhale Contractor’: High-fidelity type mapping. Recursively compiles a genuine, deeply nested Pydantic model contract straight from the stored output_schema JSON dictionary.

output_schema: Dict[str, Any]

outputs() → Dict[str, List[str]]

Decomposes the output JSONSchema.

provider: str | None

rst_files: Mapped[List[RSTFile]]

system_message: str

temperature: float

ttl: int

validate_schema_integrity() → Prompt

Ensure every required field has a matching property definition.

weight: Weight

class lbn.aidoc.models.PydanticJSON(pydantic_model_resolver: Any, *args: Any, **kwargs: Any)

Bases: TypeDecorator

The Decoupled Database Bridge: Serializes Pydantic models to disk without requiring tight compile-time import couplings to intelligence.py.

cache_ok = True

Indicate if statements using this ExternalType are “safe to cache”.

The default value None will emit a warning and then not allow caching of a statement which includes this type. Set to False to disable statements using this type from being cached at all without a warning. When set to True, the object’s class and selected elements from its state will be used as part of the cache key. For example, using a TypeDecorator:

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

The cache key for the above type would be equivalent to:

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

The caching scheme will extract attributes from the type that correspond to the names of parameters in the __init__() method. Above, the “choices” attribute becomes part of the cache key but “internal_only” does not, because there is no parameter named “internal_only”.

The requirements for cacheable elements is that they are hashable and also that they indicate the same SQL rendered for expressions using this type every time for a given cache value.

To accommodate for datatypes that refer to unhashable structures such as dictionaries, sets and lists, these objects can be made “cacheable” by assigning hashable structures to the attributes whose names correspond with the names of the arguments. For example, a datatype which accepts a dictionary of lookup values may publish this as a sorted series of tuples. Given a previously un-cacheable type as:

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

Where “lookup” is a dictionary. The type will not be able to generate a cache key:

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

If we did set up such a cache key, it wouldn’t be usable. We would get a tuple structure that contains a dictionary inside of it, which cannot itself be used as a key in a “cache dictionary” such as SQLAlchemy’s statement cache, since Python dictionaries aren’t hashable:

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

The type may be made cacheable by assigning a sorted tuple of tuples to the “.lookup” attribute:

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

Where above, the cache key for LookupType({"a": 10, "b": 20}) will be:

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

Added in version 1.4.14: - added the cache_ok flag to allow some configurability of caching for TypeDecorator classes.

Added in version 1.4.28: - added the ExternalType mixin which generalizes the cache_ok flag to both the TypeDecorator and UserDefinedType classes.

See also

sql_caching

impl

alias of JSON

process_bind_param(value: Any, dialect: Any) → Any

Before writing to disk: Flatten the object down to a plain JSON map.

process_result_value(value: Any, dialect: Any) → Any

After reading off disk: Re-hydrate straight back into the targeted model contract.

property target_model: type

Lazily resolve the class type only when a database read triggers.

class lbn.aidoc.models.RSTFile

Bases: SQLModel

epigraph: str | None

epilog: str | None

id: int | None

is_active: bool

last_prompt_id: int | None

model_config = {'from_attributes': True, 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

prolog: str | None

prompt: Mapped[Prompt | None]

raw_content: str | None

seealso: str | None

target_path: str

class lbn.aidoc.models.SalaryPeriod(*values)

Bases: StyledEnum

ANNUAL = 'annual'

DAILY = 'daily'

HOURLY = 'hourly'

class lbn.aidoc.models.Source

Bases: SQLModel

domain: str

driver: str

extras: Dict[str, Any]

classmethod get_by_url(session: Session, url: str) → Source

The Discovery Drill: Resolves Source by domain or falls back to ‘General’. PRINCIPAL: Guaranteed to return a Source object.

id: int | None

jobs: Mapped[List[Job]]

model_config = {'from_attributes': True, 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

password: str | None

searches: Dict[str, Any]

url: str | None

username: str | None

class lbn.aidoc.models.StyledEnum(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Surgical Hybrid: Identity is clean string, Style is metadata.

class lbn.aidoc.models.StyledType(enum_class, *args, **kwargs)

Bases: TypeDecorator

The Bridge: Handles DB round-trips for any StyledEnum.

cache_ok = True

Indicate if statements using this ExternalType are “safe to cache”.

The default value None will emit a warning and then not allow caching of a statement which includes this type. Set to False to disable statements using this type from being cached at all without a warning. When set to True, the object’s class and selected elements from its state will be used as part of the cache key. For example, using a TypeDecorator:

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

The cache key for the above type would be equivalent to:

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

The caching scheme will extract attributes from the type that correspond to the names of parameters in the __init__() method. Above, the “choices” attribute becomes part of the cache key but “internal_only” does not, because there is no parameter named “internal_only”.

The requirements for cacheable elements is that they are hashable and also that they indicate the same SQL rendered for expressions using this type every time for a given cache value.

To accommodate for datatypes that refer to unhashable structures such as dictionaries, sets and lists, these objects can be made “cacheable” by assigning hashable structures to the attributes whose names correspond with the names of the arguments. For example, a datatype which accepts a dictionary of lookup values may publish this as a sorted series of tuples. Given a previously un-cacheable type as:

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

Where “lookup” is a dictionary. The type will not be able to generate a cache key:

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

If we did set up such a cache key, it wouldn’t be usable. We would get a tuple structure that contains a dictionary inside of it, which cannot itself be used as a key in a “cache dictionary” such as SQLAlchemy’s statement cache, since Python dictionaries aren’t hashable:

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

The type may be made cacheable by assigning a sorted tuple of tuples to the “.lookup” attribute:

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

Where above, the cache key for LookupType({"a": 10, "b": 20}) will be:

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

Added in version 1.4.14: - added the cache_ok flag to allow some configurability of caching for TypeDecorator classes.

Added in version 1.4.28: - added the ExternalType mixin which generalizes the cache_ok flag to both the TypeDecorator and UserDefinedType classes.

See also

sql_caching

impl

alias of String

process_bind_param(value, dialect)

Receive a bound parameter value to be converted.

Custom subclasses of _types.TypeDecorator should override this method to provide custom behaviors for incoming data values. This method is called at statement execution time and is passed the literal Python data value which is to be associated with a bound parameter in the statement.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

Parameters:

• value – Data to operate upon, of any type expected by this method in the subclass. Can be None.

• dialect – the Dialect in use.

See also

types_typedecorator

_types.TypeDecorator.process_result_value()

process_result_value(value, dialect)

Receive a result-row column value to be converted.

Custom subclasses of _types.TypeDecorator should override this method to provide custom behaviors for data values being received in result rows coming from the database. This method is called at result fetching time and is passed the literal Python data value that’s extracted from a database result row.

The operation could be anything desired to perform custom behavior, such as transforming or deserializing data.

Parameters:

• value – Data to operate upon, of any type expected by this method in the subclass. Can be None.

• dialect – the Dialect in use.

See also

types_typedecorator

_types.TypeDecorator.process_bind_param()

class lbn.aidoc.models.Tag(*, id: Annotated[int | None, FieldInfoMetadata(primary_key=True, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=PydanticUndefined, index=PydanticUndefined, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)] = None, name: Annotated[str, FieldInfoMetadata(primary_key=PydanticUndefined, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=True, index=True, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)], style: Annotated[str, FieldInfoMetadata(primary_key=PydanticUndefined, nullable=PydanticUndefined, foreign_key=PydanticUndefined, ondelete=PydanticUndefined, unique=PydanticUndefined, index=PydanticUndefined, sa_type=PydanticUndefined, sa_column=PydanticUndefined, sa_column_args=PydanticUndefined, sa_column_kwargs=PydanticUndefined)] = 'white')

Bases: SQLModel

Surgical Metadata: Dynamic labels with built-in style.

id: int | None

model_config = {'from_attributes': True, 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

style: str

class lbn.aidoc.models.TagLink

Bases: SQLModel

The Glue: Polymorphic Many-to-Many link with a standard ID.

id: int | None

model_config = {'from_attributes': True, 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parent_id: int

parent_type: str

tag_id: int

class lbn.aidoc.models.Task

Bases: SQLModel

TODO/Task List

as_todoist_payload() → dict

Surgical Export: Generates a clean Todoist payload schema mapping. Translates our StyledEnum priorities into Todoist’s 1-4 numeric envelope.

blocked_by_id: int | None

blocker_reason: str | None

created_at: datetime

description: str | None

due_date: datetime | None

history: Mapped[List[History]]

id: int | None

is_blocked

Dynamically computes blocker state, eliminating out-of-sync column updates.

model_config = {'from_attributes': True, 'ignored_types': (<class 'sqlalchemy.ext.hybrid.hybrid_property'>,), 'read_from_attributes': True, 'read_with_orm_mode': True, 'registry': PydanticUndefined, 'table': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parent_id: int

parent_type: str

priority: Priority

state: TaskStatus

title: str

updated_at: datetime

classmethod validate_styled_enums(v, info)

The ‘Inhale Handshake’: Forces Pydantic to use the StyledEnum constructor. This re-attaches the .style metadata lost during database serialization.

class lbn.aidoc.models.TaskStatus(*values)

Bases: StyledEnum

ACTIVE = 'active'

BLOCKED = 'blocked'

DONE = 'done'

IGNORED = 'ignored'

NEW = 'new'

class lbn.aidoc.models.Weight(*values)

Bases: StyledEnum

HEAVYWEIGHT = 'heavyweight'

LIGHTWEIGHT = 'lightweight'

MIDDLEWEIGHT = 'middleweight'

lbn.aidoc.models.find_company(session: Session, search_name: str)

lbn.aidoc.models.find_person(session: Session, name: str = None, email: str = None)

The ‘Identity Drill’: Resolves Person via name/email or Name Alias. Surgically strikes only existing hardware columns. No redundant imports.

lbn.aidoc.models.get_comments_for(session, item)

Retrieves all narrative notes for the parent item.

lbn.aidoc.models.get_tags_for(session, item) → List[Tag]

Surgical Retrieval: Reaches into the TagLink silo for any arbitrary model.

lbn.aidoc.models.lazy_load_analytics()

lbn.aidoc.models.make_comment(item, content, category='note', timestamp=None)

Surgically injects a narrative comment against any hunting stakeholder model. Forces lowercase parent types to match get_comments_for extraction queries.