{"id":29817157,"url":"https://github.com/mocksi/bilan-example-writing-ai","last_synced_at":"2025-07-28T20:12:22.586Z","repository":{"id":306021838,"uuid":"1024666665","full_name":"Mocksi/bilan-example-writing-ai","owner":"Mocksi","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-23T06:50:52.000Z","size":211,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-23T08:37:11.668Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mocksi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-23T04:28:23.000Z","updated_at":"2025-07-23T06:15:16.000Z","dependencies_parsed_at":"2025-07-23T08:37:20.573Z","dependency_job_id":null,"html_url":"https://github.com/Mocksi/bilan-example-writing-ai","commit_stats":null,"previous_names":["mocksi/bilan-example-writing-ai"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/Mocksi/bilan-example-writing-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mocksi%2Fbilan-example-writing-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mocksi%2Fbilan-example-writing-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mocksi%2Fbilan-example-writing-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mocksi%2Fbilan-example-writing-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mocksi","download_url":"https://codeload.github.com/Mocksi/bilan-example-writing-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mocksi%2Fbilan-example-writing-ai/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267578003,"owners_count":24110351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-28T20:12:22.005Z","updated_at":"2025-07-28T20:12:22.521Z","avatar_url":"https://github.com/Mocksi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bilan Content Creation Demo\n\nA demonstration application showcasing how to integrate Bilan SDK into an AI-powered content creation assistant. This template demonstrates proper analytics integration patterns for AI applications.\n\n**Important**: This is a CLIENT application that sends analytics data TO Bilan's server. It does not display analytics - that's handled by the Bilan dashboard.\n\n## Features\n\n- 🤖 **AI Content Generation**: Local WebLLM inference for blog posts, emails, and social media\n- 📊 **Comprehensive Analytics**: Full Bilan SDK integration with turn tracking, user feedback, and journey analytics\n- 🎨 **Modern UI**: Mantine v7 components with responsive design\n- 🔄 **Iterative Refinement**: Multi-turn content improvement workflow\n- 📈 **Real-time Tracking**: All user interactions sent to Bilan for analysis\n\n## Prerequisites\n\nBefore you begin, ensure you have:\n\n- **Node.js 18+** installed\n- **Modern browser** with WebAssembly support\n\n### Zero Setup Required\n\nThis demo uses WebLLM for completely local AI inference:\n- ✅ No external services or APIs required\n- ✅ No model installation needed\n- ✅ Works completely offline after first model download\n- ✅ Models download automatically on first use\n- ✅ Multiple model options: Llama 3.2 1B/3B, Gemma 2B\n\n## Quick Start\n\n1. **Clone and install dependencies**:\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd bilan-example-writing-ai\n   npm install\n   ```\n\n2. **Configure environment**:\n   ```bash\n   cp .env.example .env.local\n   ```\n   Edit `.env.local` with your settings (defaults should work for local development).\n\n3. **Start the development server**:\n   ```bash\n   npm run dev\n   ```\n\n4. **Open your browser**:\n   Navigate to [http://localhost:3000](http://localhost:3000)\n\n## Environment Variables\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `NEXT_PUBLIC_AI_MODEL` | WebLLM model ID | `Llama-3.2-1B-Instruct-q4f32_1-MLC` | No |\n| `NEXT_PUBLIC_BILAN_ENDPOINT` | Bilan server URL | `http://localhost:3002` | **Yes for server mode** |\n| `NEXT_PUBLIC_BILAN_MODE` | Bilan mode (`local` or `server`) | `local` | **Yes for production** |\n| `NEXT_PUBLIC_BILAN_API_KEY` | Bilan API key | - | **Yes for server mode** |\n| `NEXT_PUBLIC_DEBUG` | Enable debug logging | `false` | No |\n\n### 🚨 Production Deployment Requirements\n\n**CRITICAL**: For production deployments, you MUST:\n\n1. **Set `NEXT_PUBLIC_BILAN_MODE=server`** - Demo tokens are prohibited in production\n2. **Provide `NEXT_PUBLIC_BILAN_API_KEY`** - Your actual Bilan API key\n3. **Set `NEXT_PUBLIC_BILAN_ENDPOINT`** - Your production Bilan server URL\n\n```bash\n# ✅ Production .env.local\nNEXT_PUBLIC_BILAN_MODE=server\nNEXT_PUBLIC_BILAN_ENDPOINT=https://your-bilan-server.com\nNEXT_PUBLIC_BILAN_API_KEY=your-production-api-key\nNEXT_PUBLIC_DEBUG=false\n```\n\n**Production Safety Check**: The app will throw a runtime error if `NODE_ENV=production` and `BILAN_MODE` is not `server`, preventing accidental use of demo tokens in production.\n\n### Available Models\n\n- `Llama-3.2-1B-Instruct-q4f32_1-MLC` - Fast, lightweight (1.2GB)\n- `Llama-3.2-3B-Instruct-q4f32_1-MLC` - Balanced quality (2.4GB)\n- `gemma-2-2b-it-q4f32_1-MLC` - Creative content (1.8GB)\n\n***BILAN_ENDPOINT Requirements:**\n- **Required when `BILAN_MODE=\"server\"`** - Application will throw startup error if missing\n- **Required for analytics dashboard access** - Navigation to analytics will throw runtime error if missing\n- **Optional for `BILAN_MODE=\"local\"`** - Analytics will work in local mode without external server\n- **Format**: Full URL including protocol (e.g., `http://localhost:3002` or `https://your-bilan-server.com`)\n\n### Error Behaviors\n\nThe application will throw explicit errors in these cases:\n- **Startup Error**: When `BILAN_MODE=\"server\"` but `BILAN_ENDPOINT` is not configured\n- **Runtime Error**: When clicking \"View Analytics\" but `BILAN_ENDPOINT` is not configured\n- **Purpose**: Prevents silent failures and ensures proper Bilan server integration\n\n## Usage\n\n1. **Select Content Type**: Choose from Blog Post, Email, or Social Media\n2. **Provide Brief**: Describe what you want to create\n3. **Generate Content**: AI creates initial draft using WebLLM\n4. **Provide Feedback**: Accept, reject, or request refinements\n5. **Iterate**: Refine until satisfied\n6. **View Analytics**: Check Bilan dashboard for interaction insights\n\n## Bilan Integration\n\nThis demo showcases comprehensive Bilan SDK usage:\n\n- **Turn Tracking**: Every AI interaction wrapped with `trackTurn()`\n- **User Feedback**: Vote collection with `vote()` using turn correlation\n- **Journey Analytics**: Complete workflow tracking with `trackJourneyStep()`\n- **Conversation Management**: Session lifecycle with `startConversation()` / `endConversation()`\n- **Advanced Patterns**: Frustration detection, preference learning, quality signals\n\nAll analytics data is sent to Bilan for processing and visualization in the Bilan dashboard.\n\n## Development\n\n```bash\n# Development server\nnpm run dev\n\n# Build for production\nnpm run build\n\n# Start production server\nnpm start\n\n# Linting and formatting\nnpm run lint\nnpm run format\n```\n\n## Project Structure\n\n```\nsrc/\n├── app/                 # Next.js App Router\n├── components/          # React components\n├── lib/                 # Utility libraries\n├── hooks/               # Custom React hooks\n├── types/               # TypeScript definitions\n└── utils/               # Helper functions\n```\n\n## Contributing\n\nThis is a template repository. Fork it to create your own Bilan integration examples!\n\n## License\n\nMIT License - feel free to use this as a starting point for your own AI applications with Bilan analytics.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmocksi%2Fbilan-example-writing-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmocksi%2Fbilan-example-writing-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmocksi%2Fbilan-example-writing-ai/lists"}