@elqnt/agents 3.0.0 → 3.0.1

package/README.md

@@ -0,0 +1,240 @@
+# @elqnt/agents
+
+Agent management SDK for the Eloquent platform. Provides TypeScript types, browser and server APIs, and React hooks for working with AI agents, skills, tool definitions, and jobs.
+
+## Installation
+
+```bash
+npm install @elqnt/agents
+```
+
+## Quick Start
+
+### Browser (React)
+
+```tsx
+import { useAgents, useSkills, useToolDefinitions } from "@elqnt/agents/hooks";
+
+function AgentManager() {
+  const { listAgents, createAgent, loading, error } = useAgents({
+    baseUrl: process.env.NEXT_PUBLIC_API_GATEWAY_URL!,
+    orgId: currentOrgId,
+  });
+
+  const { listSkills } = useSkills({
+    baseUrl: process.env.NEXT_PUBLIC_API_GATEWAY_URL!,
+    orgId: currentOrgId,
+  });
+
+  // List all agents
+  const agents = await listAgents();
+
+  // Create a new agent
+  const newAgent = await createAgent({
+    name: "Customer Support",
+    description: "Handles customer inquiries",
+    model: "claude-3-sonnet",
+  });
+}
+```
+
+### Server Actions
+
+```ts
+// In a Next.js server action
+"use server";
+
+import { listAgentsServer, createAgentServer } from "@elqnt/agents/api/server";
+
+export async function getAgents(orgId: string) {
+  const response = await listAgentsServer({
+    gatewayUrl: process.env.API_GATEWAY_URL!,
+    jwtSecret: process.env.JWT_SECRET!,
+    orgId,
+  });
+  return response.data?.agents || [];
+}
+
+export async function createNewAgent(orgId: string, name: string) {
+  const response = await createAgentServer(
+    { name, model: "claude-3-sonnet" },
+    {
+      gatewayUrl: process.env.API_GATEWAY_URL!,
+      jwtSecret: process.env.JWT_SECRET!,
+      orgId,
+    }
+  );
+  return response.data?.agent;
+}
+```
+
+## Exports
+
+| Import Path | Description |
+|-------------|-------------|
+| `@elqnt/agents` | All exports (types, API, hooks) |
+| `@elqnt/agents/api` | Browser API functions |
+| `@elqnt/agents/api/server` | Server API functions |
+| `@elqnt/agents/hooks` | React hooks |
+| `@elqnt/agents/models` | TypeScript types |
+
+## API Reference
+
+### Browser API (`@elqnt/agents/api`)
+
+#### Agents
+| Function | Description |
+|----------|-------------|
+| `listAgentsApi(options)` | List all agents |
+| `getAgentApi(agentId, options)` | Get agent by ID |
+| `createAgentApi(agent, options)` | Create a new agent |
+| `updateAgentApi(agentId, agent, options)` | Update an agent |
+| `deleteAgentApi(agentId, options)` | Delete an agent |
+| `getDefaultAgentApi(options)` | Get the default agent |
+
+#### Skills
+| Function | Description |
+|----------|-------------|
+| `listSkillsApi(options)` | List all skills |
+| `getSkillApi(skillId, options)` | Get skill by ID |
+| `createSkillApi(skill, options)` | Create a new skill |
+| `updateSkillApi(skillId, skill, options)` | Update a skill |
+| `deleteSkillApi(skillId, options)` | Delete a skill |
+| `getSkillCategoriesApi(options)` | Get skill categories |
+
+#### Tool Definitions
+| Function | Description |
+|----------|-------------|
+| `listToolDefinitionsApi(options)` | List tool definitions |
+| `getToolDefinitionApi(id, options)` | Get tool definition by ID |
+| `createToolDefinitionApi(toolDef, options)` | Create tool definition |
+| `updateToolDefinitionApi(id, toolDef, options)` | Update tool definition |
+| `deleteToolDefinitionApi(id, options)` | Delete tool definition |
+
+#### Agent Jobs
+| Function | Description |
+|----------|-------------|
+| `listAgentJobsApi(options)` | List agent jobs |
+| `getAgentJobApi(jobId, options)` | Get job by ID |
+| `createAgentJobApi(job, options)` | Create a job |
+| `updateAgentJobApi(jobId, job, options)` | Update a job |
+| `deleteAgentJobApi(jobId, options)` | Delete a job |
+| `pauseAgentJobApi(jobId, options)` | Pause a job |
+| `resumeAgentJobApi(jobId, options)` | Resume a job |
+
+### Server API (`@elqnt/agents/api/server`)
+
+All browser API functions have server equivalents with `Server` suffix:
+- `listAgentsServer`, `getAgentServer`, `createAgentServer`, etc.
+- `listSkillsServer`, `getSkillServer`, `createSkillServer`, etc.
+- `listToolDefinitionsServer`, `getToolDefinitionServer`, etc.
+- `listAgentJobsServer`, `pauseAgentJobServer`, `resumeAgentJobServer`, etc.
+
+### React Hooks (`@elqnt/agents/hooks`)
+
+#### `useAgents(options)`
+```tsx
+const {
+  loading,
+  error,
+  listAgents,        // () => Promise<Agent[]>
+  listAgentSummaries,// () => Promise<AgentSummary[]>
+  getAgent,          // (id) => Promise<Agent | null>
+  createAgent,       // (agent) => Promise<Agent | null>
+  updateAgent,       // (id, agent) => Promise<Agent | null>
+  deleteAgent,       // (id) => Promise<boolean>
+  getDefaultAgent,   // () => Promise<Agent | null>
+} = useAgents(options);
+```
+
+#### `useSkills(options)`
+```tsx
+const {
+  loading,
+  error,
+  listSkills,    // () => Promise<Skill[]>
+  getSkill,      // (id) => Promise<Skill | null>
+  createSkill,   // (skill) => Promise<Skill | null>
+  updateSkill,   // (id, skill) => Promise<Skill | null>
+  deleteSkill,   // (id) => Promise<boolean>
+  getCategories, // () => Promise<string[]>
+} = useSkills(options);
+```
+
+#### `useToolDefinitions(options)`
+```tsx
+const {
+  loading,
+  error,
+  listToolDefinitions,     // () => Promise<ToolDefinition[]>
+  getToolDefinition,       // (id) => Promise<ToolDefinition | null>
+  getToolDefinitionsByIds, // (ids) => Promise<ToolDefinition[]>
+  createToolDefinition,    // (def) => Promise<ToolDefinition | null>
+  updateToolDefinition,    // (id, def) => Promise<ToolDefinition | null>
+  deleteToolDefinition,    // (id) => Promise<boolean>
+} = useToolDefinitions(options);
+```
+
+#### `useAgentJobs(options)`
+```tsx
+const {
+  loading,
+  error,
+  listAgentJobs,   // () => Promise<AgentJob[]>
+  getAgentJob,     // (id) => Promise<AgentJob | null>
+  createAgentJob,  // (job) => Promise<AgentJob | null>
+  updateAgentJob,  // (id, job) => Promise<AgentJob | null>
+  deleteAgentJob,  // (id) => Promise<boolean>
+  pauseAgentJob,   // (id) => Promise<AgentJob | null>
+  resumeAgentJob,  // (id) => Promise<AgentJob | null>
+} = useAgentJobs(options);
+```
+
+#### `useWidgets(options)`
+```tsx
+const {
+  loading,
+  error,
+  listWidgets,      // () => Promise<AgentWidget[]>
+  getWidget,        // (id) => Promise<AgentWidget | null>
+  getDefaultWidget, // () => Promise<AgentWidget | null>
+  createWidget,     // (widget) => Promise<AgentWidget | null>
+  updateWidget,     // (id, widget) => Promise<AgentWidget | null>
+  deleteWidget,     // (id) => Promise<boolean>
+  setDefaultWidget, // (id) => Promise<boolean>
+} = useWidgets({ ...options, agentId });
+```
+
+### Hook Utilities
+
+For advanced usage, the package exports hook factory utilities:
+
+```tsx
+import { useApiAsync, useOptionsRef } from "@elqnt/agents/hooks";
+
+// useApiAsync - Generic async hook with loading/error handling
+const { execute, loading, error } = useApiAsync(
+  (id: string) => getAgentApi(id, options),
+  (data) => data.agent,
+  null
+);
+
+// useOptionsRef - Keeps options in sync without stale closures
+const optionsRef = useOptionsRef(options);
+```
+
+## Types (`@elqnt/agents/models`)
+
+```typescript
+// Core types
+interface Agent { id, name, description, model, skills, ... }
+interface Skill { id, name, description, category, ... }
+interface ToolDefinition { id, name, description, schema, ... }
+interface AgentJob { id, agentId, status, frequency, ... }
+interface AgentWidget { id, agentId, name, config, ... }
+interface SubAgent { id, name, description, ... }
+```
+
+## License
+
+Private - Eloquent Platform

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elqnt/agents",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Agent management and orchestration for Eloquent platform - models, browser & server APIs, React hooks, and utilities",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",