# GdiSDK

> GdiSDK (Geo Data Intelligence Software Development Kit) is a Python SDK for building data processing,
> engineering analysis, reporting, and GDIM-deployable workflow applications in geotechnical engineering,
> soil and groundwater, and resource / mineral engineering domains.

It follows a workflow programming model built around `PipeLine` + `PipeModule`, so engineers can connect
typed ports, reuse modules, and package the result as a GDIM application instead of writing large amounts
of boilerplate code from scratch.

Key concepts: `PipeLine`, `PipeModule`, `PipeLine.run(verbose=True, run_trace_file=...)`,
`PortType` / `PortTypeHint`, `TableData`, `TableCollection`, `ResultModel`, `SingleResult`,
`AgentRunResult`, `DocData`, `PlotData`, `update_ui_schema()`, `PipeLine.add_attribute()`,
`PythonCoder`, `@local_function`, `PipeLine.save_data_to_db()` / GDIM cross-pipeline data storage,
GDIM upload compatibility.

The SDK is documented as a four-layer architecture:
- **DataClass**: standardised data structures — `gdimData`, `geoProfiles`, `geoStructures`, `logs`, `tables`, `results`, `terminologies`, `llmAIModels`, plus common port payloads such as `TableData`, `TableCollection`, `ResultModel`, `SingleResult`, `DocData`, `PlotData`
- **Modules**: built-in modules for readers, writers, converters, dataClean, filters, mergers, operators, statistics, gisOperators, plotters, llmAI, widgets, geoSurvey, geoDataProcess, pileFoundation, shallowFoundation, foundationPit, and related domains
- **Pipeline**: the workflow engine (`pipeline`, `pipeData`, port types, links, flow control, observability, runner), typed ports, attributes, runtime execution, and debugging
- **GDIM**: the deployment and interaction layer for publishing `.pipe` applications on the GDIM platform

Language note: the official documentation is written in Chinese (Simplified).

## Docs

- [Overview](https://gdisdk.kulunsoft.com/overview.html): Product introduction, design philosophy, four-layer architecture (DataClass / Modules / Pipeline / GDIM), package map, use cases, and an interactive intro slide linked from the page
- [Getting Started](https://gdisdk.kulunsoft.com/getting_started.html): Installation, Python 3.11 environment setup, dependency installation, and beginner walkthroughs for building first pipelines
- [AI-Assisted Development (Code Agent)](https://gdisdk.kulunsoft.com/ai_assisted_dev.html): How to use `gdisdk-skills` with AI IDEs such as Cursor / Trae; explains `pipeline-creator`, `local-function-coder`, and `pipeline-gdim-review`
- [User Guide](https://gdisdk.kulunsoft.com/user_guide.html): Pipeline and module design concepts, `add_links`, ports, attributes, `update_ui_schema`, custom modules, `PythonCoder`, `.pipe` packaging, and GDIM deployment
- [Pipeline Runtime](https://gdisdk.kulunsoft.com/pipeline_runtime.html): How pipeline execution works internally, module triggering, DAG propagation, attributes, returned results, and runtime behaviour
- [Pipeline Debug](https://gdisdk.kulunsoft.com/pipeline_debug.html): Local debugging with `verbose` and `run_trace_file`, generated `run_trace.json` / `run_trace.html`, and how to inspect module execution order and bottlenecks
- [GDIM Upload Checklist](https://gdisdk.kulunsoft.com/gdim_upload_checklist.html): Pre-upload rules and compatibility checks for pipelines that will run on GDIM
- [Module Help](https://gdisdk.kulunsoft.com/module_help.html): Practical usage guide for common built-in modules. Sections cover `readers`, `writers`, `converters`, `mergers`, `filters`, `statistics`, `operators`, `gisOperators`, `geoSurvey`, `llmAI`, `plotters`, and `widgets`
- [Port Types](https://gdisdk.kulunsoft.com/porttype_help.html): How to choose `PortType` / `PortTypeHint` for module ports, including `TableData`, `TableCollection`, `ResultModel`, `SingleResult`, `AgentRunResult`, `DocData`, and `PlotData`
- [Port Dataclasses](https://gdisdk.kulunsoft.com/dataclass_help.html): Practical guide to the data structures behind ports, including `FieldMetadata`, `TableData`, `TableCollection`, `ResultModel`, `SingleResult`, `AgentRunResult`, `DocData`, `PlotData`, coordinate systems, and GDIM-related data models
- [UI Schema](https://gdisdk.kulunsoft.com/ui_schema.html): How `UIAttributeSchema` and subclasses such as `StringAttributeSchema`, `IntegerAttributeSchema`, `FloatAttributeSchema`, `ArrayAttributeSchema`, `ObjectAttributeSchema`, and `FileAttributeSchema` drive GDIM form generation

## Examples

- [Examples](https://gdisdk.kulunsoft.com/examples.html): Learning-case index (Chinese walkthroughs; authors recommend typing examples manually early on, then using AI-assisted development once familiar)
- [Screen bores by depth](https://gdisdk.kulunsoft.com/examples.screen_bores.html): Filter boreholes to those deeper than a threshold (e.g. 20 m)
- [Bore depth bar chart](https://gdisdk.kulunsoft.com/examples.bore_depth_bar.html): Plot borehole depth as a bar chart from bore data
- [Layer average thickness](https://gdisdk.kulunsoft.com/examples.layer_avg_thickness.html): Compute average stratum thickness from a layer table
- [Process layer table](https://gdisdk.kulunsoft.com/examples.process_layer_table.html): Read layer CSV, dedupe by bore id, add `layer_name`, export processed CSV
- [Write layer table to GDIM](https://gdisdk.kulunsoft.com/examples.write_layer_table_to_gdim.html): Upload processed layer data into GDIM's borehole overview table (钻孔一览表)

## Optional

- [API Reference](https://gdisdk.kulunsoft.com/api_reference.html): Full auto-generated class and function reference for `gdi` / `gdisdk`, organised under **Modules**, **Pipeline** (including `pipeline.flowControl`, `pipeline.observability`, `pipeline.runner`, etc.), and **Dataclass**
- [Changelog](https://gdisdk.kulunsoft.com/changelog.html): Version history; recent releases include `v0.3.2` (e.g. `WaterSoilCorrosion`, `save_data_to_db`, `GdimAppDataReader` / `GdimAppDataSelector`, `SphericalKMeans`, `TableDescribe`, markdown/LaTeX and GDIM writer fixes), `v0.3.1` (verbose / run trace, `TableToResultModel`, markdown writers, `ReadGtbFile`), and `v0.3.0` (`ResultModel`, `AgentRunResult`, `ConditionalLink`, `MergeResultModels`, GDIM `gdim_state`)