agentic-astra-catalog 0.0.1

package/README.md

@@ -0,0 +1,154 @@
+# Agentic-Astra Catalog
+
+A Next.js frontend application for viewing and editing tools stored in an Astra DB catalog collection.
+
+## Features
+
+- **Dark/Light Mode**: Toggle between dark and light themes
+- **Tool List**: Browse all tools from the catalog collection
+- **Tool Editor**: Edit tool details including parameters, configuration, and metadata
+- **Server-Side API**: All database interactions happen on the server for security
+- **Real-time Updates**: Connect directly to Astra DB using `@datastax/astra-db-ts`
+
+## Prerequisites
+
+- Node.js 18+ and npm/yarn/pnpm
+- Astra DB credentials (token, endpoint, database name)
+
+## Setup
+
+1. Install dependencies:
+
+```bash
+npm install
+```
+
+2. Configure environment variables:
+
+Create a `.env.local` file in the `frontend/` directory:
+
+```env
+ASTRA_DB_APPLICATION_TOKEN=your_astra_db_token
+ASTRA_DB_API_ENDPOINT=https://your-database-id-your-region.apps.astra.datastax.com
+ASTRA_DB_DB_NAME=your_database_name
+ASTRA_DB_CATALOG_COLLECTION=tool_catalog
+```
+
+**Note**: Next.js automatically loads environment variables from `.env.local` for local development. These variables are only available on the server side, keeping your credentials secure.
+
+## Development
+
+Run the development server:
+
+```bash
+npm run dev
+```
+
+The app will be available at `http://localhost:3000`.
+
+## Building
+
+Build for production:
+
+```bash
+npm run build
+```
+
+Start the production server:
+
+```bash
+npm start
+```
+
+## Usage
+
+### Local Development
+
+1. Set up environment variables (see Setup above)
+2. Run `npm run dev`
+3. Open the app in your browser at `http://localhost:3000`
+
+## Environment Variables
+
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| `ASTRA_DB_APPLICATION_TOKEN` | Yes | Astra DB application token | - |
+| `ASTRA_DB_API_ENDPOINT` | Yes | Astra DB API endpoint URL | - |
+| `ASTRA_DB_DB_NAME` | Yes | Name of the Astra DB database | - |
+| `ASTRA_DB_CATALOG_COLLECTION` | No | Name of the catalog collection | `tool_catalog` |
+
+## Project Structure
+
+```
+frontend/
+├── app/
+│   ├── api/
+│   │   └── tools/
+│   │       └── route.ts        # API route for tools (GET, POST)
+│   ├── globals.css              # Global styles with Tailwind
+│   ├── layout.tsx               # Root layout
+│   └── page.tsx                 # Main page component
+├── components/
+│   ├── ThemeToggle.tsx          # Dark/light mode toggle
+│   ├── ToolList.tsx             # Tool list sidebar
+│   └── ToolEditor.tsx           # Tool editing form
+├── lib/
+│   └── astraClient.ts           # Astra DB client (server-side only)
+├── next.config.js
+├── package.json
+├── tailwind.config.js
+└── tsconfig.json
+```
+
+## Technologies
+
+- **Next.js 14**: React framework with App Router
+- **React 18**: UI framework
+- **TypeScript**: Type safety
+- **Tailwind CSS**: Styling with dark mode support
+- **@datastax/astra-db-ts**: Official Astra DB TypeScript client (server-side only)
+
+## Architecture
+
+This application uses Next.js API routes to handle all database interactions on the server:
+
+- **Client-side**: React components make fetch requests to `/api/tools`
+- **Server-side**: API routes in `app/api/tools/route.ts` handle database operations
+- **Security**: Database credentials are never exposed to the client
+
+## API Endpoints
+
+### GET `/api/tools`
+Fetches all tools from the catalog collection.
+
+**Response:**
+```json
+{
+  "success": true,
+  "tools": [...]
+}
+```
+
+### POST `/api/tools`
+Creates or updates a tool in the catalog collection.
+
+**Request Body:**
+```json
+{
+  "_id": "...",
+  "name": "...",
+  "description": "...",
+  ...
+}
+```
+
+**Response:**
+```json
+{
+  "success": true
+}
+```
+
+## License
+
+Same as the parent project.

package/app/api/db/objects/route.ts

@@ -0,0 +1,44 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getAstraClient } from '@/lib/astraClient';
+
+export async function GET(request: NextRequest) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const type = searchParams.get('type'); // 'keyspaces', 'collections', 'tables'
+    const dbName = searchParams.get('dbName') || undefined;
+
+    const client = getAstraClient();
+    await client.connect();
+
+    let result: string[] = [];
+
+    switch (type) {
+      case 'keyspaces':
+        result = await client.listKeyspaces();
+        break;
+      case 'collections':
+        result = await client.listCollections(dbName);
+        break;
+      case 'tables':
+        result = await client.listTables(dbName);
+        break;
+      default:
+        return NextResponse.json(
+          { success: false, error: 'Invalid type. Must be "keyspaces", "collections", or "tables"' },
+          { status: 400 }
+        );
+    }
+
+    return NextResponse.json({ success: true, objects: result });
+  } catch (error) {
+    console.error('Error listing database objects:', error);
+    return NextResponse.json(
+      {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to list database objects',
+      },
+      { status: 500 }
+    );
+  }
+}
+

