rapitapir 0.1.2 → 2.1.0
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.
- checksums.yaml +4 -4
- data/.rubocop.yml +7 -7
- data/.rubocop_todo.yml +88 -0
- data/CHANGELOG.md +29 -1
- data/README.md +1339 -236
- data/RUBY_WEEKLY_LAUNCH_POST.md +200 -0
- data/docs/RAILS_INTEGRATION_IMPLEMENTATION.md +209 -0
- data/docs/SINATRA_EXTENSION.md +399 -348
- data/docs/STRICT_VALIDATION.md +229 -0
- data/docs/VALIDATION_IMPROVEMENTS.md +218 -0
- data/docs/adr/0001-base-class-strategy.md +33 -0
- data/docs/adr/0002-type-shortcut-and-type-system.md +30 -0
- data/docs/adr/0003-openapi-source-of-truth.md +32 -0
- data/docs/adr/0004-client-generation-typescript-first.md +34 -0
- data/docs/adr/0005-auth-architecture.md +32 -0
- data/docs/adr/0006-observability-defaults.md +30 -0
- data/docs/adr/0007-ai-scope-and-boundaries.md +30 -0
- data/docs/adr/README.md +46 -0
- data/docs/adr/template.md +24 -0
- data/docs/ai-integration-plan.md +112 -0
- data/docs/auto-derivation.md +505 -92
- data/docs/blueprint.md +92 -4
- data/docs/endpoint-definition.md +536 -129
- data/docs/implementation-status.md +1 -1
- data/docs/n8n-integration.md +212 -0
- data/docs/observability.md +810 -500
- data/docs/using-mcp.md +93 -0
- data/examples/ai/knowledge_base_rag.rb +83 -0
- data/examples/ai/user_management_mcp.rb +92 -0
- data/examples/ai/user_validation_llm.rb +187 -0
- data/examples/auto_derivation_ruby_friendly.rb +44 -113
- data/examples/cli/user_api_endpoints.rb +63 -36
- data/examples/demo_api.rb +57 -18
- data/examples/enterprise_extension_demo.rb +13 -13
- data/examples/enterprise_rapitapir_api.rb +81 -93
- data/examples/nocodb/nocodb_scaffold/Gemfile +22 -0
- data/examples/nocodb/nocodb_scaffold/README.md +10 -0
- data/examples/nocodb/nocodb_scaffold/Rakefile +7 -0
- data/examples/nocodb/nocodb_scaffold/app/api/app.rb +1139 -0
- data/examples/nocodb/nocodb_scaffold/app/models/email_template.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/faq.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/feature.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/idea.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/itinerary_day.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/route.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/subscriber.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/tour.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models/webhook.rb +6 -0
- data/examples/nocodb/nocodb_scaffold/app/models_loader.rb +3 -0
- data/examples/nocodb/nocodb_scaffold/config/database.yml +11 -0
- data/examples/nocodb/nocodb_scaffold/config.ru +9 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152012_create_features.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152013_create_tours.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152014_create_routes.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152015_create_itinerary_days.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152016_create_subscribers.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152017_create_email_templates.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152018_create_faqs.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152019_create_webhooks.rb +10 -0
- data/examples/nocodb/nocodb_scaffold/db/migrate/20250808152020_create_ideas.rb +10 -0
- data/examples/nocodb/swagger.json +4378 -0
- data/examples/production_ready_example.rb +78 -58
- data/examples/rails/RAILS_8_GUIDE.md +165 -0
- data/examples/rails/RAILS_LOADING_FIX.rb +35 -0
- data/examples/rails/README.md +497 -0
- data/examples/rails/comprehensive_test.rb +91 -0
- data/examples/rails/config/routes.rb +48 -0
- data/examples/rails/debug_controller.rb +63 -0
- data/examples/rails/detailed_test.rb +46 -0
- data/examples/rails/enhanced_users_controller.rb +278 -0
- data/examples/rails/final_server_test.rb +50 -0
- data/examples/rails/hello_world_app.rb +116 -0
- data/examples/rails/hello_world_controller.rb +186 -0
- data/examples/rails/hello_world_routes.rb +28 -0
- data/examples/rails/rails8_minimal_demo.rb +132 -0
- data/examples/rails/rails8_simple_demo.rb +140 -0
- data/examples/rails/rails8_working_demo.rb +255 -0
- data/examples/rails/real_world_blog_api.rb +510 -0
- data/examples/rails/server_test.rb +46 -0
- data/examples/rails/test_direct_processing.rb +41 -0
- data/examples/rails/test_hello_world.rb +80 -0
- data/examples/rails/test_rails_integration.rb +54 -0
- data/examples/rails/traditional_app/Gemfile +37 -0
- data/examples/rails/traditional_app/README.md +265 -0
- data/examples/rails/traditional_app/app/controllers/api/v1/posts_controller.rb +254 -0
- data/examples/rails/traditional_app/app/controllers/api/v1/users_controller.rb +220 -0
- data/examples/rails/traditional_app/app/controllers/application_controller.rb +86 -0
- data/examples/rails/traditional_app/app/controllers/application_controller_simplified.rb +87 -0
- data/examples/rails/traditional_app/app/controllers/documentation_controller.rb +149 -0
- data/examples/rails/traditional_app/app/controllers/health_controller.rb +42 -0
- data/examples/rails/traditional_app/config/routes.rb +25 -0
- data/examples/rails/traditional_app/config/routes_best_practice.rb +25 -0
- data/examples/rails/traditional_app/config/routes_simplified.rb +36 -0
- data/examples/rails/traditional_app_runnable.rb +406 -0
- data/examples/rails/users_controller.rb +4 -1
- data/examples/serverless/Gemfile +43 -0
- data/examples/serverless/QUICKSTART.md +331 -0
- data/examples/serverless/README.md +520 -0
- data/examples/serverless/aws_lambda_example.rb +307 -0
- data/examples/serverless/aws_sam_template.yaml +215 -0
- data/examples/serverless/azure_functions_example.rb +407 -0
- data/examples/serverless/deploy.rb +204 -0
- data/examples/serverless/gcp_cloud_functions_example.rb +367 -0
- data/examples/serverless/gcp_function.yaml +23 -0
- data/examples/serverless/host.json +24 -0
- data/examples/serverless/package.json +32 -0
- data/examples/serverless/spec/aws_lambda_spec.rb +196 -0
- data/examples/serverless/spec/spec_helper.rb +89 -0
- data/examples/serverless/vercel.json +31 -0
- data/examples/serverless/vercel_example.rb +404 -0
- data/examples/simple_demo_api.rb +40 -7
- data/examples/strict_validation_examples.rb +104 -0
- data/examples/user_api.rb +130 -132
- data/examples/validation_error_examples.rb +173 -0
- data/lib/rapitapir/ai/llm_instruction.rb +456 -0
- data/lib/rapitapir/ai/mcp.rb +134 -0
- data/lib/rapitapir/ai/rag.rb +287 -0
- data/lib/rapitapir/ai/rag_middleware.rb +147 -0
- data/lib/rapitapir/auth/oauth2.rb +44 -58
- data/lib/rapitapir/cli/command.rb +392 -6
- data/lib/rapitapir/cli/mcp_export.rb +18 -0
- data/lib/rapitapir/cli/scaffold_generator.rb +639 -0
- data/lib/rapitapir/cli/validator.rb +3 -7
- data/lib/rapitapir/core/endpoint.rb +59 -6
- data/lib/rapitapir/core/enhanced_endpoint.rb +3 -7
- data/lib/rapitapir/dsl/enhanced_structures.rb +1 -1
- data/lib/rapitapir/dsl/fluent_endpoint_builder.rb +53 -0
- data/lib/rapitapir/endpoint_registry.rb +47 -0
- data/lib/rapitapir/observability/health_check.rb +4 -4
- data/lib/rapitapir/observability/logging.rb +10 -10
- data/lib/rapitapir/openapi/schema_generator.rb +46 -2
- data/lib/rapitapir/schema.rb +2 -2
- data/lib/rapitapir/server/enhanced_rack_adapter.rb +11 -8
- data/lib/rapitapir/server/middleware.rb +2 -2
- data/lib/rapitapir/server/rack_adapter.rb +1 -3
- data/lib/rapitapir/server/rails/configuration.rb +77 -0
- data/lib/rapitapir/server/rails/controller_base.rb +185 -0
- data/lib/rapitapir/server/rails/documentation_helpers.rb +76 -0
- data/lib/rapitapir/server/rails/resource_builder.rb +181 -0
- data/lib/rapitapir/server/rails/routes.rb +114 -0
- data/lib/rapitapir/server/rails_adapter.rb +10 -3
- data/lib/rapitapir/server/rails_adapter_class.rb +1 -3
- data/lib/rapitapir/server/rails_controller.rb +1 -3
- data/lib/rapitapir/server/rails_integration.rb +67 -0
- data/lib/rapitapir/server/rails_response_handler.rb +16 -3
- data/lib/rapitapir/server/sinatra_adapter.rb +29 -5
- data/lib/rapitapir/server/sinatra_integration.rb +4 -4
- data/lib/rapitapir/sinatra/extension.rb +2 -2
- data/lib/rapitapir/sinatra/oauth2_helpers.rb +34 -40
- data/lib/rapitapir/types/array.rb +4 -0
- data/lib/rapitapir/types/auto_derivation.rb +4 -20
- data/lib/rapitapir/types/datetime.rb +1 -3
- data/lib/rapitapir/types/float.rb +2 -6
- data/lib/rapitapir/types/hash.rb +40 -2
- data/lib/rapitapir/types/integer.rb +4 -12
- data/lib/rapitapir/types/object.rb +6 -2
- data/lib/rapitapir/types.rb +6 -2
- data/lib/rapitapir/version.rb +1 -1
- data/lib/rapitapir.rb +5 -3
- data/rapitapir.gemspec +3 -2
- metadata +142 -8
data/docs/adr/README.md
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Architectural Decision Records (ADRs)
|
|
2
|
+
|
|
3
|
+
This directory contains Architecture Decision Records (ADRs) that document significant architectural decisions made throughout the RapiTapir project.
|
|
4
|
+
|
|
5
|
+
## Purpose
|
|
6
|
+
|
|
7
|
+
- Maintain a clear history of architectural choices and their rationale.
|
|
8
|
+
- Provide context and rationale for future maintainers and contributors.
|
|
9
|
+
|
|
10
|
+
## ADR Structure
|
|
11
|
+
|
|
12
|
+
Each ADR is a Markdown file with a sequential identifier and a descriptive title:
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
NNNN-short-title.md
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Inside, ADRs follow this structure:
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
# ADR NNNN: Short Title
|
|
22
|
+
|
|
23
|
+
Date: YYYY-MM-DD
|
|
24
|
+
|
|
25
|
+
## Status
|
|
26
|
+
|
|
27
|
+
Proposed | Accepted | Deprecated
|
|
28
|
+
|
|
29
|
+
## Context
|
|
30
|
+
|
|
31
|
+
Describe the context and forces leading to this decision.
|
|
32
|
+
|
|
33
|
+
## Decision
|
|
34
|
+
|
|
35
|
+
Describe the decision and its rationale.
|
|
36
|
+
|
|
37
|
+
## Consequences
|
|
38
|
+
|
|
39
|
+
Describe the resulting consequences, trade-offs, and impacts.
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Creating a New ADR
|
|
43
|
+
|
|
44
|
+
1. Copy `template.md` and rename to the next sequence number, e.g., `0002-add-auth-cache.md`.
|
|
45
|
+
2. Fill in date, status, context, decision, and consequences.
|
|
46
|
+
3. Commit the new ADR file to the repository.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# ADR-NNNN: Title
|
|
2
|
+
|
|
3
|
+
Date: YYYY-MM-DD
|
|
4
|
+
Status: Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
Describe the background and forces leading to this decision.
|
|
9
|
+
|
|
10
|
+
## Decision
|
|
11
|
+
|
|
12
|
+
Record the decision made, with enough detail to be unambiguous.
|
|
13
|
+
|
|
14
|
+
## Consequences
|
|
15
|
+
|
|
16
|
+
List positive, negative, and neutral consequences. Consider security, performance, DX, and maintenance.
|
|
17
|
+
|
|
18
|
+
## Alternatives considered
|
|
19
|
+
|
|
20
|
+
Briefly list alternatives and why they were not chosen.
|
|
21
|
+
|
|
22
|
+
## Follow-ups
|
|
23
|
+
|
|
24
|
+
List tasks, docs, or changes required to uphold this decision.
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# RapiTapir AI Integration: Full Implementation Plan
|
|
2
|
+
|
|
3
|
+
## 🧠 Vision
|
|
4
|
+
|
|
5
|
+
RapiTapir aims to become the first Ruby API framework with native support for AI-driven workflows, agent orchestration, and LLM-powered developer experience. This plan details the steps to integrate Model Context Protocol (MCP), Retrieval-Augmented Generation (RAG), and LLM/agent orchestration into the core and ecosystem.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Phase A: Core AI Integration
|
|
10
|
+
|
|
11
|
+
### 1. Model Context Protocol (MCP) Support
|
|
12
|
+
- Add endpoint(s) to expose API schemas, example requests/responses, and documentation in MCP-compatible JSON format.
|
|
13
|
+
- Implement a DSL helper (`.mcp_export`) to mark endpoints as context providers for LLMs/agents.
|
|
14
|
+
- CLI: `rapitapir export mcp` to generate MCP context files for agent toolchains.
|
|
15
|
+
- Documentation: Add a section on “Using RapiTapir APIs as LLM Tools (MCP)”.
|
|
16
|
+
|
|
17
|
+
### 2. Retrieval-Augmented Generation (RAG) Pipelines
|
|
18
|
+
- Extend the endpoint DSL with `.rag_inference(llm:, retrieval:, context_fields:)`.
|
|
19
|
+
- Provide built-in RAG pipeline support:
|
|
20
|
+
- Accept user query, retrieve relevant data (DB/API), pass to LLM, return result.
|
|
21
|
+
- Support for OpenAI, local LLMs, and pluggable retrieval backends.
|
|
22
|
+
- Example endpoint generator for RAG:
|
|
23
|
+
```ruby
|
|
24
|
+
endpoint = RapiTapir.post("/ask")
|
|
25
|
+
.in(json_body(:question => :string))
|
|
26
|
+
.rag_inference(llm: :openai, retrieval: :postgres, context_fields: [:user_id])
|
|
27
|
+
.out(json_body(:answer => :string))
|
|
28
|
+
```
|
|
29
|
+
- Add test coverage for RAG endpoints (mock LLM/retrieval).
|
|
30
|
+
|
|
31
|
+
### 3. LLM Instruction/Prompt Generation
|
|
32
|
+
- Add `.llm_instruction(purpose:, fields:)` DSL extension to annotate endpoints with prompt templates or instructions.
|
|
33
|
+
- Auto-generate OpenAPI-based prompts for LLM tool-use (e.g., for OpenAI function calling, LangChain).
|
|
34
|
+
- CLI: `rapitapir generate llm-prompts` to export prompts for all endpoints.
|
|
35
|
+
- Documentation: “How to use RapiTapir endpoints as LLM tools”.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Phase B: Agent & Tooling Ecosystem
|
|
40
|
+
|
|
41
|
+
### 4. Agent Tool Registration & Orchestration
|
|
42
|
+
- Auto-generate OpenAPI/JSON Schema for agent tool registration (OpenAI, LangChain, etc.).
|
|
43
|
+
- Add endpoints for agent-to-agent communication (e.g., `/agent/invoke`, `/agent/context`).
|
|
44
|
+
- Provide a Ruby module for registering RapiTapir endpoints as agent tools (with function signatures, descriptions, and examples).
|
|
45
|
+
- CLI: `rapitapir agent export-tools` to generate tool schemas for agent frameworks.
|
|
46
|
+
|
|
47
|
+
### 5. Agent-Driven Workflows
|
|
48
|
+
- Enable endpoints to accept/return LLM-generated instructions, plans, or summaries.
|
|
49
|
+
- Add support for “chain-of-thought” and multi-step agent workflows (e.g., via a `.agent_workflow` DSL helper).
|
|
50
|
+
- Example:
|
|
51
|
+
```ruby
|
|
52
|
+
endpoint = RapiTapir.post("/plan")
|
|
53
|
+
.in(json_body(:goal => :string))
|
|
54
|
+
.agent_workflow(steps: [:search, :summarize, :act])
|
|
55
|
+
.out(json_body(:plan => :string))
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Phase C: Developer Experience & Documentation
|
|
61
|
+
|
|
62
|
+
### 6. AI-Enhanced Documentation & Testing
|
|
63
|
+
- Integrate LLMs to auto-generate endpoint summaries, descriptions, and usage examples.
|
|
64
|
+
- Add CLI commands:
|
|
65
|
+
- `rapitapir ai describe-endpoints` (auto-generate docs)
|
|
66
|
+
- `rapitapir ai suggest-tests` (auto-generate RSpec tests)
|
|
67
|
+
- Web UI: “Describe this endpoint” and “Suggest test cases” buttons in generated docs.
|
|
68
|
+
|
|
69
|
+
### 7. AI-Driven Endpoint Design
|
|
70
|
+
- CLI: `rapitapir ai generate-endpoint "A GET /books endpoint that returns a list of books with title and author"`
|
|
71
|
+
- Uses LLM to generate endpoint DSL, schema, and docs.
|
|
72
|
+
- Web UI: Interactive wizard for natural language to endpoint DSL/code.
|
|
73
|
+
|
|
74
|
+
### 8. RAG/LLM Example Gallery
|
|
75
|
+
- Add example endpoints and use cases for RAG, MCP, and agent orchestration in `examples/ai/`.
|
|
76
|
+
- Documentation: “AI Patterns with RapiTapir” guide.
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Phase D: Ecosystem & Community
|
|
81
|
+
|
|
82
|
+
### 9. Plugin & Extension System
|
|
83
|
+
- Provide hooks for custom LLMs, retrieval backends, and agent frameworks.
|
|
84
|
+
- Document how to build and share AI plugins/extensions.
|
|
85
|
+
|
|
86
|
+
### 10. Community & Feedback
|
|
87
|
+
- Launch a feedback program for AI features.
|
|
88
|
+
- Collect and publish community-contributed AI endpoint patterns.
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## Milestones & Timeline (Suggested)
|
|
93
|
+
|
|
94
|
+
| Phase | Feature Area | Timeline |
|
|
95
|
+
|-------|----------------------------|------------|
|
|
96
|
+
| A | Core AI Integration | 4 weeks |
|
|
97
|
+
| B | Agent & Tooling Ecosystem | 3 weeks |
|
|
98
|
+
| C | Dev Experience & Docs | 3 weeks |
|
|
99
|
+
| D | Ecosystem & Community | Ongoing |
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## Success Metrics
|
|
104
|
+
|
|
105
|
+
- MCP/RAG endpoints pass integration tests with LLM/agent frameworks.
|
|
106
|
+
- CLI and docs support AI-driven workflows.
|
|
107
|
+
- Community adoption of AI features and plugins.
|
|
108
|
+
- RapiTapir endpoints can be used as tools by LLM agents with minimal friction.
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
RapiTapir will become a first-class Ruby API platform for AI-native and agent-driven applications, while maintaining its core strengths in type safety, developer experience, and extensibility.
|