@arcteninc/core 0.0.176 → 0.0.177

package/README.md

@@ -1,6 +1,6 @@
 # @arcteninc/core
 
-React component library for building AI-powered agent interfaces.
+Core hooks, types, and utilities for building AI-powered agent interfaces.
 
 ## Installation
 
@@ -14,114 +14,109 @@ pnpm add @arcteninc/core
 bun add @arcteninc/core
 ```
 
-## Requirements
+> **Note:** For the pre-built UI component (`<ArctenAgent>`), install `@arcteninc/ui` instead. See [@arcteninc/ui](../ui/README.md) for details.
 
-**Tailwind CSS is only required if you're using the visual components** (like `<ArctenAgent>`). If you're only using the headless hooks (like `useAgent`), Tailwind is not needed.
+## What's in this package
 
-The UI components use Tailwind utility classes for styling.
+This package provides the **headless** building blocks for creating AI agent interfaces:
 
-### Setting up Tailwind CSS
-
-1. Install Tailwind CSS (if not already installed):
-
-```bash
-npm install -D tailwindcss
-npx tailwindcss init
-```
-
-2. Configure Tailwind to scan the library's components by adding the package path to your `content` array in `tailwind.config.js`:
-
-```js
-/** @type {import('tailwindcss').Config} */
-module.exports = {
-  content: [
-    "./src/**/*.{js,ts,jsx,tsx,mdx}",
-    // Add this line to include @arcteninc/core components:
-    "./node_modules/@arcteninc/core/dist/**/*.{js,mjs}"
-  ],
-  theme: {
-    extend: {},
-  },
-  plugins: [],
-}
-```
-
-3. Include Tailwind directives in your CSS:
-
-```css
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-```
+- **`useAgent`** - React hook for managing agent conversations, tool calls, and state
+- **`useGenerate`** - React hook for one-off AI text/object generation
+- **Types** - TypeScript types for tool definitions, conversations, and configurations
+- **Utilities** - Helper functions like `extractToolsMetadata`
 
 ## Usage
 
-### Complete Example
+### useAgent Hook
 
 ```tsx
-// 1. Import the component
-import { ArctenAgent } from "@arcteninc/core";
-
-// 2. Import the styles (REQUIRED - styles are NOT auto-applied)
-import "@arcteninc/core/styles";
+import { useAgent } from "@arcteninc/core";
+import type { UseAgentOptions } from "@arcteninc/core";
+
+function MyCustomChat() {
+  const {
+    messages,
+    sendMessage,
+    status,
+    stop,
+  } = useAgent({
+    apiBaseUrl: "https://api.arcten.com",
+    user: { id: "user-123" },
+    tools: myTools,
+  });
 
-function App() {
   return (
-    <ArctenAgent
-      title="My AI Assistant"
-      tokenEndpoint="/api/arcten/token"
-    />
+    <div>
+      {messages.map((msg) => (
+        <div key={msg.id}>{msg.content}</div>
+      ))}
+      <button onClick={() => sendMessage({ text: "Hello!" })}>
+        Send
+      </button>
+    </div>
   );
 }
 ```
 
-**⚠️ Important:** Importing the component does NOT automatically include styles. You must import the CSS separately (see below).
+### useGenerate Hook
 
-### Import Styles
+```tsx
+import { useGenerate } from "@arcteninc/core";
 
-**Required:** You MUST import the CSS styles separately for the components to display correctly. The styles are pre-compiled and self-contained - they work regardless of whether you're using Tailwind CSS in your project.
+function MyComponent() {
+  const { generateText, generateObject, isLoading } = useGenerate({
+    apiBaseUrl: "https://api.arcten.com",
+  });
 
-#### Option 1: Import in your CSS file (Recommended)
+  const handleGenerate = async () => {
+    const result = await generateText({
+      prompt: "Write a haiku about coding",
+    });
+    console.log(result);
+  };
 
-```css
-/* In your globals.css or main CSS file */
-@import "@arcteninc/core/styles";
+  return <button onClick={handleGenerate}>Generate</button>;
+}
 ```
 
-#### Option 2: Import in your JavaScript/TypeScript
-
-```tsx
-// In your main entry file (e.g., app.tsx, _app.tsx, layout.tsx)
-import "@arcteninc/core/styles";
-```
+## Pre-built UI Component
 
-#### Option 3: Import via CDN (if using unpkg or similar)
+If you want a ready-to-use chat interface, use the `@arcteninc/ui` package:
 
-```html
-<link rel="stylesheet" href="https://unpkg.com/@arcteninc/core@latest/dist/core.css" />
+```bash
+npm install @arcteninc/core @arcteninc/ui
 ```
-## Development
 
-To install dependencies:
+```tsx
+import { ArctenAgent } from "@arcteninc/ui";
+import "@arcteninc/ui/styles";
 
-```bash
-bun install
+function App() {
+  return (
+    <ArctenAgent
+      apiBaseUrl="https://api.arcten.com"
+      user={{ id: "user-123" }}
+    />
+  );
+}
 ```
 
-To build:
+## CLI Utilities
+
+This package includes a utility for extracting tool metadata:
 
 ```bash
-bun run build
+# Extract tool types and metadata
+npx arcten extract-types
+
+# Or specify a custom tools file
+npx arcten extract-types --tools ./src/tools.ts
 ```
 
-To watch for changes:
+## Development
 
 ```bash
-bun run dev
+bun install    # Install dependencies
+bun run build  # Build the package
+bun run dev    # Watch for changes
 ```
-
-## Notes
-
-- The CSS is pre-compiled and includes all necessary Tailwind styles
-- You don't need to configure Tailwind CSS in your project to use this package
-- The styles are self-contained and won't conflict with your existing styles