package/app/api/tools/attributes/route.ts

@@ -0,0 +1,27 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getAstraClient, extractAttributes, Tool } from '@/lib/astraClient';
+
+export async function POST(request: NextRequest) {
+  try {
+    const tool: Tool = await request.json();
+    const client = getAstraClient();
+    const documents = await client.getSampleDocuments(tool, 5);
+    const attributes = extractAttributes(documents);
+    
+    return NextResponse.json({ 
+      success: true, 
+      attributes,
+      sampleCount: documents.length 
+    });
+  } catch (error) {
+    console.error('Error fetching attributes:', error);
+    return NextResponse.json(
+      { 
+        success: false, 
+        error: error instanceof Error ? error.message : 'Failed to fetch attributes' 
+      },
+      { status: 500 }
+    );
+  }
+}
+

package/app/api/tools/generate/route.ts

@@ -0,0 +1,146 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getAstraClient, extractAttributes } from '@/lib/astraClient';
+import OpenAI from 'openai';
+
+export async function POST(request: NextRequest) {
+  try {
+    const { dataType, name, dbName } = await request.json();
+
+    if (!name || !dataType) {
+      return NextResponse.json(
+        { success: false, error: 'Collection/table name and data type are required' },
+        { status: 400 }
+      );
+    }
+
+    // Get sample documents
+    const client = getAstraClient();
+    await client.connect();
+    const tool: any = {
+      [dataType === 'collection' ? 'collection_name' : 'table_name']: name,
+      db_name: dbName || process.env.ASTRA_DB_DB_NAME || '',
+    };
+
+    const documents = await client.getSampleDocuments(tool, 10);
+    const attributes = extractAttributes(documents);
+
+    if (documents.length === 0) {
+      return NextResponse.json(
+        { success: false, error: `No documents found in ${dataType} "${name}"` },
+        { status: 404 }
+      );
+    }
+
+    // Prepare sample data for OpenAI
+    const sampleData = documents.slice(0, 5).map((doc: any) => {
+      const { _id, ...rest } = doc;
+      return rest;
+    });
+
+    // Initialize OpenAI client
+    const openai = new OpenAI({
+      apiKey: process.env.OPENAI_API_KEY,
+    });
+
+    // Create prompt for OpenAI
+    const prompt = `You are an expert at creating database query tool specifications. Based on the following ${dataType} structure and sample data, generate a comprehensive tool specification in JSON format.
+
+${dataType} Name: ${name}
+Available Attributes: ${attributes.join(', ')}
+
+Sample Documents (first 5):
+${JSON.stringify(sampleData, null, 2)}
+
+Generate a tool specification JSON with the following structure:
+{
+  "name": "descriptive_tool_name",
+  "description": "Clear description of what this tool does",
+  "type": "tool",
+  "method": "find",
+  "${dataType === 'collection' ? 'collection_name' : 'table_name'}": "${name}",
+  "db_name": "${dbName || 'default'}",
+  "parameters": [
+    {
+      "param": "parameter_name",
+      "paramMode": "tool_param",
+      "type": "string|number|boolean|text|timestamp|float|vector",
+      "description": "Parameter description",
+      "attribute": "attribute_name_from_list",
+      "operator": "$eq|$gt|$gte|$lt|$lte|$in|$ne",
+      "required": true|false
+    }
+  ],
+  "projection": {
+    "attribute_name": 1
+  },
+  "limit": 10,
+  "enabled": true,
+  "tags": ["relevant", "tags"]
+}
+
+Return ONLY valid JSON, no markdown, no explanations.`;
+
+    // Call OpenAI
+    const completion = await openai.chat.completions.create({
+      model: process.env.OPENAI_MODEL || 'gpt-4o-mini',
+      messages: [
+        {
+          role: 'system',
+          content: 'You are an expert at creating database query tool specifications. Always return valid JSON only, no markdown formatting.',
+        },
+        {
+          role: 'user',
+          content: prompt,
+        },
+      ],
+      temperature: 0.3,
+      response_format: { type: 'json_object' },
+    });
+
+    const responseContent = completion.choices[0]?.message?.content;
+    if (!responseContent) {
+      throw new Error('No response from OpenAI');
+    }
+
+    // Parse the JSON response
+    let toolSpec;
+    try {
+      toolSpec = JSON.parse(responseContent);
+    } catch (parseError) {
+      // Try to extract JSON from markdown if present
+      const jsonMatch = responseContent.match(/```json\s*([\s\S]*?)\s*```/) || 
+                       responseContent.match(/```\s*([\s\S]*?)\s*```/);
+      if (jsonMatch) {
+        toolSpec = JSON.parse(jsonMatch[1]);
+      } else {
+        throw new Error('Failed to parse OpenAI response as JSON');
+      }
+    }
+
+    // Ensure required fields are set
+    toolSpec[dataType === 'collection' ? 'collection_name' : 'table_name'] = name;
+    toolSpec.db_name = dbName || process.env.ASTRA_DB_DB_NAME || '';
+    toolSpec.type = 'tool';
+    toolSpec.enabled = toolSpec.enabled !== false;
+
+    // Normalize parameters
+    if (toolSpec.parameters && Array.isArray(toolSpec.parameters)) {
+      toolSpec.parameters = toolSpec.parameters.map((param: any) => ({
+        ...param,
+        paramMode: param.paramMode || 'tool_param',
+      }));
+    }
+
+    return NextResponse.json({ success: true, tool: toolSpec });
+  } catch (error) {
+    console.error('Error generating tool:', error);
+    return NextResponse.json(
+      {
+        success: false,
+        error: error instanceof Error ? error.message : 'Failed to generate tool specification',
+      },
+      { status: 500 }
+    );
+  }
+}
+

