brainy/integrations/google-sheets/README.md

Brainy Google Sheets Add-on

Two-way sync between Brainy and Google Sheets.

Quick Setup

1. Open your Google Sheet
2. Go to Extensions → Apps Script
3. Delete any existing code
4. Copy and paste Code.gs into the editor
5. Create a new HTML file called Sidebar.html and paste the content
6. Go to Project Settings (gear icon) → Script properties
7. Add property: BRAINY_URL = your Brainy server URL (e.g., http://localhost:3000)
8. Save and refresh your spreadsheet

Custom Functions

Use these directly in cells:

=BRAINY_QUERY(query, limit)

Query entities using semantic search or type filter.

=BRAINY_QUERY("machine learning", 10)
=BRAINY_QUERY("type:person", 100)

=BRAINY_GET(id)

Get a single entity by ID.

=BRAINY_GET("entity-uuid-here")

=BRAINY_SIMILAR(text, limit)

Find semantically similar entities.

=BRAINY_SIMILAR("artificial intelligence research", 5)

=BRAINY_RELATIONS(entityId, direction)

Get relationships for an entity.

=BRAINY_RELATIONS("entity-id", "from")
=BRAINY_RELATIONS("entity-id", "to")
=BRAINY_RELATIONS("entity-id", "both")

=BRAINY_TYPES()

List all available entity types.

=BRAINY_RELATION_TYPES()

List all available relationship types.

Sidebar

Open via Brainy → Open Sidebar menu:

• Search: Query entities and insert results into the sheet
• Add: Create new entities with a form
• Sync: Sync selected range to Brainy (add or update)

Authentication

If your Brainy server requires authentication:

1. Go to Project Settings → Script properties
2. Add property: BRAINY_API_KEY = your API key

Real-Time Sync

For real-time updates, enable SSE in your Brainy server:

brain.augmentations.register(new SSEIntegration())

The sidebar will automatically show changes as they happen.

Troubleshooting

"Brainy URL not configured"

Add the BRAINY_URL script property in Apps Script settings.

"Connection failed"

• Check that your Brainy server is running
• Ensure the URL is correct (include port if needed)
• For local development, use ngrok or similar to expose localhost

Custom functions not appearing

• Refresh the spreadsheet
• Wait a few seconds (Apps Script can be slow to register)
• Check the Apps Script execution log for errors

Server Setup

The simplest way to enable all integrations:

import { Brainy } from '@soulcraft/brainy'

const brain = new Brainy({ integrations: true })
await brain.init()

console.log(brain.hub.endpoints)
// { odata: '/odata', sheets: '/sheets', sse: '/events', webhooks: '/webhooks' }

With Express:

import express from 'express'
import { Brainy } from '@soulcraft/brainy'

const app = express()
const brain = new Brainy({ integrations: true })
await brain.init()

// Route all integration requests
app.use(express.json())
app.all(['/odata/*', '/sheets/*', '/events/*'], async (req, res) => {
  const response = await brain.hub.handleRequest({
    method: req.method,
    path: req.path,
    query: req.query,
    headers: req.headers,
    body: req.body
  })

  if (response.isSSE) {
    // Handle SSE stream
    res.setHeader('Content-Type', 'text/event-stream')
    // ... streaming logic
  } else {
    res.status(response.status).set(response.headers).json(response.body)
  }
})

app.listen(3000)