diff --git a/CLAUDE.md b/CLAUDE.md index c15117c..e9888ec 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,117 +1,3 @@ -# TPMJS - Tool Package Manager for AI Agents - -## Philosophy - -TPMJS is a registry and package manager for AI agent tools. Just as npm transformed how developers share and consume JavaScript packages, TPMJS aims to do the same for the emerging ecosystem of AI agent tooling. - -### The Problem We're Solving - -AI agents are becoming increasingly capable, but they face a fundamental challenge: **tool discovery and selection at scale**. - -1. **Context Window Limitations** - When an agent has access to 10+ tools, LLMs struggle to remember and correctly select from all available options. Tool schemas consume precious context tokens. - -2. **Tool Hallucination** - Models sometimes attempt to call tools that don't exist, or use incorrect parameter schemas, leading to failed executions and poor user experiences. - -3. **Static Tool Sets** - Most agent implementations hardcode their available tools at build time. There's no standard way to discover, add, or share tools dynamically. - -4. **Fragmented Ecosystem** - Developers building AI agents are recreating the same tools (web search, file operations, API integrations) over and over. There's no central place to share and discover production-ready implementations. - -### Our Vision - -We believe AI agent development should be: - -- **Elegant** - Simple APIs, clear conventions, minimal boilerplate -- **Productive** - Leverage community-built tools instead of reinventing wheels -- **Safe** - Vetted tools with clear security boundaries and permissions - -## Core Concepts - -### Tools -A tool is a capability that an AI agent can invoke. Tools have: -- A unique name/identifier -- A description (used for semantic search and LLM understanding) -- A parameter schema (typically defined with Zod or JSON Schema) -- An implementation function - -### Registry -The registry is the central index of available tools. It enables: -- Browsing by category -- Semantic search (find tools by what they do, not just their name) -- Version management -- Usage analytics - -### Meta-Tools -Meta-tools are tools that help agents work with other tools. The most important is `tool-search`, which allows an agent to query the registry and load only the tools relevant to its current task. This "search-then-execute" pattern dramatically improves accuracy and token efficiency. - -## How It Works - -### The Search-Then-Execute Pattern - -Instead of loading all tool schemas into context upfront (expensive and error-prone), agents using TPMJS: - -1. **Search** - Use the `tool-search` meta-tool to find relevant tools based on the current task -2. **Load** - Dynamically load only the matched tools into context -3. **Execute** - Make a follow-up call with the focused tool set - -This pattern: -- Reduces token usage (only load what you need) -- Improves selection accuracy (smaller choice set) -- Eliminates hallucination (tools are confirmed to exist before use) -- Enables runtime flexibility (tools can be added/removed without restarts) - -## Technical Details - -### Compatibility -- TypeScript-first with full type safety via Zod schemas -- Compatible with Anthropic AI SDK, OpenAI, and other major providers -- Minimal footprint (~340 tokens for the meta-tool) - -### Scale -- Supports registries with 1,000+ tools -- Sub-2ms search latency -- Semantic search, fuzzy matching, and category filtering - -## Categories - -Tools in the registry span: -- Web & APIs -- Databases -- Documents -- Images -- Email -- Calendar -- Search -- Code Execution -- Communication -- Analytics -- Security -- Workflows - -## Development Notes - -This project is in early development. Key areas to work on: - -- [ ] Core registry API design -- [ ] Tool schema specification -- [ ] CLI for publishing and discovering tools -- [ ] SDK integrations (Anthropic, OpenAI, etc.) -- [ ] Search algorithm (semantic + fuzzy matching) -- [ ] Security model and sandboxing -- [ ] Documentation and examples - -## Open Questions - -1. **Trust & Security** - How do we vet tools? What sandboxing is needed? -2. **Versioning** - How do tools handle breaking changes? -3. **Monetization** - Free tier + Pro? Marketplace cuts? -4. **Governance** - Who decides what gets published? Moderation? -5. **Offline/Local** - Can tools be cached locally? Private registries? - ---- - -*"The registry for AI tools. Discover, share, and integrate tools that give your agents superpowers."* - ---- ## Monorepo Setup @@ -140,23 +26,7 @@ This project uses a Turborepo monorepo architecture with the following structure ### Architecture Principles -#### 1. .ts-only React Components -All UI components use `.ts` extension instead of `.tsx` and utilize `createElement`: - -```typescript -import { createElement, forwardRef } from 'react'; - -export const Button = forwardRef( - (props, ref) => createElement('button', { ref, ...props }) -); -``` - -**Why?** -- Explicit runtime behavior -- Prevents JSX spreading anti-patterns -- Better for code generation -- Forces consideration of every prop #### 2. No Barrel Exports @@ -211,13 +81,6 @@ pnpm lint pnpm format ``` -### Component Development - -1. Create component in `packages/ui/src/ComponentName/ComponentName.ts` -2. Use `.ts` extension with `createElement` -3. Add tests in `ComponentName.test.ts` -4. Export in `package.json` exports map -5. Add Storybook story in `packages/storybook/stories/` ### Publishing Flow @@ -232,7 +95,7 @@ pnpm format - **Build System:** Turborepo - **Package Manager:** pnpm - **TypeScript:** Strict mode, composite projects -- **React:** v19 with .ts-only components +- **React:** v19 - **Next.js:** v16 App Router - **Styling:** Tailwind CSS - **Testing:** Vitest + Testing Library diff --git a/apps/web/src/app/playground/page.tsx b/apps/web/src/app/playground/page.tsx index 39aceb6..7a1988b 100644 --- a/apps/web/src/app/playground/page.tsx +++ b/apps/web/src/app/playground/page.tsx @@ -10,14 +10,22 @@ import { CardHeader, CardTitle, } from '@tpmjs/ui/Card/Card'; +import { Checkbox } from '@tpmjs/ui/Checkbox/Checkbox'; import { CodeBlock } from '@tpmjs/ui/CodeBlock/CodeBlock'; import { Container } from '@tpmjs/ui/Container/Container'; +import { FormField } from '@tpmjs/ui/FormField/FormField'; import { Header } from '@tpmjs/ui/Header/Header'; import { Icon } from '@tpmjs/ui/Icon/Icon'; import { Input } from '@tpmjs/ui/Input/Input'; import { Label } from '@tpmjs/ui/Label/Label'; import { ProgressBar } from '@tpmjs/ui/ProgressBar/ProgressBar'; +import { Radio } from '@tpmjs/ui/Radio/Radio'; +import { RadioGroup } from '@tpmjs/ui/Radio/RadioGroup'; +import { Select } from '@tpmjs/ui/Select/Select'; +import { Slider } from '@tpmjs/ui/Slider/Slider'; +import { Switch } from '@tpmjs/ui/Switch/Switch'; import { Tabs } from '@tpmjs/ui/Tabs/Tabs'; +import { Textarea } from '@tpmjs/ui/Textarea/Textarea'; import Link from 'next/link'; import { useState } from 'react'; import { ThemeToggle } from '../../components/ThemeToggle'; @@ -26,6 +34,17 @@ export default function PlaygroundPage() { const [activeTab, setActiveTab] = useState('all'); const [progress, setProgress] = useState(65); + // Form state + const [name, setName] = useState(''); + const [bio, setBio] = useState(''); + const [newsletter, setNewsletter] = useState(false); + const [terms, setTerms] = useState(false); + const [theme, setTheme] = useState('system'); + const [notifications, setNotifications] = useState(true); + const [country, setCountry] = useState(''); + const [volume, setVolume] = useState(50); + const [privacy, setPrivacy] = useState('public'); + return (
{/* Header */} @@ -443,6 +462,244 @@ export default function Example() {
+ {/* Forms Section */} +
+

Form Components

+ + {/* Textarea */} +
+

Textarea

+
+ +