ebookfoundation / alt-text-backend Goto Github PK

View Code? Open in Web Editor NEW

1.0 1.0 0.0 84 KB

Python 100.00%

alt-text-backend's People

Contributors

Stargazers

Watchers

alt-text-backend's Issues

push or pull?

alt-text-backend/openapi.yaml

Line 114 in 7afe104

description: Zip file of the book.

you assume a "push" with a zip file. Why??? It's more efficient to send a URL and have the server pull in the file. This is because
the html is much smaller than most images, and you want to process images one by one. You don't need to get sound files, or css files or font files.

context rather description

alt-text-backend/openapi.yaml

Line 109 in 7afe104

description:

maybe what you want is context rather than 'description', as some contextual info might be useful to the model. genre maybe? emphasis on helping the ai, not on discovery!

"Books"

alt-text-backend/openapi.yaml

Line 20 in 7afe104

description: Everything regarding books

it's worth noting that these objects are html pages, not really "books". "document" would have been a better word.

API user stories

When building software applications, I have found that it is useful to have user stories to guide the application design to help me focus on the important functions of the application.

User stories for alt-text AI API

As a client system, I have a document with images. I would like to get suggested alt-text descriptions for each of the images.
As a client system, I have received alt-text descriptions from you for a document with images . I would like a way to improve your suggestions.

linking of images to documents

alt-text-backend/openapi.yaml

Lines 298 to 304 in 7afe104

 - name: srcQ 

 in: query 

 description: String to match the title to. 

 required: false 

 explode: true 

 schema: 

 type: string

this bit seems to imply that you're doing something other than using foreign keys to link images to books.

...and we're keeping the images around, too? Maybe leave them where they came from, or at least have that option using redirects?

alt-text-backend/openapi.yaml

Lines 331 to 347 in 7afe104

 /books/{bookid}/image: 

 parameters: 

 - name: bookid 

 in: path 

 description: Id of the book. 

 required: true 

 explode: true 

 schema: 

 type: string 

 example: "123e4567-e89b-12d3-a456-426614174000" 

 - name: src 

 in: query 

 description: Src of the image. 

 required: true 

 explode: true 

 schema: 

 type: string

sorting is expensive!

alt-text-backend/openapi.yaml

Line 46 in 7afe104

- name: sortBy

don't bother

what is a title?

alt-text-backend/openapi.yaml

Line 32 in 7afe104

- name: titleQ

where are you getting the title from? from a document, another metadat feed or from a PUT?

Why would we reanalyse?

alt-text-backend/openapi.yaml

Line 196 in 7afe104

 description: Re-analyze an entire book and overwrite current image data by its id. 

We might add to context data to improve the result, or we might want to see the results of a newer model. In that case, wouldn't I want to compare the results? I think you need to keep track of sessions.

string or binary

alt-text-backend/openapi.yaml

Line 177 in 7afe104

type: string

This is probably just my lack of understanding of the spec semantics but what does it mean that a field is binary AND a string?

Authors are too messy to deal with

alt-text-backend/openapi.yaml

Line 39 in 7afe104

- name: authorQ

authors can be lists, for example, pseudonyms, honorifics, etc.

just remove it

sorting is messy too

alt-text-backend/openapi.yaml

Line 55 in 7afe104

- name: sortOrder

most applications would rather have fast results

maybe separate image from a session

alt-text-backend/openapi.yaml

Lines 464 to 496 in 7afe104

 Image: 

 type: object 

 properties: 

 src: 

 type: string 

 example: "images/cover.png" 

 hash: 

 type: string 

 example: "" 

 size: 

 type: string 

 example: "24KB" 

 alt: 

 type: string 

 example: "" 

 originalAlt: 

 type: string 

 example: "" 

 genAlt: 

 type: string 

 example: "" 

 genImageCaption: 

 type: string 

 example: "" 

 ocr: 

 type: string 

 example: "" 

 beforeContext: 

 type: string 

 example: "" 

 afterContext: 

 type: string 

 example: ""

it seems to me you'll want the results of an analysis session separate from the image, espesially if you imagine re-running the model. you can store processing times (and dates) on the session object.

same question about title

alt-text-backend/openapi.yaml

Line 103 in 7afe104

title:

titles can come from the doumnet, from the PUT or from an API. Which takes precedence.

Titles can have multiple uses, display, (mostly for human users) context, for the AI, and retrieval.

Maybe add a field for a user-generated document identifier to facilitate retrieval.

where is get by submitter?

alt-text-backend/openapi.yaml

Line 28 in 7afe104

summary: Get a list of books.

also, seems to me I'd want a handle returned with each document I submit, and be able to review the result for multiple sessions

Are we keeping the book around?

alt-text-backend/openapi.yaml

Line 174 in 7afe104

type: string

you say I can overwrite a book. How is it identified? are you keeping it around. How many Terabytes will I need? (I've seen 100MB books!)

why a single book or document?

alt-text-backend/openapi.yaml

Line 95 in 7afe104

operationId: addBook

Why not a list of books?, with urls to pull from?

	- name: srcQ
	in: query
	description: String to match the title to.
	required: false
	explode: true
	schema:
	type: string
	- name: limit
	in: query
	description: Max number of images to return.
	required: false
	explode: true
	schema:
	type: integer
	- name: skip
	in: query
	description: Number of images to skip.
	required: false
	explode: true
	schema:
	type: integer
	default: 0

	/books/{bookid}/image:
	parameters:
	- name: bookid
	in: path
	description: Id of the book.
	required: true
	explode: true
	schema:
	type: string
	example: "123e4567-e89b-12d3-a456-426614174000"
	- name: src
	in: query
	description: Src of the image.
	required: true
	explode: true
	schema:
	type: string

	Image:
	type: object
	properties:
	src:
	type: string
	example: "images/cover.png"
	hash:
	type: string
	example: ""
	size:
	type: string
	example: "24KB"
	alt:
	type: string
	example: ""
	originalAlt:
	type: string
	example: ""
	genAlt:
	type: string
	example: ""
	genImageCaption:
	type: string
	example: ""
	ocr:
	type: string
	example: ""
	beforeContext:
	type: string
	example: ""
	afterContext:
	type: string
	example: ""

ebookfoundation / alt-text-backend Goto Github PK

alt-text-backend's People

Contributors

Stargazers

Watchers

alt-text-backend's Issues

Recommend Projects

Recommend Topics

Recommend Org

Jobs