Metadata-Version: 2.4
Name: vibeserver
Version: 0.3.0
Summary: Prompt-driven backend framework — add AI-powered natural language tool execution to any Python project
Author: VibeServer
License: MIT
Keywords: agent,ai,backend,fastapi,llm,natural-language,tool-calling
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: asyncpg>=0.30.0
Requires-Dist: bcrypt>=4.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: jsonschema>=4.20
Requires-Dist: litellm>=1.40.0
Requires-Dist: numpy>=1.24
Requires-Dist: passlib[bcrypt]>=1.7
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: sqlalchemy[asyncio]>=2.0
Requires-Dist: structlog>=24.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# VibeServer

**Prompt-driven backend framework.** Replace REST endpoints with natural language.

```bash
pip install vibeserver
```

```python
from vibeserver import VibeServer

vs = VibeServer()
@vs.tool("greet", description="Greet a user by name")
def greet(name: str) -> dict:
    return {"message": f"Hello, {name}!"}

vs.run()  # starts at http://localhost:8000
```

Then call it:
```python
from vibeserver import VibeClient
async with VibeClient("http://localhost:8000") as client:
    result = await client.vibe("greet Alice")
    print(result.data)  # {"message": "Hello, Alice!"}
```

## How It Works

Instead of `POST /api/greet {"name": "Alice"}`:

1. Send natural language: `POST /` with `{"input": "greet Alice"}`
2. LLM plans execution: `{steps: [{action: "greet", params: {name: "Alice"}}]}`
3. Tool executes and returns structured JSON
4. Repeat calls match the **Intent Graph** — no LLM needed

## Quick Start

```bash
# Scaffold a new project
vibeserver init my-app
cd my-app

# Edit app.py to add your tools, then:
vibeserver serve

# Open http://localhost:8000 for the Web UI
```

## SDK: Embedded Mode

```python
from fastapi import FastAPI
from vibeserver import VibeServer

app = FastAPI()
vs = VibeServer()

@vs.tool("search_users", description="Search users by name")
def search_users(query: str, limit: int = 10) -> dict:
    results = db.query(f"SELECT * FROM users WHERE name LIKE '%{query}%' LIMIT {limit}")
    return {"users": results}

# Mount under existing FastAPI app
app.mount("/vibe", vs.asgi("my-app"))
```

## Client: Remote Access

```python
from vibeserver import VibeClient

async with VibeClient("http://vibe:8000", api_key="vs_xxx") as client:
    # Natural language execution
    result = await client.vibe("search users named Alice")
    
    # Streaming (SSE)
    async for event in client.stream("create a report for Q3"):
        print(event["type"], event)

    # Direct API
    tools = await client.list_tools()
    metrics = await client.metrics()
```

## Built-in Tools (9 included)

| Tool | Description |
|---|---|
| `compute` | Transform data (uppercase, lowercase, json_parse, sum, length) |
| `create_record` | Create a database record |
| `search` | Search records by type |
| `update_record` | Update a record |
| `delete_record` | Delete a record |
| `get_user` | Look up user by ID |
| `auth` | Verify API keys |
| `list_users` | List all users (admin) |
| `stats` | System statistics |

## Configuration

```env
VIBESERVER_MODEL=openai/cmd/deepseek/deepseek-v4-pro
VIBESERVER_API_BASE=http://localhost:20128/v1
VIBESERVER_API_KEY=sk-xxx
VIBESERVER_DB_PATH=vibeserver.db
VIBESERVER_LOG_LEVEL=INFO
```

Or pass directly:
```python
vs = VibeServer(
    model="openai/cmd/deepseek/deepseek-v4-pro",
    api_base="http://localhost:20128/v1",
    api_key="sk-xxx",
)
```

## Docker

```bash
docker compose up
```

## Architecture

```
POST / {"input": "create a note saying hello"}
  → Guardrails (prompt injection check)
  → Intent Graph: match cached plan?
      YES → ParamExtractor fills slots → execute
      NO  → LLM Planner → validate → new node → execute
  → Responder → {"status": "success", "data": {...}}
```

Full architecture docs: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)

## License

MIT
