npm - @electric-ax/agents - Versions diffs - 0.2.1 → 0.2.2 - Mend

@electric-ax/agents 0.2.1 → 0.2.2

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.

Files changed (49) hide show

package/dist/entrypoint.js +5 -3
package/dist/index.cjs +5 -3
package/dist/index.js +5 -3
package/docs/entities/agents/horton.md +89 -0
package/docs/entities/agents/worker.md +102 -0
package/docs/entities/patterns/blackboard.md +111 -0
package/docs/entities/patterns/dispatcher.md +77 -0
package/docs/entities/patterns/manager-worker.md +127 -0
package/docs/entities/patterns/map-reduce.md +81 -0
package/docs/entities/patterns/pipeline.md +101 -0
package/docs/entities/patterns/reactive-observers.md +125 -0
package/docs/examples/mega-draw.md +106 -0
package/docs/examples/playground.md +46 -0
package/docs/index.md +208 -0
package/docs/quickstart.md +201 -0
package/docs/reference/agent-config.md +82 -0
package/docs/reference/agent-tool.md +58 -0
package/docs/reference/built-in-collections.md +334 -0
package/docs/reference/cli.md +238 -0
package/docs/reference/entity-definition.md +57 -0
package/docs/reference/entity-handle.md +63 -0
package/docs/reference/entity-registry.md +73 -0
package/docs/reference/handler-context.md +108 -0
package/docs/reference/runtime-handler.md +136 -0
package/docs/reference/shared-state-handle.md +74 -0
package/docs/reference/state-collection-proxy.md +41 -0
package/docs/reference/wake-event.md +132 -0
package/docs/usage/app-setup.md +165 -0
package/docs/usage/clients-and-react.md +191 -0
package/docs/usage/configuring-the-agent.md +136 -0
package/docs/usage/context-composition.md +204 -0
package/docs/usage/defining-entities.md +181 -0
package/docs/usage/defining-tools.md +229 -0
package/docs/usage/embedded-builtins.md +180 -0
package/docs/usage/managing-state.md +93 -0
package/docs/usage/overview.md +284 -0
package/docs/usage/programmatic-runtime-client.md +216 -0
package/docs/usage/shared-state.md +169 -0
package/docs/usage/spawning-and-coordinating.md +165 -0
package/docs/usage/testing.md +76 -0
package/docs/usage/waking-entities.md +148 -0
package/docs/usage/writing-handlers.md +267 -0
package/package.json +2 -1
package/skills/quickstart/scaffold/package.json +16 -3
package/skills/quickstart/scaffold/tsconfig.json +8 -3
package/skills/quickstart/scaffold/vite.config.ts +21 -0
package/skills/quickstart/scaffold-ui/index.html +12 -0
package/skills/quickstart/scaffold-ui/main.tsx +235 -0
package/skills/quickstart.md +244 -334

package/skills/quickstart/scaffold/package.json CHANGED Viewed

@@ -4,14 +4,27 @@
   "type": "module",
   "scripts": {
     "start": "tsx server.ts",
-    "dev": "tsx --watch server.ts"
+    "dev": "tsx --watch server.ts",
+    "dev:server": "tsx --watch server.ts",
+    "dev:ui": "vite",
+    "dev:all": "npm run dev:server & npm run dev:ui"
   },
   "dependencies": {
     "@electric-ax/agents-runtime": "latest",
-    "@sinclair/typebox": "^0.34.49"
+    "@radix-ui/themes": "^3.3.0",
+    "@sinclair/typebox": "^0.34.49",
+    "@tanstack/db": "^0.6.0",
+    "@tanstack/react-db": "^0.1.78",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "streamdown": "^2.5.0"
   },
   "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.2.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vite": "^7.2.4"
   }
 }

package/skills/quickstart/scaffold/tsconfig.json CHANGED Viewed

@@ -3,13 +3,18 @@
     "target": "ES2022",
     "module": "ESNext",
     "moduleResolution": "bundler",
+    "jsx": "react-jsx",
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
     "resolveJsonModule": true,
