logosai-forge 0.5.0__tar.gz

logosai_forge-0.5.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: logosai-forge
+Version: 0.5.0
+Summary: AI Agent Generation Library — Agents Building Agents
+Author: LogosAI Team
+License: Proprietary (pre-publication)
+Project-URL: Homepage, https://github.com/maior/logosai-forge
+Keywords: ai,agent,code-generation,agentic,logosai
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: google-generativeai>=0.8.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: logosai
+Requires-Dist: logosai>=0.7.0; extra == "logosai"
+
+# logosai-forge
+
+**FORGE: An AI Agent Code Builder** — agents that create, fix, and evolve other agents.
+
+15 agentic AI agents collaborate to autonomously generate, improve, enhance, and self-evolve agent code.
+
+## Installation
+
+```bash
+pip install logosai-forge
+```
+
+## Quick Start
+
+```python
+import asyncio
+from logosai_forge import ForgeClient
+
+async def main():
+    forge = ForgeClient()
+
+    # Generate a new agent
+    result = await forge.create_agent(
+        "Calculate BMI from weight and height",
+        test_cases=[{
+            "input": {"weight_kg": 70, "height_m": 1.75},
+            "expected": {"bmi": 22.9, "category": "normal"}
+        }]
+    )
+    print(result.code)
+
+    # Fix a broken agent
+    result = await forge.improve_agent(agent_code, {
+        "error_type": "logic_error",
+        "error_message": "Condition is inverted — score>700 should approve",
+        "test_input": {"credit_score": 750},
+        "expected_output": {"decision": "approved"},
+        "actual_output": {"decision": "denied"},
+    })
+    print(result.changes)
+
+    # Add missing functions
+    result = await forge.enhance_agent(
+        existing_code,
+        "Add multiply and divide methods"
+    )
+    print(result.added_functions)  # ['_multiply', '_divide']
+
+asyncio.run(main())
+```
+
+## Features
+
+| Method | Purpose | Example |
+|--------|---------|---------|
+| `create_agent()` | Generate new agent from query | "Calculate shipping cost" |
+| `improve_agent()` | Fix bugs from failure feedback | Inverted condition, wrong formula |
+| `enhance_agent()` | Add missing logic/functions | "Add caching", "Add error handling" |
+
+### Self-Evolution Infrastructure (v0.2.16)
+
+FORGE now detects duplicate agents, composes agents from reusable blocks, and extracts blocks from existing agents:
+
+```python
+# Duplicate detection — avoid creating redundant agents
+# (Automatic in V6 pipeline Stage 0)
+result = await forge.create_agent("File search agent")
+# → Detects existing file_agent, asks: create_new / extend_existing / cancel
+```
+
+REST API endpoints:
+- `GET /api/blocks/search?query=&category=` — search 339 reusable blocks
+- `GET /api/blocks/{block_id}` — block detail
+- `POST /api/blocks/compose` — compose agent from selected blocks
+- `POST /api/agents/check-duplicate` — similarity analysis (4-dim: purpose/function/tags/pattern)
+- `POST /api/agents/{id}/extract-blocks` — extract reusable functions from existing agent
+
+**Registry**: 339 building blocks (157 templates + 169 slices + 13 extracted), unified adapter over existing FORGE assets.
+
+### Desktop Library Integration (v0.2.15)
+
+Generated agents automatically use `logosai.desktop` for messaging and desktop control:
+
+```python
+# Messaging channels (API-based)
+result = await forge.create_agent("Telegram으로 메시지 보내는 에이전트")
+# → Uses: from logosai.desktop.channels.telegram import TelegramChannel
+
+# Desktop app control (GUI automation)
+result = await forge.create_agent("카카오톡으로 메시지 보내는 에이전트")
+# → Uses: from logosai.desktop.apps.kakaotalk import KakaoTalkController
+```
+
+**Supported**: Telegram, Slack, Discord, LINE, Teams (API) + KakaoTalk, Gmail, Notion (GUI)
+
+### Natural Language Query Parsing (v0.2.15)
+
+Generated agents parse natural language into structured parameters via LLM:
+
+```
+"5 킬로그램을 파운드로" → _parse_query(LLM) → {"kilograms": 5.0} → business function
+```
+
+No code changes needed — `_parse_query()` is auto-generated with exact parameter hints from function specs.
+
+### ACP-Compliant Code Generation
+
+Generated agents automatically follow the ACP Agent Interface Specification:
+- `process(query, context)` with query str/dict normalization + LLM parameter extraction
+- `AgentResponse` with `content["answer"]` (string)
+- File creation agents return `file_path` + `file_name`
+- Search agents return `files` list with absolute paths
+- Uses python-pptx, openpyxl, subprocess (mdfind, pdfgrep) when appropriate
+
+### Function Slice Architecture
+
+Agents are built by **combining reusable function slices** (174 slices), not writing entire code from scratch.
+
+`improve_agent()` works at function granularity with a dedicated repair pipeline:
+1. Extract functions (AST-based, sync + async)
+2. Diagnose: LLM identifies broken function + root cause
+3. Repair: `_repair_function()` fixes in-place (preserves original signature, not regenerate)
+4. Replace in original code (other functions untouched)
+5. Validate: quick execution check + full test case comparison
+6. Auto-register fixed version to function registry
+
+**E2E accuracy**: create_agent 98%, improve_agent 100% (3-run average).
+
+Supports large agents (15KB+) with size-based strategy and dynamic timeouts.
+
+### Function Template Library
+
+153 reusable function templates across 21 categories, including:
+- **API Channels**: Telegram, Slack, Discord, LINE, Teams (`logosai.desktop.channels`)
+- **Desktop Apps**: KakaoTalk, Gmail, Notion AppControllers (`logosai.desktop.apps`)
+- **File Ops**: PDF/Excel/PPTX/DOCX read/write, Spotlight search
+- **Vision**: Screen capture, Vision AI analysis, ReAct loop
+- **Browser**: Chrome automation, form fill, JS injection
+
+### Domain Expert Review (v0.2.12)
+
+Pipeline Stage 6.5 — after code assembly, a **dynamically created domain expert** reviews the generated code:
+- Automatic domain detection (finance, healthcare, legal, etc.)
+- Confidence gate: low confidence → expert feedback injected into retry loop
+- Enable/disable via YAML config (`domain_review.enabled`)
+
+### Function Intelligence
+
+- **Telemetry**: per-function call count, success rate, error types (SQLite)
+- **Version Management**: auto-increment versions, quality comparison, rollback
+- **Composition Learning**: tracks which functions work well together (function pairs)
+- **Pattern-Based Generation**: successful functions as reference for new domains
+- **Quality Gate**: success rate < 0.70 → blocked from library admission
+- **Function Graph**: unified ontology connecting templates, pairs, metrics, and type compatibility
+
+### Persistent Memory & Observability
+
+- Learned patterns survive server restarts (SQLite-backed)
+- All reasoning traces persisted and queryable (agent, time, success)
+- Configuration via YAML (`config/agentic_pipeline.yaml`) + env var overrides
+- Tool Registry for LLM/library dependency injection
+- Context Manager for priority-based LLM token fitting
+
+## Setup
+
+### Google API Key (required)
+
+FORGE uses Gemini LLM for code generation. A Google API Key is required.
+
+```bash
+export GOOGLE_API_KEY="your-google-api-key-here"
+```
+
+Get your API key: https://aistudio.google.com/apikey
+
+## Requirements
+
+- Python 3.10+
+- Google API Key (`GOOGLE_API_KEY` environment variable)
+- LogosAI framework (optional, for agent execution)
+
+## License
+
+Source code will be open-sourced after paper publication.
+Part of the [LogosAI](https://github.com/maior) ecosystem.

logosai_forge-0.5.0/README.md

@@ -0,0 +1,363 @@
+# FORGE AI
+
+**Framework for Orchestrating Reactive Generated Entities**
+
+FORGE is an AI-powered agent builder that generates production-ready Python agents from natural language descriptions. Instead of manually coding agents, describe what you need and FORGE handles query analysis, business logic synthesis, code generation, and self-healing validation automatically.
+
+> **🆕 2026-06-14 — Collaborative Self-Evolution**: self-healing and self-growing are no longer isolated stages — they **converse** (Healer posts a diagnosis, Grower regenerates and learns) and **grow each other** over time. Runs at V6 Stage 7.5 behind `FORGE_COLLAB_EVOLUTION` (default off). Generation can also be driven directly by logos_api over WebSocket (`FORGE_VIA_API`). See `docs/COLLABORATIVE_SELF_EVOLUTION_DESIGN.md`.
+
+---
+
+## How It Works
+
+```
+User Query ──► Query Analysis ──► Business Logic ──► Code Assembly ──► Self-Healing ──► Agent
+                                     Synthesis         + Agentic AI     Validation
+```
+
+**Input**: `"Create a calculator agent that adds and multiplies numbers"`
+
+**Output**: A complete Python agent class (~200 lines) with:
+- Proper class structure inheriting from LogosAIAgent
+- Async `process()` method with business logic
+- Error handling, logging, and metadata
+- Optional agentic capabilities (tool use, reasoning, memory)
+
+## Features
+
+### Agent Generation Pipeline
+- **6-stage progressive generation**: Query analysis → pattern detection → function generation → workflow orchestration → code assembly → validation
+- **Domain-aware LLM prompts**: 14 domain categories with specialized hints (calculation, finance, analysis, vision, etc.)
+- **LLM retry with fallback**: Primary generation → retry with shorter prompt → template fallback
+- **Unified code validation**: Structural checks instead of brittle keyword matching
+
+### Agentic AI Integration
+Generated agents can use the LogosAI SDK's agentic modules when the query requires advanced capabilities:
+- **AgenticCore**: Think-Plan-Act-Reflect reasoning cycle
+- **AgenticTools**: Automatic tool registration from generated functions
+- **AgenticMemory**: 5 memory types (short-term, long-term, episodic, semantic, procedural)
+- **AgenticReasoning**: Chain-of-thought reasoning
+
+### Workflow Orchestration
+5 workflow patterns for multi-step agents:
+
+| Pattern | Use Case |
+|---------|----------|
+| Pipeline | Each step feeds the next (ETL, data processing) |
+| Parallel | Independent steps run concurrently via `asyncio.gather()` |
+| Sequential | Ordered execution with data piping between dependent steps |
+| Conditional | Branch execution based on runtime conditions |
+| Loop | Iterative improvement with convergence detection |
+
+### Self-Healing
+3-stage automatic error correction:
+1. **Rule-based** (<100ms): Fixes indentation, missing colons, unclosed brackets
+2. **LLM-based** (<500ms): AI-powered fixes for complex errors
+3. **Pattern-based**: Learns from previously successful fixes
+
+### Self-Evolution (Optional)
+Paper2-verified self-evolution system integrated into the generation pipeline:
+- **Self-Growing**: Gap detection against a 169-slice code library
+- **Self-Evaluation**: 5-dimensional quality scoring
+- **Self-Healing**: 3-stage healing with library admission
+
+### Web Interface
+Full-featured IDE for agent development and management:
+- **3-panel layout**: Agent sidebar + Monaco code editor + AI chat panel
+- **AI Chat Assistant**: Conversational agent creation and code editing via Gemini LLM
+- **Knowledge Graph**: D3.js force-directed visualization of agent generation ontology (embedded split view)
+- **Per-hunk Diff Review**: Accept/Reject individual code changes with unified diff preview
+- **Agent Metadata Editor**: Marketplace-ready metadata management (capabilities, tags, category, parameters)
+- **Agent Templates**: Quick scaffolding with 3 built-in templates (Basic, API Integration, Data Analysis)
+- **Interactive Testing Lab**: Sandboxed agent execution with real-time output
+- **Performance Monitoring Dashboard**: D3.js metrics visualization
+
+## Quick Start
+
+### Prerequisites
+- Python 3.11+
+- Node.js 18+ (for web interface)
+- Google API key (for Gemini LLM) or OpenAI API key
+
+### Installation
+
+```bash
+# Clone and set up
+git clone <repository-url>
+cd forge
+
+# Install Python dependencies
+pip install -r requirements.txt
+
+# Set API keys
+export GOOGLE_API_KEY="your-google-api-key"
+# or
+export OPENAI_API_KEY="your-openai-api-key"
+```
+
+### Start the Server
+
+```bash
+# Backend (port 8030)
+python server.py
+
+# Frontend (port 3001, optional)
+cd prototype/frontend
+npm install && npm run dev
+```
+
+### Generate an Agent
+
+**Via API:**
+```bash
+curl -X POST http://localhost:8030/api/agents/create-unified \
+  -H "Content-Type: application/json" \
+  -d '{"query": "Create a calculator agent that adds and multiplies numbers"}'
+```
+
+**Via Python:**
+```python
+import asyncio
+from core.forge_v2_system import ForgeV2System, ForgeV2Request
+
+async def main():
+    forge = ForgeV2System()
+    request = ForgeV2Request(
+        query="Create a data analysis agent that computes statistics",
+        user_email="user@example.com"
+    )
+    result = await forge.create_agent(request)
+    print(f"Agent: {result.metadata.get('agent_name')}")
+    print(f"Code: {len(result.agent_code)} characters")
+
+asyncio.run(main())
+```
+
+**Via WebSocket (streaming):**
+```javascript
+const ws = new WebSocket('ws://localhost:8030/ws/client-123');
+ws.send(JSON.stringify({
+  action: 'create_agent',
+  data: { query: 'Create a weather monitoring agent' }
+}));
+ws.onmessage = (event) => {
+  const msg = JSON.parse(event.data);
+  console.log(`[${msg.stage}] ${msg.message}`);
+};
+```
+
+## Project Structure
+
+```
+forge/
+├── core/
+│   ├── business_logic_v2/          # Core generation pipeline
+│   │   ├── query_analyzer.py       # Intent extraction & requirement analysis
+│   │   ├── function_generator.py   # LLM-powered function code generation
+│   │   ├── code_assembler.py       # Final agent code assembly + agentic integration
+│   │   ├── workflow_orchestrator.py # 5-pattern workflow generation
+│   │   ├── self_healing.py         # 3-stage error correction
+│   │   ├── performance_monitor.py  # Generation metrics tracking
+│   │   └── slice_library/          # 169 reusable code slices
+│   ├── self_evolution/             # Self-Growing + Self-Evaluation + Self-Healing
+│   │   ├── orchestrator.py         # Pre/post generation hooks
+│   │   └── adapters/               # Paper2 system wrappers
+│   └── forge_v2_system.py          # Main pipeline orchestrator
+│
+├── prototype/
+│   ├── backend/                    # FastAPI server (30+ endpoints)
+│   │   └── app/
+│   │       ├── main.py             # App entry + route registration
+│   │       └── api/                # REST + WebSocket endpoints
+│   │           ├── agents.py       # Agent CRUD + metadata management
+│   │           ├── websocket_interactive_agent.py  # AI chat via Gemini
+│   │           └── knowledge_graph.py  # KG data API
+│   └── frontend/                   # Next.js 15 web interface
+│       └── app/forge/
+│           ├── components/
+│           │   ├── workspace/      # Editor, TabBar, WelcomeScreen, KG view
+│           │   ├── chat/           # AI chat panel, diff preview, messages
+│           │   ├── sidebar/        # Agent tree, folder management
+│           │   └── metadata/       # Agent metadata editor modal
+│           ├── contexts/           # UI, Forge, Editor, Generation providers
+│           └── lib/                # Agent templates
+│
+├── templates/                      # Agent code templates
+├── agents/generated/               # Output directory for generated agents
+├── server.py                       # Main server entry point
+└── config/                         # LLM and system configuration
+```
+
+## API Reference
+
+### REST Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/agents/create-unified` | Generate agent from query |
+| `POST` | `/api/agents/create-draft` | Create blank draft agent |
+| `GET` | `/api/agents/list` | List all generated agents |
+| `GET` | `/api/agents/{id}/code` | Get agent source code |
+| `PUT` | `/api/agents/{id}/metadata` | Update agent metadata for marketplace |
+| `DELETE` | `/api/agent-code/delete/{id}` | Delete agent |
+| `GET` | `/api/knowledge-graph/{id}` | Get agent knowledge graph data |
+| `POST` | `/api/code/fix` | AI-powered code fixing |
+| `POST` | `/api/execute-python-safe` | Sandboxed code execution |
+| `GET` | `/api/monitoring/overview` | System metrics dashboard |
+| `GET` | `/health` | Health check |
+
+### WebSocket Endpoints
+
+| Endpoint | Purpose |
+|----------|---------|
+| `/ws/{client_id}` | Streaming agent generation with progress events |
+| `/ws/interactive/{client_id}` | AI chat assistant (conversational code creation/editing) |
+
+### Progress Events (WebSocket)
+
+```
+initialization → analyzing → planning → generating → validating → complete
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GOOGLE_API_KEY` | Yes* | Google Gemini API key |
+| `OPENAI_API_KEY` | Yes* | OpenAI API key |
+| `ANTHROPIC_API_KEY` | No | Anthropic Claude API key |
+| `FORGE_ENABLE_SELF_EVOLUTION` | No | Enable self-evolution system (default: off) |
+| `FORGE_EVOLUTION_TAU_MATCH` | No | Coverage matching threshold (default: 0.40) |
+| `FORGE_EVOLUTION_TAU_QUALITY` | No | Quality admission threshold (default: 0.70) |
+
+*At least one LLM API key is required.
+
+### LLM Configuration
+
+The system uses Gemini Flash Lite by default for fast generation. Configure in `config/llm_config.yaml`:
+
+```yaml
+models:
+  gemini_flash_lite:
+    provider: "gemini"
+    model_id: "gemini-2.5-flash-lite"
+    temperature: 0.3
+```
+
+## Architecture
+
+### Generation Pipeline
+
+```
+ForgeV2System.create_agent(request)
+│
+├── 1. IntelligentAnalyzer
+│   └── Query → intent, features, domain, complexity
+│
+├── 2. BusinessLogicGeneratorV2 (6 stages)
+│   ├── Stage 1: Query Analysis → FunctionSpecs
+│   ├── Stage 2: Template Search (169-slice library)
+│   ├── Stage 3: Logic Synthesis (combine templates)
+│   ├── Stage 4: LLM Generation (DOMAIN_HINTS-guided prompts)
+│   ├── Stage 5: Workflow Orchestration (5 patterns)
+│   └── Stage 6: Code Assembly (+ agentic integration)
+│
+├── 3. Self-Healing (if errors detected)
+│   ├── Rule-based fixes → LLM fixes → Pattern fixes
+│   └── Retry up to 3 times
+│
+├── 4. Self-Evolution (optional, if enabled)
+│   ├── Pre-generation: gap detection
+│   └── Post-generation: evaluation + healing + admission
+│
+└── 5. Result
+    ├── agent_code: str (complete Python agent)
+    ├── metadata: dict (agent name, analysis, metrics)
+    └── test_results: dict (validation outcomes)
+```
+
+### Generated Agent Structure
+
+```python
+import logging
+from logosai import LogosAIAgent
+from logosai.config import AgentConfig
+
+class CalculatorAgent(LogosAIAgent):
+    def __init__(self):
+        config = AgentConfig(
+            name="Calculator Agent",
+            description="Adds and multiplies numbers",
+            version="1.0.0",
+            config={"agentic_config": {
+                "enable_agentic": True,
+                "tools_enabled": True,
+                "reasoning_type": "chain_of_thought",
+                "memory_capacity": 100,
+            }}
+        )
+        super().__init__(config)
+        # Auto-registered tools from generated functions
+
+    async def _calculate_sum(self, data):
+        a = data.get("a", 0)
+        b = data.get("b", 0)
+        return {"result": a + b}
+
+    async def process(self, input_data, options=None):
+        # Uses AgenticCore.execute_cycle() when available
+        # Falls back to direct function execution
+        ...
+```
+
+## Testing
+
+```bash
+# Syntax check all core modules
+python -c "import ast; ast.parse(open('core/business_logic_v2/function_generator.py').read()); print('OK')"
+
+# Test full pipeline
+python -c "
+import asyncio
+from core.forge_v2_system import ForgeV2System, ForgeV2Request
+forge = ForgeV2System()
+result = asyncio.run(forge.create_agent(
+    ForgeV2Request(query='Create a calculator', save_to_file=False, enable_testing=False)
+))
+print(f'Success: {result.success}, Lines: {len(result.agent_code.splitlines())}')
+"
+
+# Server health check
+curl http://localhost:8030/health
+```
+
+## Security
+
+- **Sandboxed execution**: Generated agents run in isolated environments
+- **Code validation**: Multi-layer syntax and security checks
+- **Resource limits**: Memory and execution time constraints
+- **Input sanitization**: Protection against injection attacks
+
+## Technology Stack
+
+| Component | Technology |
+|-----------|------------|
+| Backend | Python 3.11+, FastAPI, aiohttp |
+| Frontend | Next.js 15, React 19, TypeScript |
+| Code Editor | Monaco Editor |
+| LLM | Google Gemini, OpenAI GPT, Anthropic Claude |
+| Database | SQLite (dev), PostgreSQL (prod) |
+| UI | Tailwind CSS, Radix UI, D3.js |
+| Agent Framework | LogosAI SDK |
+
+## License
+
+MIT License
+
+## Acknowledgments
+
+- Built on the [LogosAI](https://github.com/maior/logosai-framework) agent framework
+- Powered by Google Gemini, OpenAI, and Anthropic LLMs
+- Frontend components from [shadcn/ui](https://ui.shadcn.com)