{"id":51889448,"url":"https://github.com/teaql/teaql-java","last_synced_at":"2026-07-26T02:02:56.076Z","repository":{"id":118242921,"uuid":"564696813","full_name":"teaql/teaql-java","owner":"teaql","description":"An AI-Native deterministic libray for undeterministic AI Coding in Java","archived":false,"fork":false,"pushed_at":"2026-07-25T04:24:59.000Z","size":1622,"stargazers_count":3,"open_issues_count":9,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-07-25T06:09:32.582Z","etag":null,"topics":["aicoding","java","springboot","teaql"],"latest_commit_sha":null,"homepage":"https://teaql.io/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/teaql.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2022-11-11T09:31:43.000Z","updated_at":"2026-07-17T15:57:22.000Z","dependencies_parsed_at":"2024-01-22T11:47:32.479Z","dependency_job_id":"94a3cae9-34c2-4995-9f95-5d931a49c697","html_url":"https://github.com/teaql/teaql-java","commit_stats":null,"previous_names":["teaql/teaql-java"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/teaql/teaql-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teaql%2Fteaql-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teaql%2Fteaql-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teaql%2Fteaql-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teaql%2Fteaql-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/teaql","download_url":"https://codeload.github.com/teaql/teaql-java/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teaql%2Fteaql-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35898043,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-26T02:00:06.503Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aicoding","java","springboot","teaql"],"created_at":"2026-07-26T02:02:55.366Z","updated_at":"2026-07-26T02:02:56.061Z","avatar_url":"https://github.com/teaql.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# teaql-java\n\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13612/badge)](https://www.bestpractices.dev/projects/13612)\n\n**TeaQL is an AI-native runtime designed for Coding Agents and modern application development.** \n\nWhile traditional frameworks assume a human is writing every line of code, TeaQL provides a strict, typed, and auditable Capability Sandbox tailored specifically for autonomous AI Agents (and humans) to execute code securely.\n\n### The Five Safeguards of AI Coding\n\nTo ensure absolute safety and governance when AI Agents interact with production systems, the TeaQL runtime enforces the following five safeguards:\n\n1. **Mandatory Identity (UserContext):** Every operation must pass through a runtime `UserContext`. The system explicitly records whether the action was performed by a human or an AI Agent.\n2. **Intent Auditing (Typestate/Builder):** Agents cannot simply call `.execute()`. They are forced by the compiler to declare their intent using `.purpose()` (for reads) or `.auditAs()` (for writes) before the execution terminal is unlocked.\n3. **Capability Sandbox (SPI/Features):** Dangerous operations (HTTP, File IO, Message Queues) are physically isolated. Unless explicitly granted in the project dependencies (via JPMS SPI or Cargo features), the Agent is structurally blocked from accessing them.\n4. **Graph Mutability Control:** Agents do not manually assemble SQL `UPDATE`s or relationship loops. They operate on typed Entity Graphs (`saveGraph`), reducing hallucination-induced data corruption.\n5. **Universal Error Translation:** The runtime intercepts infrastructure errors and translates them into semantic business codes, preventing the Agent from getting stuck in stack trace loops.\n\n---\n\nTeaQL Java is the Java runtime for TeaQL domain applications. It provides the\ncore entity/request/repository model, SQL repository support, database-specific\ndialects, and integration modules for Spring Boot and Android.\n\nTeaQL Java is positioned as a portable domain runtime across Android,\ndesktop/console, and server-side Java frameworks, with pluggable SQL/database\nmodules.\n\nThe main runtime path is designed to run without reflection-heavy entity\nconstruction or bean mutation. See\n[Native Image Reflection Guide](NATIVE_IMAGE_REFLECTION_GUIDE.md) for the\nno-reflection baseline and coding rules.\n\nFor TeaQL entities, JSON serialization/deserialization and SQL result-set row\nmapping are on that no-reflection path:\n\n- `teaql-jackson` registers explicit TeaQL entity serializers and\n  deserializers through `TeaQLModule`.\n- `teaql-sql-portable` creates entities from database rows through\n  `EntityDescriptor.createEntity()`, backed by registered suppliers such as\n  `Task::new`.\n- Generated or hand-written metadata must register `entitySupplier` beside\n  `targetType`.\n\nKeep dynamic/additional values JSON-friendly, such as scalars, maps, lists, and\nother already-serializable values. If an application stores arbitrary Java\nobjects in dynamic/additional fields, Jackson may still use its default bean\nintrospection for those application objects.\n\nThe project was renamed from `teaql-spring-boot-starter` to `teaql-java` as the\nruntime moved from a Spring-only package to a modular Java runtime. The Spring\nBoot starter artifact remains `teaql-spring-boot-starter` for compatibility.\n\n## Modules\n\n### Core Modules\n| Module | Purpose |\n| --- | --- |\n| `teaql-core` | Core entities, requests, criteria, metadata, audit logging, policies, and contracts. Completely independent of Spring/SQL. |\n| `teaql-runtime` | Default runtime implementation including `TeaQLRuntime` engine, user contexts, registry lookup, and an optimized concurrent in-memory database execution service with LRU eviction. |\n\n### Optional Modules\n| Module | Purpose |\n| --- | --- |\n| `teaql-jackson` | Explicit TeaQL entity JSON serialization and deserialization support. |\n| `teaql-query-json` | JSON query parsing support. |\n| `teaql-runtime-log` | Optional runtime log sinks. |\n| `teaql-context-runtime-tools` | Runtime tool registration and policy integration. |\n| `teaql-tool-http` | Optional HTTP tool support. |\n| `teaql-sql-portable` | Portable SQL repository through the `TeaQLDatabase` abstraction. |\n| `teaql-data-service-sql` | SQL data service integration. |\n| `teaql-provider-jdbc`, `teaql-provider-spring-jdbc` | JDBC provider integrations. |\n| `teaql-sqlite`, `teaql-mysql`, `teaql-postgres`, etc. | Database-specific SQL repository modules. |\n| `teaql-android` | Android-facing integration helpers. |\n\n### Module Selection Matrix\n\n`✅` means the module is directly useful for that application type. Database\nmodules are selected by the target database; most applications only need one\ndialect module.\n\n| Module | Android APP | Compose APP | Console APP | Spring Boot APP | Quarkus APP | Micronaut APP |\n| --- | ---: | ---: | ---: | ---: | ---: | ---: |\n| `teaql-core` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-runtime` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-jackson` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-query-json` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-runtime-log` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-sql-portable` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-data-service-sql` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-provider-jdbc` | ✅ | ✅ | ✅ |  | ✅ | ✅ |\n| `teaql-provider-spring-jdbc` |  |  |  | ✅ |  |  |\n| `teaql-utils` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-utils-json` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-utils-reflection` |  |  |  | ✅ |  |  |\n| `teaql-utils-spring` |  |  |  | ✅ |  |  |\n| `teaql-context-runtime-tools` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-tool-http` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-android` | ✅ |  |  |  |  |  |\n| `teaql-sqlite` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-mysql` |  | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-postgres` |  | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-oracle` |  | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-db2` |  | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-mssql` |  | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-hana` |  | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-duckdb` |  | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-snowflake` |  | ✅ | ✅ | ✅ | ✅ | ✅ |\n| `teaql-dm8` |  | ✅ | ✅ | ✅ | ✅ | ✅ |\n\n## Requirements\n\n- Java 17+\n- Maven 3.8+\n\n## Dependency Examples\n\nSpring Boot applications should depend on the starter artifact:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.teaql\u003c/groupId\u003e\n    \u003cartifactId\u003eteaql-spring-boot-starter\u003c/artifactId\u003e\n    \u003cversion\u003e1.516-RELEASE\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nAndroid applications should use `teaql-sql-portable` and provide a platform-specific\n`TeaQLDatabase` implementation.\n\n## Runtime Model\n\nTeaQL request objects are executable only after the request carries enough\nintent for policy and audit checks. A typical generated request flow looks like:\n\n```java\nQ.tasks()\n    .comment(\"Load tasks\")\n    .purpose(\"Display kanban board\")\n    .executeForList(userContext);\n```\n\nThe default runtime keeps a small execution surface. Applications can replace\n`RequestPolicy`, `RuntimeLogSink`, `DataStore`, `LockService`, `Translator`, and\n`EntityMetaFactory` beans in their framework integration layer. File/stdout log\nwriting is provided by the optional `teaql-runtime-log` module.\n\n## Framework Integration\n\n### Spring Boot\n\n`teaql-autoconfigure` provides the default Spring Boot runtime beans, while the\nstarter artifact pulls the auto-configuration into an application.\n\nSQLite applications can use normal Spring datasource properties:\n\n```properties\nspring.datasource.url=jdbc:sqlite:./data/app.db\nspring.datasource.driver-class-name=org.sqlite.JDBC\n```\n\nWhen the SQLite module sees a `jdbc:sqlite:` URL, it wraps the datasource with a\nsingle-connection datasource to avoid common SQLite multi-connection lock\ncontention.\n\n### Android\n\n`teaql-sql-portable` removes the `spring-jdbc` dependency from the repository\npath. The module is not an Android SDK module, but its main use case today is\nAndroid: application code supplies an Android-backed `TeaQLDatabase`\nimplementation, and the repository executes positional SQL through that\nabstraction.\n\n## Build \u0026 Development\n\nTo build the project from source, you need Java 17+ and Maven 3.8+:\n\n```bash\ngit clone https://github.com/teaql/teaql-java.git\ncd teaql-java\nmvn clean install\n```\n\nRun tests where present:\n\n```bash\nmvn test\n```\n\n## Reporting Bugs\n\nIf you find a bug, please create an issue on [GitHub Issues](https://github.com/teaql/teaql-java/issues).\nPlease include as much detail as possible, such as TeaQL version, Java version, framework details, and steps to reproduce.\nFor security vulnerabilities, please see our [Security Policy](SECURITY.md).\n\nScan for Chinese comments or strings:\n\n```bash\nnode scan-chinese.js\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteaql%2Fteaql-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteaql%2Fteaql-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteaql%2Fteaql-java/lists"}