package/app/api/tools/route.ts

@@ -0,0 +1,38 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getAstraClient } from '@/lib/astraClient';
+
+export async function GET() {
+  try {
+    const client = getAstraClient();
+    const tools = await client.getTools();
+    return NextResponse.json({ success: true, tools });
+  } catch (error) {
+    console.error('Error fetching tools:', error);
+    return NextResponse.json(
+      { 
+        success: false, 
+        error: error instanceof Error ? error.message : 'Failed to fetch tools' 
+      },
+      { status: 500 }
+    );
+  }
+}
+
+export async function POST(request: NextRequest) {
+  try {
+    const tool = await request.json();
+    const client = getAstraClient();
+    await client.updateTool(tool);
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.error('Error updating tool:', error);
+    return NextResponse.json(
+      { 
+        success: false, 
+        error: error instanceof Error ? error.message : 'Failed to update tool' 
+      },
+      { status: 500 }
+    );
+  }
+}
+

package/app/globals.css

@@ -0,0 +1,4 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+

package/app/layout.tsx

@@ -0,0 +1,20 @@
+import type { Metadata } from 'next'
+import './globals.css'
+
+export const metadata: Metadata = {
+  title: 'Agentic Astra Catalog',
+  description: 'Manage your Astra DB tool catalog',
+}
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}
+

package/app/page.tsx

@@ -0,0 +1,119 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import ThemeToggle from '@/components/ThemeToggle';
+import ToolList from '@/components/ToolList';
+import ToolEditor from '@/components/ToolEditor';
+import { Tool } from '@/lib/astraClient';
+
+export default function Home() {
+  const [tools, setTools] = useState<Tool[]>([]);
+  const [selectedTool, setSelectedTool] = useState<Tool | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    loadTools();
+  }, []);
+
+  const loadTools = async (showLoading = true) => {
+    try {
+      if (showLoading) {
+        setLoading(true);
+      }
+      setError(null);
+      const response = await fetch('/api/tools');
+      const data = await response.json();
+      
+      if (!response.ok || !data.success) {
+        throw new Error(data.error || 'Failed to load tools');
+      }
+      
+      const loadedTools = data.tools || [];
+      // Sort tools alphabetically by name (case-insensitive)
+      const sortedTools = loadedTools.sort((a: Tool, b: Tool) => {
+        const nameA = (a.name || '').toLowerCase();
+        const nameB = (b.name || '').toLowerCase();
+        return nameA.localeCompare(nameB);
+      });
+      setTools(sortedTools);
+      
+      // Update selected tool if it still exists
+      if (selectedTool) {
+        const updatedTool = sortedTools.find(
+          (t: Tool) => (t._id && t._id === selectedTool._id) || t.name === selectedTool.name
+        );
+        if (updatedTool) {
+          setSelectedTool(updatedTool);
+        }
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to load tools');
+      console.error('Error loading tools:', err);
+    } finally {
+      if (showLoading) {
+        setLoading(false);
+      }
+    }
+  };
+
+  const handleToolSave = async (savedTool: Tool) => {
+    // Refresh the tools list without showing loading screen
+    await loadTools(false);
+    // Update selected tool with the saved data
+    setSelectedTool(savedTool);
+  };
+
+  if (loading) {
+    return (
+      <div className="h-screen flex items-center justify-center bg-white dark:bg-gray-800">
+        <div className="text-center">
+          <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-600 mx-auto mb-4"></div>
+          <p className="text-gray-600 dark:text-gray-400">Loading tools...</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="h-screen flex items-center justify-center bg-white dark:bg-gray-800">
+        <div className="text-center max-w-md mx-auto p-6">
+          <div className="text-red-600 dark:text-red-400 mb-4">
+            <svg className="w-16 h-16 mx-auto" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+            </svg>
+          </div>
+          <h2 className="text-xl font-semibold text-gray-800 dark:text-gray-200 mb-2">Error Loading Tools</h2>
+          <p className="text-gray-600 dark:text-gray-400 mb-4">{error}</p>
+          <button
+            onClick={() => loadTools()}
+            className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 transition-colors"
+          >
+            Retry
+          </button>
+        </div>
+      </div>
+    );
+  }
+
+  const handleNewTool = () => {
+    setSelectedTool({
+      type: 'tool',
+      name: '',
+      collection_name: '',
+      table_name: '',
+      db_name: '',
+      enabled: true,
+    } as Tool);
+  };
+
+  return (
+    <div className="h-screen flex bg-white dark:bg-gray-800">
+      <ThemeToggle />
+      <ToolList tools={tools} selectedTool={selectedTool} onSelectTool={setSelectedTool} onNewTool={handleNewTool} />
+      <ToolEditor tool={selectedTool} onSave={handleToolSave} />
+    </div>
+  );
+}
+

