hyperterse 1.4.0 → 2.0.0-rc.0

package/README.md

@@ -1,191 +1,80 @@
 <div align="center">
-
-[![Hyperterse](docs/public/og.png)](https://docs.hyperterse.com)
-
-# Hyperterse
-
-**Connect your data to your agents.**
-
-A declarative interface between your data and modern software. Turn database queries into stable APIs and AI-ready tools—without exposing SQL, writing boilerplate, or coupling your application to your database.
-
-[Website](https://hyperterse.com) • [Documentation](https://docs.hyperterse.com) • [Quick Start](#quick-start) • [Features](#features) • [Examples](#examples)
-
+  <picture>
+    <img alt="Hyperterse - connect your data to your agents." src="docs/assets/og.png" />
+  </picture>
 </div>
+<br />
+<div align="center">
+  <h1>Hyperterse</h1>
+</div>
+<p align="center">
+  <strong>The declarative framework for performant MCP servers.</strong><br />
+  <a href="https://hyperterse.com">Website</a>
+  •
+  <a href="https://docs.hyperterse.com">Documentation</a>
+  •
+  <a href="#quick-start">Quick Start</a>
+  •
+  <a href="#tool-examples">Examples</a>
+  •
+  <a href="https://github.com/hyperterse/hyperterse">GitHub</a>
+</p>
 
 ---
 
-## What is Hyperterse?
-
-Hyperterse is a high-performance runtime server that transforms database queries into REST endpoints and MCP (Model Context Protocol) tools.
-
-You describe your queries once, in a simple configuration file. Hyperterse does the rest:
-
-- Generates individual, typed endpoints
-- Validates inputs automatically
-- Produces OpenAPI documentation
-- Exposes queries safely to AI systems
-
-No ORMs. No boilerplate. No exposed SQL.
-
-## Designed for Modern Systems
-
-### AI & LLM Applications
-
-Hyperterse is built with AI in mind.
-
-- **AI agents and assistants** - Safely query databases through MCP without exposing raw SQL.
-- **LLM tool calling** - Let models discover and invoke database operations autonomously.
-- **Retrieval-augmented generation (RAG)** - Use structured database queries as reliable context.
-- **Conversational interfaces** - Power chatbots that access live business data.
-- **AI-driven analytics** - Enable models to generate insights through validated queries.
-- **Multi-agent systems** - Share consistent database access across agents.
-- **Natural language to SQL pipelines** - Bridge human input and databases using tool calls.
-- **AI dashboards** - Query and visualize data dynamically.
-
-### Traditional Use Cases
-
-- **Database-backed APIs** without boilerplate
-- **Lightweight microservices** without ORM overhead
-- **Rapid prototyping** with configuration-first workflows
-
-## Features
-
-Hyperterse comes several features that help you leverage accessing your data in a secure manner for your AI agents and LLMs.
-
-### Declarative data interfaces
-
-Define the shape and intent of data access once, and let Hyperterse handle execution, validation, and exposure.
-
-### Agent-ready by design
-
-Connect your data to AI agents through discoverable, callable tools—without exposing SQL, schemas, or credentials.
-
-### Zero-boilerplate API
-
-Turn queries into production-ready APIs with typed inputs, predictable outputs, and built-in documentation.
+Hyperterse turns tool configs into callable tools, with:
 
-### Single source of truth
+- filesystem-based tool discovery,
+- pluggable adapters (Postgres, MySQL, MongoDB, Redis),
+- optional scripts for transforms and handlers,
+- MCP runtime exposure over Streamable HTTP.
 
-Generate REST endpoints, OpenAPI specs, LLM-readable docs, and MCP tools from one configuration file.
+## What Hyperterse is
 
-### Database independence
+- **Tool-first MCP framework**: each tool config compiles into a tool.
+- **Declarative runtime**: root config + adapter files + tool files.
+- **Extensible execution pipeline**: auth -> input transform -> execute -> output transform.
+- **Embedded scripting**: script hooks run in a sandboxed runtime; bundled at compile time.
 
-Work across PostgreSQL, MySQL, MongoDB, and Redis using a consistent, unified interface.
+## Quick start
 
-### Fast and iterative development
-
-Update queries and schemas with immediate feedback during development.
-
-### Portable deployment
-
-Ship a self-contained runtime that moves cleanly from local development to production.
-
-### Built to scale
-
-Support everything from prototypes to multi-agent systems without changing your architecture.
-
-## Quick Start
-
-### Installation
-
-Install Hyperterse with a single command:
+### Install
 
 ```bash
 curl -fsSL https://hyperterse.com/install | bash
 ```
 
-**Supported platforms:**
+### Initialize
 
-- Linux (amd64, arm64, arm)
-- macOS (Intel, Apple Silicon)
-- Windows (amd64, arm64)
+```bash
+hyperterse init
+```
 
-For more installation options, see the [installation guide](https://docs.hyperterse.com/getting-started/installation).
+This scaffolds:
 
-### Your First Query
+- `.hyperterse`
+- `app/adapters/my-database.terse`
+- `app/tools/hello-world/config.terse`
+- `app/tools/hello-world/user-data-mapper.ts`
 
-Create a configuration file:
+### Run
 
-```yaml
-name: my-api
-
-adapters:
-  my_database:
-    connector: postgres
-    connection_string: "postgresql://user:password@localhost:5432/mydb"
-
-queries:
-  get-user:
-    use: my_database
-    description: "Retrieve a user by email address"
-    statement: |
-      SELECT id, name, email, created_at
-      FROM users
-      WHERE email = {{ inputs.email }}
-    inputs:
-      email:
-        type: string
-        description: "User email address"
+```bash
+hyperterse start
 ```
 
-Start the server:
+With hot reload:
 
 ```bash
-hyperterse run -f config.terse
+hyperterse start --watch
 ```
 
-Call the endpoint:
+### Test
 
 ```bash
-curl -X POST http://localhost:8080/query/get-user \
-  -H "Content-Type: application/json" \
-  -d '{"email": "user@example.com"}'
-```
-
-Response:
-
-```json
-{
-  "success": true,
-  "error": "",
-  "results": [
-    {
-      "id": 123,
-      "name": "John Doe",
-      "email": "user@example.com",
-      "created_at": "2024-01-01T00:00:00Z"
-    }
-  ]
-}
+curl http://localhost:8080/heartbeat
 ```
 
-## Documentation
-
-📚 **[Read the docs →](https://docs.hyperterse.com)**
-
-- **[Getting Started](https://docs.hyperterse.com/getting-started/quick-start)** - Quick start guide and installation
-- **[CLI Reference](https://docs.hyperterse.com/reference/cli)** - Complete command-line interface reference
-- **[Configuration Guide](https://docs.hyperterse.com/reference/configuration)** - Configuration file reference
-- **[Guides](https://docs.hyperterse.com/guides)** - Practical guides for AI integration, OpenAPI, MCP, and caching
-- **[Caching Guide](https://docs.hyperterse.com/guides/caching)** - Executor-level query caching, TTL, and override strategy
-- **[Concepts](https://docs.hyperterse.com/concepts)** - Core concepts: adapters, queries, and inputs
-- **[Databases](https://docs.hyperterse.com/databases)** - Database-specific documentation
-- **[Deployment](https://docs.hyperterse.com/deployment)** - Deployment guides for various platforms
-
-### Runtime Endpoints
-
-When running, Hyperterse exposes several endpoints:
-
-- **OpenAPI Documentation**: `GET /docs` - Interactive API documentation
-- **LLM Documentation**: `GET /llms.txt` - AI-friendly documentation format
-- **MCP Protocol**: `POST /mcp` - Model Context Protocol JSON-RPC endpoint
-
-## Examples
-
-### MCP Protocol
-
-List available tools:
-
 ```bash
 curl -X POST http://localhost:8080/mcp \
   -H "Content-Type: application/json" \
@@ -196,160 +85,102 @@ curl -X POST http://localhost:8080/mcp \
   }'
 ```
 
-Invoke a tool:
+## Project structure
 
-```bash
-curl -X POST http://localhost:8080/mcp \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "method": "tools/call",
-    "params": {
-      "name": "get-user-by-id",
-      "arguments": {
-        "userId": "123"
-      }
-    },
-    "id": 1
-  }'
+```text
+my-project/
+  .hyperterse
+  app/
+    adapters/
+      main-db.terse
+    tools/
+      get-user/
+        config.terse
+        input.ts
+        output.ts
+      get-weather/
+        config.terse
+        handler.ts
 ```
 
-### User Management
+## Tool examples
 
-```yaml
-queries:
-  get-user-by-id:
-    use: user_db
-    description: "Retrieve user information by ID"
-    statement: |
-      SELECT id, name, email, created_at
-      FROM users
-      WHERE id = {{ inputs.userId }}
-```
-
-### Analytics
+### DB-backed tool
 
 ```yaml
-queries:
-  daily-stats:
-    description: "Daily statistics over a date range"
-    statement: |
-      SELECT
-        DATE(created_at) AS date,
-        COUNT(*) AS total_events,
-        COUNT(DISTINCT user_id) AS unique_users
-      FROM events
-      WHERE created_at BETWEEN {{ inputs.startDate }} AND {{ inputs.endDate }}
-      GROUP BY DATE(created_at)
-      ORDER BY date DESC
-```
-
-## CLI
-
-Run:
-
-```bash
-hyperterse run -f config.terse
-```
-
-Development mode (hot reload):
-
-```bash
-hyperterse dev -f config.terse
-```
-
-Validate configuration:
-
-```bash
-hyperterse validate -f config.terse
-```
-
-Generate artifacts:
-
-```bash
-hyperterse generate llms -f config.terse
-hyperterse generate skills -f config.terse
+description: "Get user by id"
+use: main-db
+statement: |
+  SELECT id, name, email
+  FROM users
+  WHERE id = {{ inputs.user_id }}
+inputs:
+  user_id:
+    type: int
 ```
 
-Initialize:
+### Script-backed tool
 
-```bash
-hyperterse init
+```yaml
+description: "Get weather"
+handler: "./weather-handler.ts"
 ```
 
-Upgrade:
+## CLI commands
 
-```bash
-hyperterse upgrade
-```
+- `start` - run runtime from config
+- `serve` - run from a compiled artifact
+- `build` - produce a deployable artifact
+- `validate` - validate config and tool scripts
+- `init` - scaffold starter project
+- `upgrade` - upgrade installed binary
+- `completion` - shell completion helper
 
-Export:
+## Build and deploy
 
 ```bash
-hyperterse export -f config.terse -o dist
+hyperterse validate
+hyperterse build -o dist
+hyperterse serve dist/
 ```
 
-## Configuration
+The `dist/` output includes everything needed to run in production.
 
-Hyperterse uses a simple YAML-like configuration format (`.terse` files) to define your database adapters and queries.
+## Configuration highlights
 
-**Supported input types:** `string`, `int`, `float`, `boolean`, `uuid`, `datetime`
+- root config: `.hyperterse`
+- adapter files: `app/adapters/*.terse`
+- tool files: `app/tools/*/config.terse`
 
-**Template syntax:**
-
-```sql
-WHERE price <= {{ inputs.maxPrice }}
-```
-
-**Optional inputs:**
-
-```yaml
-optional: true
-default: "20"
-```
+Supported primitive types:
 
-**Multiple databases:** Hyperterse supports multiple adapters in a single configuration file.
+- `string`
+- `int`
+- `float`
+- `boolean`
+- `datetime`
 
-For complete configuration reference, see the [configuration guide](https://docs.hyperterse.com/reference/configuration).
+## Security note
 
-## Security
-
-Hyperterse is designed with security as a baseline:
-
-- 🔒 **Credentials are never exposed** - Connection strings stay server-side
-- 🛡️ **SQL is never returned to clients** - Raw queries remain hidden
-- ✅ **Inputs are validated and escaped** - Strong typing prevents injection
-- 🔇 **Errors are sanitized by default** - Internal details stay internal
-
-For production deployments, place Hyperterse behind a reverse proxy for authentication, rate limiting, and TLS. See the [production security guide](https://docs.hyperterse.com/security/production) for best practices.
+Hyperterse validates typed inputs, but statement placeholder substitution (`{{ inputs.x }}`) is raw string replacement. Use strict tool input constraints and safe query patterns for production.
 
 ## Contributing
 
-Contributions are welcome! We appreciate your help in making Hyperterse better.
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Add tests for your changes
-4. Ensure code follows standard Go formatting
-5. Open a pull request
-
-Please keep changes focused and well-tested. For major changes, open an issue first to discuss your proposal. See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed development guidelines.
-
-**Please note**: By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). We are committed to providing a welcoming and inclusive environment for all contributors.
+1. Fork the repo
+2. Create a feature branch
+3. Add or update tests
+4. Run validation/lint/test locally
+5. Open a PR
 
-## Support
-
-- 🌐 **Website**: [hyperterse.com](https://hyperterse.com)
-- 📖 **Documentation**: [docs.hyperterse.com](https://docs.hyperterse.com)
-- 🐛 **Issues**: [GitHub Issues](https://github.com/hyperterse/hyperterse/issues)
-- 💬 **Discussions**: [GitHub Discussions](https://github.com/hyperterse/hyperterse/discussions)
+See `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md`.
 
 ---
 
-<div align="center">
-
-Made with care by the Hyperterse team.
-
-[Website](https://hyperterse.com) • [GitHub](https://github.com/hyperterse/hyperterse) • [Documentation](https://docs.hyperterse.com)
-
-</div>
+<p align="center">
+  The declarative framework for performant MCP servers.<br />
+  <a href="https://hyperterse.com">Website</a>
+  •
+  <a href="https://github.com/hyperterse/hyperterse">GitHub</a>
+  •
+  <a href="https://docs.hyperterse.com">Documentation</a>
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperterse",
-  "version": "1.4.0",
+  "version": "2.0.0-rc.0",
   "description": "A declarative interface to connect your database to your AI agents",
   "author": "Samrith Shankar <samrith@outlook.com>",
   "license": "Apache-2.0",