flybase 0.1.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
flybase-0.1.4/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Gustavo Madeira Santana
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
flybase-0.1.4/PKG-INFO ADDED
@@ -0,0 +1,284 @@
1
+ Metadata-Version: 2.4
2
+ Name: flybase
3
+ Version: 0.1.4
4
+ Summary: FlyBase sync/query helper for agents.
5
+ License-Expression: MIT
6
+ Requires-Python: >=3.11
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Dynamic: license-file
10
+
11
+ # FlyBase local sync/query
12
+
13
+ Use FlyBase bulk files for agent workloads. Live API: helper only.
14
+
15
+ ## Why
16
+
17
+ - `https://api.flybase.org/api/v1.0/` exists.
18
+ - some endpoints return useful JSON now, eg `domain/FBgn0001250`, `sequence/id/FBgn0001250`.
19
+ - some plausible endpoints return empty body today.
20
+ - bulk bucket + release files: better for repeatable agent queries.
21
+
22
+ ## Current surfaces checked
23
+
24
+ - release bucket: `https://s3ftp.flybase.org/releases/current/`
25
+ - precomputed files: `https://s3ftp.flybase.org/releases/current/precomputed_files/`
26
+ - Postgres dump: `https://s3ftp.flybase.org/releases/current/psql/FB2026_01.sql.gz`
27
+ - API root: `https://api.flybase.org/api/v1.0/`
28
+ - batch download: `https://flybase.org/batchdownload`
29
+
30
+ ## Layout
31
+
32
+ - `src/flybase_cli/`: package code
33
+ - `tests/`: stdlib `unittest`
34
+ - `flybase_cli.py`: thin repo-root shim
35
+ - `pyproject.toml`: package metadata / console entrypoint
36
+
37
+ ## Install
38
+
39
+ PyPI with `pipx`:
40
+
41
+ ```bash
42
+ pipx install flybase
43
+ ```
44
+
45
+ PyPI with plain `pip`:
46
+
47
+ ```bash
48
+ python3 -m pip install flybase
49
+ ```
50
+
51
+ Homebrew:
52
+
53
+ ```bash
54
+ brew tap gumadeiras/tap
55
+ brew install flybase
56
+ ```
57
+
58
+ From source:
59
+
60
+ ```bash
61
+ python3 -m pip install -e .
62
+ ```
63
+
64
+ ## Release
65
+
66
+ Current release: `v0.1.2`.
67
+
68
+ Tag pushes like `vX.Y.Z` run the release workflow: build artifacts, create a
69
+ GitHub release, publish to PyPI, and update `gumadeiras/homebrew-tap`.
70
+
71
+ Release prerequisites:
72
+
73
+ - PyPI trusted publishing configured for this repo.
74
+ - `HOMEBREW_TAP_TOKEN` repository secret can write to
75
+ `gumadeiras/homebrew-tap`.
76
+
77
+ ## CLI
78
+
79
+ ```bash
80
+ python3 flybase_cli.py presets
81
+
82
+ python3 flybase_cli.py sync gene-core
83
+
84
+ python3 flybase_cli.py sync gene-core --release FB2026_01
85
+
86
+ python3 flybase_cli.py sync gene-knowledge --release FB2026_01
87
+
88
+ python3 flybase_cli.py full-sync --release FB2026_01
89
+
90
+ python3 flybase_cli.py full-sync \
91
+ --release FB2026_01 \
92
+ --include 'best_gene_summary|entity_publication'
93
+
94
+ python3 flybase_cli.py sync-incremental \
95
+ gene-knowledge \
96
+ --from-release FB2025_06 \
97
+ --release FB2026_01
98
+
99
+ python3 flybase_cli.py release-diff \
100
+ --preset gene-knowledge \
101
+ --from-release FB2025_06 \
102
+ --to-release FB2026_01
103
+
104
+ python3 flybase_cli.py genomes --release FB2026_01
105
+
106
+ python3 flybase_cli.py sync-genome \
107
+ --release FB2026_01 \
108
+ --genome dmel_r6.67 \
109
+ --section fasta \
110
+ --asset mirna
111
+
112
+ python3 flybase_cli.py genome-presets
113
+
114
+ python3 flybase_cli.py sync-genome \
115
+ --release FB2026_01 \
116
+ --genome dmel_r6.67 \
117
+ --preset mirna-fasta
118
+
119
+ PYTHONPATH=src python3 -m flybase_cli sync gene-expression
120
+
121
+ python3 flybase_cli.py manifest \
122
+ --url https://s3ftp.flybase.org/genomes/Drosophila_melanogaster/dmel_r6.67_FB2026_01/fasta/ \
123
+ --include 'miRNA'
124
+
125
+ python3 flybase_cli.py sync-url \
126
+ --url https://s3ftp.flybase.org/genomes/Drosophila_melanogaster/dmel_r6.67_FB2026_01/fasta/ \
127
+ --include 'miRNA'
128
+
129
+ python3 flybase_cli.py ingest \
130
+ data/flybase/precomputed_files/genes/best_gene_summary_fb_2026_01.tsv.gz \
131
+ data/flybase/precomputed_files/genes/fbgn_fbtr_fbpp_fb_2026_01.tsv.gz \
132
+ data/flybase/precomputed_files/genes/fbgn_annotation_ID_fb_2026_01.tsv.gz
133
+
134
+ python3 flybase_cli.py tables --columns
135
+
136
+ python3 flybase_cli.py describe --sample-values 2
137
+ python3 flybase_cli.py schema-export --sample-values 1
138
+ python3 flybase_cli.py query-plan --sample-values 1 --limit 5
139
+ python3 flybase_cli.py query-run --template-name gene-summary-by-fbgn --param fbgn_id=FBgn0002121
140
+
141
+ python3 flybase_cli.py fts-build
142
+
143
+ python3 flybase_cli.py search 'memory formation'
144
+
145
+ python3 flybase_cli.py pg-load --release FB2026_01
146
+
147
+ python3 flybase_cli.py sql \
148
+ "select * from fb_best_gene_summary_fb_2026_01 limit 5"
149
+
150
+ python3 flybase_cli.py sql \
151
+ "select s.fbgn_id, s.gene_symbol, a.annotation_id, p.flybase_fbtr, p.flybase_fbpp \
152
+ from fb_best_gene_summary_fb_2026_01 s \
153
+ join fb_fbgn_annotation_id_fb_2026_01 a on a.primary_fbgn = s.fbgn_id \
154
+ left join fb_fbgn_fbtr_fbpp_fb_2026_01 p on p.flybase_fbgn = s.fbgn_id \
155
+ limit 5"
156
+
157
+ python3 flybase_cli.py api domain/FBgn0001250
158
+ ```
159
+
160
+ ## Sync presets
161
+
162
+ - `gene-core`: summaries + FBgn/FBtr/FBpp + annotation IDs + SO annotations
163
+ - `gene-expression`: curated/high-throughput/scRNA expression slices
164
+ - `references`: publication/link tables
165
+ - `gene-knowledge`: core gene facts + representative publications + orthology tables
166
+ - `orthology`: ortholog, paralog, and disease-association tables
167
+ - `interactions`: gene- and allele-level interaction tables
168
+
169
+ ## Full sync
170
+
171
+ - `full-sync` crawls an entire release prefix, default `precomputed_files/`
172
+ - default behavior: download only files the current loaders can ingest into SQLite
173
+ - use `--all-files` if you want non-ingestable release artifacts too
174
+ - use `--include` / `--exclude` to stage a narrower smoke or partial warehouse
175
+ - default manifest path: `data/flybase/manifests/<release>/full-sync.json`
176
+
177
+ ## Discovery
178
+
179
+ - `genomes --release FB2026_01` lists genome builds linked from that FlyBase release
180
+ - `sync-url` turns a crawlable FlyBase directory URL into a one-step local sync
181
+ - `sync-genome` resolves a release/build pair into the right genome-section URL automatically
182
+ - `genome-presets` lists reusable genome asset sync recipes
183
+
184
+ ## Genome sync
185
+
186
+ - sections: `fasta`, `gff`, `gtf`, `dna`, `chado-xml`
187
+ - asset shortcuts include `mirna`, `transcript`, `translation`, `gene`, `chromosome`, `cds`, `ncrna`, `gff`, `gtf`
188
+ - presets include `mirna-fasta`, `transcript-fasta`, `translation-fasta`, `gene-fasta`, `chromosome-fasta`, `ncrna-fasta`, `gff-all`, `gtf-all`
189
+ - use `--include`/`--exclude` for narrower file selection on top of the asset preset
190
+
191
+ ## Ingest formats
192
+
193
+ - delimited: `tsv`, `csv`, gzipped variants
194
+ - sequence: `fasta`, `fa`, `fna`, `faa`, gzipped variants
195
+ - annotation: `gff`, `gff3`, `gtf`, gzipped variants
196
+ - JSON: `json`, `json.gz`
197
+
198
+ ## JSON ingest
199
+
200
+ - top-level scalar JSON fields become queryable SQLite columns
201
+ - one nested dict level is flattened, eg `gene.symbol` -> `gene_symbol`
202
+ - repeated top-level lists become child tables, eg `symbolSynonyms` -> `<table>_symbolsynonyms`
203
+ - repeated lists nested inside child dict rows become descendant tables, eg `genomeLocations[].exons[]` -> `<table>_genomelocations_exons`
204
+ - full source record remains in `payload_json`
205
+
206
+ Example:
207
+
208
+ ```bash
209
+ python3 flybase_cli.py sql \
210
+ "select record_id, symbol, gene_geneId from fb_ncrna_genes_fb_2026_01 limit 5"
211
+
212
+ python3 flybase_cli.py sql \
213
+ "select parent_record_id, ordinal, value \
214
+ from fb_ncrna_genes_fb_2026_01_symbolsynonyms \
215
+ limit 5"
216
+
217
+ python3 flybase_cli.py sql \
218
+ "select parent_record_id, parent_ordinal, ordinal, startPosition, endPosition \
219
+ from fb_ncrna_genes_fb_2026_01_genomelocations_exons \
220
+ limit 5"
221
+ ```
222
+
223
+ ## Search
224
+
225
+ - `fts-build` creates a local SQLite FTS5 index from ingested tables
226
+ - `search` queries that index without calling the live FlyBase API
227
+ - record ids prefer stable FlyBase-like columns such as `fbgn_id`, `primary_fbgn`, `flybase_fbtr`
228
+
229
+ ## Metadata
230
+
231
+ - `describe` summarizes ingested tables with row counts, source paths, semantic tags, columns, and representative non-empty values
232
+ - `schema-export` writes the same metadata to a deterministic JSON artifact beside the SQLite DB, eg `FB2026_01.schema.json`
233
+ - `schema-export` also includes inferred `relationships` for nested child tables and common FlyBase ID joins
234
+ - `schema-export` also emits `semantic_summary` for table/entity tag coverage
235
+ - `schema-export` also emits ready-to-run `query_templates`
236
+ - `query-plan` prints starter SQL without the larger schema payload
237
+ - `query-plan` now includes named biological templates such as `gene-summary-by-fbgn`, `transcript-protein-links`, `publications-for-gene`, and coordinate lookups when matching tables exist
238
+ - `query-run` selects one template and executes it with parameter values
239
+ - useful first step before writing ad hoc SQL or building agent query plans
240
+
241
+ Example:
242
+
243
+ ```bash
244
+ python3 flybase_cli.py schema-export \
245
+ --db data/flybase/FB2026_01.sqlite \
246
+ --sample-values 1
247
+
248
+ python3 flybase_cli.py query-plan \
249
+ --db data/flybase/FB2026_01.sqlite \
250
+ --sample-values 1 \
251
+ --limit 5
252
+
253
+ python3 flybase_cli.py query-run \
254
+ --db data/flybase/FB2026_01.sqlite \
255
+ --template-name gene-summary-by-fbgn \
256
+ --param fbgn_id=FBgn0002121
257
+ ```
258
+
259
+ ## Notes
260
+
261
+ - nested JSON child tables keep lineage columns like `parent_record_id`, `parent_ordinal`, `ordinal`.
262
+ - many FlyBase files start with `##` metadata lines; loader skips those.
263
+ - `sync` writes a preset manifest under `data/flybase/manifests/<release>/`.
264
+ - `full-sync` is the broadest offline path for release bulk data without going through the full Postgres dump.
265
+ - `sync --release FB2026_01` defaults to `data/flybase/FB2026_01.sqlite` to avoid cross-release mixing.
266
+ - `sync-incremental` uses stable manifest keys so release-renamed files still land in `updated` instead of noisy add/remove pairs.
267
+ - `release-diff` compares releases either by raw prefix or by curated multi-prefix preset.
268
+ - `manifest --url` lets you crawl non-`releases/` FlyBase directories such as genome FASTA/GFF trees.
269
+ - `sync-url` is the shortest path for genome assets once you know the directory URL.
270
+ - `sync-genome` is the shortest path when you know the FlyBase release + genome build label.
271
+ - `sync-genome --preset ...` is the preferred path for common genome asset pulls.
272
+ - some FlyBase `.gff.gz` assets are tar-wrapped gzip archives; loader handles that transparently.
273
+ - `sql` and `query-run` shape results as record-oriented JSON with summary metadata for agent chaining.
274
+ - `pg-load` stages the full Postgres import script for `releases/<release>/psql/<release>.sql.gz`.
275
+ - `pg-load --execute` runs the staged script when `createdb` and `psql` are installed locally.
276
+ - SQLite keeps setup minimal; switch to DuckDB/Postgres if you want bigger joins/faster scans.
277
+ - if you only need a few IDs, FlyBase Batch Download may be simpler than syncing files.
278
+ - use `--no-header` for files whose first non-comment row is data, not column names.
279
+
280
+ ## Tests
281
+
282
+ ```bash
283
+ python3 -m unittest discover -s tests
284
+ ```
@@ -0,0 +1,274 @@
1
+ # FlyBase local sync/query
2
+
3
+ Use FlyBase bulk files for agent workloads. Live API: helper only.
4
+
5
+ ## Why
6
+
7
+ - `https://api.flybase.org/api/v1.0/` exists.
8
+ - some endpoints return useful JSON now, eg `domain/FBgn0001250`, `sequence/id/FBgn0001250`.
9
+ - some plausible endpoints return empty body today.
10
+ - bulk bucket + release files: better for repeatable agent queries.
11
+
12
+ ## Current surfaces checked
13
+
14
+ - release bucket: `https://s3ftp.flybase.org/releases/current/`
15
+ - precomputed files: `https://s3ftp.flybase.org/releases/current/precomputed_files/`
16
+ - Postgres dump: `https://s3ftp.flybase.org/releases/current/psql/FB2026_01.sql.gz`
17
+ - API root: `https://api.flybase.org/api/v1.0/`
18
+ - batch download: `https://flybase.org/batchdownload`
19
+
20
+ ## Layout
21
+
22
+ - `src/flybase_cli/`: package code
23
+ - `tests/`: stdlib `unittest`
24
+ - `flybase_cli.py`: thin repo-root shim
25
+ - `pyproject.toml`: package metadata / console entrypoint
26
+
27
+ ## Install
28
+
29
+ PyPI with `pipx`:
30
+
31
+ ```bash
32
+ pipx install flybase
33
+ ```
34
+
35
+ PyPI with plain `pip`:
36
+
37
+ ```bash
38
+ python3 -m pip install flybase
39
+ ```
40
+
41
+ Homebrew:
42
+
43
+ ```bash
44
+ brew tap gumadeiras/tap
45
+ brew install flybase
46
+ ```
47
+
48
+ From source:
49
+
50
+ ```bash
51
+ python3 -m pip install -e .
52
+ ```
53
+
54
+ ## Release
55
+
56
+ Current release: `v0.1.2`.
57
+
58
+ Tag pushes like `vX.Y.Z` run the release workflow: build artifacts, create a
59
+ GitHub release, publish to PyPI, and update `gumadeiras/homebrew-tap`.
60
+
61
+ Release prerequisites:
62
+
63
+ - PyPI trusted publishing configured for this repo.
64
+ - `HOMEBREW_TAP_TOKEN` repository secret can write to
65
+ `gumadeiras/homebrew-tap`.
66
+
67
+ ## CLI
68
+
69
+ ```bash
70
+ python3 flybase_cli.py presets
71
+
72
+ python3 flybase_cli.py sync gene-core
73
+
74
+ python3 flybase_cli.py sync gene-core --release FB2026_01
75
+
76
+ python3 flybase_cli.py sync gene-knowledge --release FB2026_01
77
+
78
+ python3 flybase_cli.py full-sync --release FB2026_01
79
+
80
+ python3 flybase_cli.py full-sync \
81
+ --release FB2026_01 \
82
+ --include 'best_gene_summary|entity_publication'
83
+
84
+ python3 flybase_cli.py sync-incremental \
85
+ gene-knowledge \
86
+ --from-release FB2025_06 \
87
+ --release FB2026_01
88
+
89
+ python3 flybase_cli.py release-diff \
90
+ --preset gene-knowledge \
91
+ --from-release FB2025_06 \
92
+ --to-release FB2026_01
93
+
94
+ python3 flybase_cli.py genomes --release FB2026_01
95
+
96
+ python3 flybase_cli.py sync-genome \
97
+ --release FB2026_01 \
98
+ --genome dmel_r6.67 \
99
+ --section fasta \
100
+ --asset mirna
101
+
102
+ python3 flybase_cli.py genome-presets
103
+
104
+ python3 flybase_cli.py sync-genome \
105
+ --release FB2026_01 \
106
+ --genome dmel_r6.67 \
107
+ --preset mirna-fasta
108
+
109
+ PYTHONPATH=src python3 -m flybase_cli sync gene-expression
110
+
111
+ python3 flybase_cli.py manifest \
112
+ --url https://s3ftp.flybase.org/genomes/Drosophila_melanogaster/dmel_r6.67_FB2026_01/fasta/ \
113
+ --include 'miRNA'
114
+
115
+ python3 flybase_cli.py sync-url \
116
+ --url https://s3ftp.flybase.org/genomes/Drosophila_melanogaster/dmel_r6.67_FB2026_01/fasta/ \
117
+ --include 'miRNA'
118
+
119
+ python3 flybase_cli.py ingest \
120
+ data/flybase/precomputed_files/genes/best_gene_summary_fb_2026_01.tsv.gz \
121
+ data/flybase/precomputed_files/genes/fbgn_fbtr_fbpp_fb_2026_01.tsv.gz \
122
+ data/flybase/precomputed_files/genes/fbgn_annotation_ID_fb_2026_01.tsv.gz
123
+
124
+ python3 flybase_cli.py tables --columns
125
+
126
+ python3 flybase_cli.py describe --sample-values 2
127
+ python3 flybase_cli.py schema-export --sample-values 1
128
+ python3 flybase_cli.py query-plan --sample-values 1 --limit 5
129
+ python3 flybase_cli.py query-run --template-name gene-summary-by-fbgn --param fbgn_id=FBgn0002121
130
+
131
+ python3 flybase_cli.py fts-build
132
+
133
+ python3 flybase_cli.py search 'memory formation'
134
+
135
+ python3 flybase_cli.py pg-load --release FB2026_01
136
+
137
+ python3 flybase_cli.py sql \
138
+ "select * from fb_best_gene_summary_fb_2026_01 limit 5"
139
+
140
+ python3 flybase_cli.py sql \
141
+ "select s.fbgn_id, s.gene_symbol, a.annotation_id, p.flybase_fbtr, p.flybase_fbpp \
142
+ from fb_best_gene_summary_fb_2026_01 s \
143
+ join fb_fbgn_annotation_id_fb_2026_01 a on a.primary_fbgn = s.fbgn_id \
144
+ left join fb_fbgn_fbtr_fbpp_fb_2026_01 p on p.flybase_fbgn = s.fbgn_id \
145
+ limit 5"
146
+
147
+ python3 flybase_cli.py api domain/FBgn0001250
148
+ ```
149
+
150
+ ## Sync presets
151
+
152
+ - `gene-core`: summaries + FBgn/FBtr/FBpp + annotation IDs + SO annotations
153
+ - `gene-expression`: curated/high-throughput/scRNA expression slices
154
+ - `references`: publication/link tables
155
+ - `gene-knowledge`: core gene facts + representative publications + orthology tables
156
+ - `orthology`: ortholog, paralog, and disease-association tables
157
+ - `interactions`: gene- and allele-level interaction tables
158
+
159
+ ## Full sync
160
+
161
+ - `full-sync` crawls an entire release prefix, default `precomputed_files/`
162
+ - default behavior: download only files the current loaders can ingest into SQLite
163
+ - use `--all-files` if you want non-ingestable release artifacts too
164
+ - use `--include` / `--exclude` to stage a narrower smoke or partial warehouse
165
+ - default manifest path: `data/flybase/manifests/<release>/full-sync.json`
166
+
167
+ ## Discovery
168
+
169
+ - `genomes --release FB2026_01` lists genome builds linked from that FlyBase release
170
+ - `sync-url` turns a crawlable FlyBase directory URL into a one-step local sync
171
+ - `sync-genome` resolves a release/build pair into the right genome-section URL automatically
172
+ - `genome-presets` lists reusable genome asset sync recipes
173
+
174
+ ## Genome sync
175
+
176
+ - sections: `fasta`, `gff`, `gtf`, `dna`, `chado-xml`
177
+ - asset shortcuts include `mirna`, `transcript`, `translation`, `gene`, `chromosome`, `cds`, `ncrna`, `gff`, `gtf`
178
+ - presets include `mirna-fasta`, `transcript-fasta`, `translation-fasta`, `gene-fasta`, `chromosome-fasta`, `ncrna-fasta`, `gff-all`, `gtf-all`
179
+ - use `--include`/`--exclude` for narrower file selection on top of the asset preset
180
+
181
+ ## Ingest formats
182
+
183
+ - delimited: `tsv`, `csv`, gzipped variants
184
+ - sequence: `fasta`, `fa`, `fna`, `faa`, gzipped variants
185
+ - annotation: `gff`, `gff3`, `gtf`, gzipped variants
186
+ - JSON: `json`, `json.gz`
187
+
188
+ ## JSON ingest
189
+
190
+ - top-level scalar JSON fields become queryable SQLite columns
191
+ - one nested dict level is flattened, eg `gene.symbol` -> `gene_symbol`
192
+ - repeated top-level lists become child tables, eg `symbolSynonyms` -> `<table>_symbolsynonyms`
193
+ - repeated lists nested inside child dict rows become descendant tables, eg `genomeLocations[].exons[]` -> `<table>_genomelocations_exons`
194
+ - full source record remains in `payload_json`
195
+
196
+ Example:
197
+
198
+ ```bash
199
+ python3 flybase_cli.py sql \
200
+ "select record_id, symbol, gene_geneId from fb_ncrna_genes_fb_2026_01 limit 5"
201
+
202
+ python3 flybase_cli.py sql \
203
+ "select parent_record_id, ordinal, value \
204
+ from fb_ncrna_genes_fb_2026_01_symbolsynonyms \
205
+ limit 5"
206
+
207
+ python3 flybase_cli.py sql \
208
+ "select parent_record_id, parent_ordinal, ordinal, startPosition, endPosition \
209
+ from fb_ncrna_genes_fb_2026_01_genomelocations_exons \
210
+ limit 5"
211
+ ```
212
+
213
+ ## Search
214
+
215
+ - `fts-build` creates a local SQLite FTS5 index from ingested tables
216
+ - `search` queries that index without calling the live FlyBase API
217
+ - record ids prefer stable FlyBase-like columns such as `fbgn_id`, `primary_fbgn`, `flybase_fbtr`
218
+
219
+ ## Metadata
220
+
221
+ - `describe` summarizes ingested tables with row counts, source paths, semantic tags, columns, and representative non-empty values
222
+ - `schema-export` writes the same metadata to a deterministic JSON artifact beside the SQLite DB, eg `FB2026_01.schema.json`
223
+ - `schema-export` also includes inferred `relationships` for nested child tables and common FlyBase ID joins
224
+ - `schema-export` also emits `semantic_summary` for table/entity tag coverage
225
+ - `schema-export` also emits ready-to-run `query_templates`
226
+ - `query-plan` prints starter SQL without the larger schema payload
227
+ - `query-plan` now includes named biological templates such as `gene-summary-by-fbgn`, `transcript-protein-links`, `publications-for-gene`, and coordinate lookups when matching tables exist
228
+ - `query-run` selects one template and executes it with parameter values
229
+ - useful first step before writing ad hoc SQL or building agent query plans
230
+
231
+ Example:
232
+
233
+ ```bash
234
+ python3 flybase_cli.py schema-export \
235
+ --db data/flybase/FB2026_01.sqlite \
236
+ --sample-values 1
237
+
238
+ python3 flybase_cli.py query-plan \
239
+ --db data/flybase/FB2026_01.sqlite \
240
+ --sample-values 1 \
241
+ --limit 5
242
+
243
+ python3 flybase_cli.py query-run \
244
+ --db data/flybase/FB2026_01.sqlite \
245
+ --template-name gene-summary-by-fbgn \
246
+ --param fbgn_id=FBgn0002121
247
+ ```
248
+
249
+ ## Notes
250
+
251
+ - nested JSON child tables keep lineage columns like `parent_record_id`, `parent_ordinal`, `ordinal`.
252
+ - many FlyBase files start with `##` metadata lines; loader skips those.
253
+ - `sync` writes a preset manifest under `data/flybase/manifests/<release>/`.
254
+ - `full-sync` is the broadest offline path for release bulk data without going through the full Postgres dump.
255
+ - `sync --release FB2026_01` defaults to `data/flybase/FB2026_01.sqlite` to avoid cross-release mixing.
256
+ - `sync-incremental` uses stable manifest keys so release-renamed files still land in `updated` instead of noisy add/remove pairs.
257
+ - `release-diff` compares releases either by raw prefix or by curated multi-prefix preset.
258
+ - `manifest --url` lets you crawl non-`releases/` FlyBase directories such as genome FASTA/GFF trees.
259
+ - `sync-url` is the shortest path for genome assets once you know the directory URL.
260
+ - `sync-genome` is the shortest path when you know the FlyBase release + genome build label.
261
+ - `sync-genome --preset ...` is the preferred path for common genome asset pulls.
262
+ - some FlyBase `.gff.gz` assets are tar-wrapped gzip archives; loader handles that transparently.
263
+ - `sql` and `query-run` shape results as record-oriented JSON with summary metadata for agent chaining.
264
+ - `pg-load` stages the full Postgres import script for `releases/<release>/psql/<release>.sql.gz`.
265
+ - `pg-load --execute` runs the staged script when `createdb` and `psql` are installed locally.
266
+ - SQLite keeps setup minimal; switch to DuckDB/Postgres if you want bigger joins/faster scans.
267
+ - if you only need a few IDs, FlyBase Batch Download may be simpler than syncing files.
268
+ - use `--no-header` for files whose first non-comment row is data, not column names.
269
+
270
+ ## Tests
271
+
272
+ ```bash
273
+ python3 -m unittest discover -s tests
274
+ ```
@@ -0,0 +1,20 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "flybase"
7
+ version = "0.1.4"
8
+ description = "FlyBase sync/query helper for agents."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.11"
12
+
13
+ [project.scripts]
14
+ flybase = "flybase_cli.cli:main"
15
+
16
+ [tool.setuptools]
17
+ package-dir = {"" = "src"}
18
+
19
+ [tool.setuptools.packages.find]
20
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+