-    "allowImportingTsExtensions": false,
-    "noEmit": true
+    "isolatedModules": true,
+    "noEmit": true,
+    "paths": {
+      "@tanstack/db": ["./node_modules/@tanstack/db"]
+    }
   },
-  "include": ["**/*.ts"],
+  "include": ["**/*.ts", "**/*.tsx"],
   "exclude": ["node_modules"]
 }

package/skills/quickstart/scaffold/vite.config.ts ADDED Viewed

@@ -0,0 +1,21 @@
+import path from 'node:path'
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+export default defineConfig({
+  root: `ui`,
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@tanstack/db': path.resolve(
+        import.meta.dirname,
+        `node_modules/@tanstack/db`
+      ),
+    },
+  },
+  server: {
+    port: 5175,
+    proxy: { '/api': `http://localhost:3000` },
+  },
+  build: { outDir: `../dist`, emptyOutDir: true },
+})

package/skills/quickstart/scaffold-ui/index.html ADDED Viewed

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Perspectives Analyzer</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

package/skills/quickstart/scaffold-ui/main.tsx ADDED Viewed

@@ -0,0 +1,235 @@
+import { useState, useEffect, useRef } from 'react'
+import { createRoot } from 'react-dom/client'
+import { createAgentsClient, entity } from '@electric-ax/agents-runtime'
+import { useChat } from '@electric-ax/agents-runtime/react'
+import {
+  Theme,
+  Box,
+  Flex,
+  Heading,
+  Text,
+  TextField,
+  Button,
+  Card,
+} from '@radix-ui/themes'
+import { Streamdown } from 'streamdown'
+import '@radix-ui/themes/styles.css'
+import 'streamdown/styles.css'
+import type { EntityStreamDB } from '@electric-ax/agents-runtime'
+const AGENTS_URL = `http://localhost:4437`
+const AGENT_COLORS: Record<string, { bg: string; border: string }> = {
+  analyser: { bg: `var(--blue-3)`, border: `var(--blue-6)` },
+  optimist: { bg: `var(--green-3)`, border: `var(--green-6)` },
+  critic: { bg: `var(--red-3)`, border: `var(--red-6)` },
+}
+function useEntityDb(url: string | null, retryMs = 0) {
+  const [db, setDb] = useState<EntityStreamDB | null>(null)
+  useEffect(() => {
+    if (!url) {
+      setDb(null)
+      return
+    }
+    let cancelled = false
+    let observedDb: EntityStreamDB | null = null
+    let timer: ReturnType<typeof setTimeout> | null = null
+    const connect = () => {
+      const client = createAgentsClient({ baseUrl: AGENTS_URL })
+      client.observe(entity(url)).then(
+        (observed) => {
+          observedDb = observed as EntityStreamDB
+          if (cancelled) {
+            observedDb.close()
+            return
+          }
+          setDb(observedDb)
+        },
+        () => {
+          if (!cancelled && retryMs > 0) {
+            timer = setTimeout(connect, retryMs)
+          }
+        }
+      )
+    }
+    connect()
+    return () => {
+      cancelled = true
+      if (timer) clearTimeout(timer)
+      observedDb?.close()
+    }
+  }, [url, retryMs])
+  return db
+}
+interface AgentMessage {
+  agent: string
+  text: string
+  isStreaming: boolean
+}
+function useAgentMessages(
+  url: string | null,
+  agent: string,
+  retryMs = 0
+): AgentMessage[] {
+  const db = useEntityDb(url, retryMs)
+  const chat = useChat(db)
+  return chat.runs.flatMap((r, ri) =>
+    r.texts
+      .filter((t) => t.text.trim().length > 0)
+      .map((t, ti) => ({
+        agent,
+        text: t.text,
+        isStreaming:
+          chat.state === `working` &&
+          ri === chat.runs.length - 1 &&
+          ti === r.texts.length - 1,
+      }))
+  )
+}
+function MessageBubble({ msg }: { msg: AgentMessage }) {
+  const colors = AGENT_COLORS[msg.agent] ?? {
+    bg: `var(--gray-3)`,
+    border: `var(--gray-6)`,
+  }
+  return (
+    <Card
+      size="1"
+      style={{
+        background: colors.bg,
+        borderLeft: `3px solid ${colors.border}`,
+      }}
+    >
+      <Text size="1" weight="bold" style={{ textTransform: `capitalize` }}>
+        {msg.agent}
+      </Text>
+      <Box mt="1" style={{ fontSize: `var(--font-size-2)` }}>
+        <Streamdown isAnimating={msg.isStreaming} controls={false}>
+          {msg.text}
+        </Streamdown>
+      </Box>
+    </Card>
+  )
+}
+function App() {
+  const [question, setQuestion] = useState(``)
+  const [urls, setUrls] = useState<{
+    entityUrl: string
+    optimistUrl: string
+    criticUrl: string
+  } | null>(null)
+  const [loading, setLoading] = useState(false)
+  const bottomRef = useRef<HTMLDivElement>(null)
+  const analyserMessages = useAgentMessages(urls?.entityUrl ?? null, `analyser`)
+  const optimistMessages = useAgentMessages(
+    urls?.optimistUrl ?? null,
+    `optimist`,
+    2000
+  )
+  const criticMessages = useAgentMessages(
+    urls?.criticUrl ?? null,
+    `critic`,
+    2000
+  )
+  const allMessages = [
+    ...analyserMessages,
+    ...optimistMessages,
+    ...criticMessages,
+  ]
+  useEffect(() => {
+    const el = bottomRef.current?.parentElement
+    if (!el) return
+    const observer = new MutationObserver(() => {
+      window.scrollTo({ top: document.body.scrollHeight, behavior: `smooth` })
+    })
+    observer.observe(el, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    })
+    return () => observer.disconnect()
+  }, [urls])
+  const handleAnalyze = async () => {
+    if (!question.trim()) return
+    setLoading(true)
+    try {
+      const res = await fetch(`/api/analyze`, {
+        method: `POST`,
+        headers: { 'Content-Type': `application/json` },
+        body: JSON.stringify({ question }),
+      })
+      const data = (await res.json()) as {
+        entityUrl: string
+        optimistUrl: string
+        criticUrl: string
+      }
+      setUrls(data)
+    } catch (err) {
+      console.error(`Analyze failed:`, err)
+    } finally {
+      setLoading(false)
+    }
+  }
+  return (
+    <Theme appearance="light" accentColor="blue" radius="medium">
+      <style>{`@keyframes blink { 50% { opacity: 0; } }`}</style>
+      <Box maxWidth="700px" mx="auto" p="5">
+        <Heading size="6" mb="1">
+          Perspectives Analyzer
+        </Heading>
+        <Text size="2" color="gray" mb="5" as="p">
+          Ask a question and get two perspectives — an optimist and a critic —
+          then a balanced analysis.
+        </Text>
+        <Flex gap="2" mb="5">
+          <Box flexGrow="1">
+            <TextField.Root
+              size="3"
+              placeholder="Enter a question to analyze..."
+              value={question}
+              onChange={(e) => setQuestion(e.target.value)}
+              onKeyDown={(e) => e.key === `Enter` && handleAnalyze()}
+            />
+          </Box>
+          <Button
+            size="3"
+            onClick={handleAnalyze}
+            disabled={loading || !question.trim()}
+          >
+            {loading ? `Analyzing...` : `Analyze`}
+          </Button>
+        </Flex>
+        <Flex direction="column" gap="3">
+          {urls && allMessages.length === 0 && (
+            <Text color="gray" size="2">
+              Waiting for agents to respond...
+            </Text>
+          )}
+          {allMessages.map((msg, i) => (
+            <MessageBubble key={`${msg.agent}-${i}`} msg={msg} />
+          ))}
+          <div ref={bottomRef} />
+        </Flex>
+      </Box>
+    </Theme>
+  )
+}
+createRoot(document.getElementById(`root`)!).render(<App />)