package/bin/agentic-astra-catalog.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for agentic-astra-catalog
+ * This script runs the Next.js development server
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// Get the directory where the package is installed
+const packageDir = path.resolve(__dirname, '..');
+
+// Check if node_modules exists, if not, install dependencies
+const nodeModulesPath = path.join(packageDir, 'node_modules');
+const nextPath = path.join(nodeModulesPath, '.bin', 'next');
+
+function runNextDev() {
+  const port = process.env.PORT || '3000';
+  const hostname = process.env.HOSTNAME || 'localhost';
+  
+  console.log(`🚀 Starting Agentic Astra Catalog...`);
+  console.log(`📦 Package directory: ${packageDir}`);
+  console.log(`🌐 Server will be available at http://${hostname}:${port}`);
+  console.log(`\n💡 Make sure to set up your .env.local file with Astra DB credentials!\n`);
+
+  // Spawn next dev process
+  const nextProcess = spawn('npx', ['next', 'dev', '-p', port, '-H', hostname], {
+    cwd: packageDir,
+    stdio: 'inherit',
+    shell: true
+  });
+
+  nextProcess.on('error', (error) => {
+    console.error('❌ Error starting server:', error.message);
+    process.exit(1);
+  });
+
+  nextProcess.on('exit', (code) => {
+    process.exit(code || 0);
+  });
+
+  // Handle graceful shutdown
+  process.on('SIGINT', () => {
+    console.log('\n\n👋 Shutting down...');
+    nextProcess.kill();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    nextProcess.kill();
+    process.exit(0);
+  });
+}
+
+// Check if dependencies are installed
+if (!fs.existsSync(nodeModulesPath) || !fs.existsSync(nextPath)) {
+  console.log('📦 Installing dependencies...');
+  const installProcess = spawn('npm', ['install'], {
+    cwd: packageDir,
+    stdio: 'inherit',
+    shell: true
+  });
+
+  installProcess.on('exit', (code) => {
+    if (code === 0) {
+      runNextDev();
+    } else {
+      console.error('❌ Failed to install dependencies');
+      process.exit(1);
+    }
+  });
+} else {
+  runNextDev();
+}
+

package/components/ThemeToggle.tsx

@@ -0,0 +1,49 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+export default function ThemeToggle() {
+  const [isDark, setIsDark] = useState(() => {
+    if (typeof window !== 'undefined') {
+      const stored = localStorage.getItem('theme');
+      if (stored) {
+        return stored === 'dark';
+      }
+      return window.matchMedia('(prefers-color-scheme: dark)').matches;
+    }
+    return false;
+  });
+
+  useEffect(() => {
+    if (isDark) {
+      document.documentElement.classList.add('dark');
+      localStorage.setItem('theme', 'dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+      localStorage.setItem('theme', 'light');
+    }
+  }, [isDark]);
+
+  const toggleTheme = () => {
+    setIsDark(!isDark);
+  };
+
+  return (
+    <button
+      onClick={toggleTheme}
+      className="fixed top-4 right-4 p-2 rounded-lg bg-gray-200 dark:bg-gray-800 text-gray-800 dark:text-gray-200 hover:bg-gray-300 dark:hover:bg-gray-700 transition-colors"
+      aria-label="Toggle theme"
+    >
+      {isDark ? (
+        <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z" />
+        </svg>
+      ) : (
+        <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z" />
+        </svg>
+      )}
+    </button>
+  );
+}
+