Metadata-Version: 2.4
Name: opensculpt
Version: 0.1.6
Summary: OpenSculpt — The Self-Evolving Agentic OS
Author: Abhishek M Shivalingaiah
License-Expression: Apache-2.0
Project-URL: Homepage, https://opensculpt.ai
Project-URL: Repository, https://github.com/opensculpt/opensculpt
Project-URL: Issues, https://github.com/opensculpt/opensculpt/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.40.0
Requires-Dist: typer[all]>=0.12.0
Requires-Dist: rich>=13.9.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pydantic-settings>=2.5.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: orjson>=3.10.0
Requires-Dist: structlog>=24.4.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: packaging>=24.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: websockets>=13.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3.0; extra == "dev"
Requires-Dist: ruff>=0.7.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/opensculpt/opensculpt/main/openSulpt_text.png" alt="OpenSculpt" width="500">
</p>

<h3 align="center">The Self-Evolving Agentic OS</h3>

<p align="center">
  <a href="https://github.com/opensculpt/opensculpt/stargazers"><img src="https://img.shields.io/github/stars/opensculpt/opensculpt?style=social" alt="GitHub Stars"></a>
  <a href="https://pypi.org/project/opensculpt/"><img src="https://img.shields.io/pypi/v/opensculpt" alt="PyPI version"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
  <a href="https://github.com/opensculpt/opensculpt/actions"><img src="https://img.shields.io/github/actions/workflow/status/opensculpt/opensculpt/ci.yml?label=tests" alt="Tests"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-green.svg" alt="License"></a>
</p>

<p align="center">
  <a href="https://codespaces.new/OpenSculpt/opensculpt?quickstart=1"><img src="https://github.com/codespaces/badge.svg" alt="Open in GitHub Codespaces"></a>
  <a href="vscode://vscode.git/clone?url=https://github.com/OpenSculpt/opensculpt.git"><img src="https://img.shields.io/badge/Open%20in-VS%20Code-007ACC?logo=visual-studio-code&logoColor=white" alt="Open in VS Code"></a>
  <a href="https://gitpod.io/#https://github.com/OpenSculpt/opensculpt"><img src="https://gitpod.io/button/open-in-gitpod.svg" alt="Open in Gitpod"></a>
</p>

**Every failure is a chisel strike. Every fix reveals a better shape.** 🐧🪨

OpenSculpt is not another agent framework. It's an operating system for intelligence. You speak naturally, it reasons, plans, spawns agents, executes, remembers, and evolves — driven by what you actually need, not random research papers. Claude Code, Cursor, Windsurf are the chisels. The OS is the stone. Like Tux represents Linux, Chip (the self-sculpting penguin) represents an OS that shapes itself.

```bash
sculpt "why is my API slow?"
# → Spawns analyst agent, profiles endpoints, checks logs, reports findings

sculpt "write a REST API for user management with tests and docs"
# → Assembles a team: architect → coder → [tester + documenter in parallel]
```

## Try It Free

**No install needed** — explore OpenSculpt directly in your browser:

| Method | What you get | Time to start |
|--------|-------------|---------------|
| [![Open in Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/OpenSculpt/opensculpt?quickstart=1) | Full dev environment + dashboard auto-launches on port 8420 | ~60s |
| [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/OpenSculpt/opensculpt) | Same setup via Gitpod | ~90s |

> GitHub Codespaces gives **120 free core-hours/month** on every GitHub account — enough to explore for days.

Once the Codespace starts, the dashboard opens automatically. Set your API key in the terminal to unlock the full OS:

```bash
export SCULPT_LLM_API_KEY=your-key-here
sculpt "analyze this codebase"
```

## Install

### pip

```bash
pip install opensculpt
```

### From Source

```bash
git clone https://github.com/opensculpt/opensculpt.git
cd opensculpt
pip install -e ".[dev]"
```

> **Note:** If `sculpt` isn't found after install, use `python -m agos` instead.

### Windows Executable

Download `OpenSculpt.exe` from the [latest release](https://github.com/opensculpt/opensculpt/releases/latest).

## Quick Start

```bash
# Set your API key (Anthropic, OpenRouter, or any supported provider)
export SCULPT_LLM_API_KEY=your-key-here

# Initialize workspace
sculpt init

# Talk to it via CLI
sculpt "analyze my codebase and summarize what each module does"
sculpt "find all TODO comments and prioritize them"

# Or launch the web dashboard
python -m agos.serve
# Opens http://localhost:8420
```

## Architecture

```
+------------------------------------------------------------------+
|                         OpenSculpt                                  |
|                                                                   |
|   INTERFACE    Natural Language CLI  |  Dashboard  |  SDK         |
|                         |                                         |
|   SOUL         Intent Engine (understand → plan → execute)        |
|                         |                                         |
|   BRAIN        Agent Kernel (lifecycle, state, budget)            |
|                         |                                         |
|   MEMORY       Knowledge System (episodic + semantic + graph)     |
|                         |                                         |
|   BODY         Tool Bus (file, shell, HTTP, Python, web search)   |
|                         |                                         |
|   SENSES       Triggers (file watch, cron, webhooks)              |
|                         |                                         |
|   SOCIAL       Coordination (channels, teams, debate protocol)    |
|                         |                                         |
|   IMMUNE       Policy Engine + Audit Trail                        |
|                         |                                         |
|   EVOLUTION    Demand-Driven Self-Evolution (failures → research  |
|                → code generation → sandbox → deploy)              |
+------------------------------------------------------------------+
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `sculpt "<intent>"` | Natural language — the OS figures out what to do |
| `sculpt ps` | List running agents |
| `sculpt recall "<topic>"` | Search knowledge system |
| `sculpt timeline` | View event history |
| `sculpt watch <path> "<intent>"` | Watch files, trigger agent on changes |
| `sculpt schedule <interval> "<intent>"` | Run agent on a schedule |
| `sculpt team "<task>"` | Multi-agent team execution |
| `sculpt evolve` | Run R&D cycle (scan arxiv, analyze, propose) |
| `sculpt evolve --proposals` | View pending evolution proposals |
| `sculpt ambient --start` | Start background watchers |
| `sculpt proactive --scan` | Run pattern detection |
| `sculpt audit` | View audit trail |
| `sculpt policy` | Configure safety policies |
| `sculpt dashboard` | Launch web monitoring UI |
| `sculpt update` | Check for updates and self-update |
| `sculpt version` | Show version |

## Configuration

All settings via environment variables with `SCULPT_` prefix:

| Variable | Default | Description |
|----------|---------|-------------|
| `SCULPT_LLM_API_KEY` | (required) | Your LLM API key (Anthropic, OpenRouter, etc.) |
| `SCULPT_DEFAULT_MODEL` | `anthropic/claude-haiku-4-5` | Claude model to use |
| `SCULPT_WORKSPACE_DIR` | `.opensculpt` | Local workspace directory |
| `SCULPT_MAX_CONCURRENT_AGENTS` | `50` | Max agents running at once |
| `SCULPT_DASHBOARD_PORT` | `8420` | Dashboard web UI port |
| `SCULPT_LOG_LEVEL` | `INFO` | Logging level |

## Self-Evolution

OpenSculpt evolves itself based on what you actually need:

1. **Detect** — Collects demand signals from user failures, tool errors, missing capabilities, agent crashes
2. **Scout** — Searches arxiv for papers that address actual problems (not random topics)
3. **Analyze** — Extracts actionable techniques from each paper
4. **Generate** — LLM writes code implementing the technique, with demand context injected
5. **Test** — Runs code patterns in a sandboxed environment
6. **Deploy** — Applies sandbox-passing code as live evolved strategies
7. **Learn** — Records what worked and what failed for cross-cycle learning

```bash
sculpt evolve                    # Run a full R&D cycle
sculpt evolve --proposals        # Review what it found
sculpt evolve --accept <id>      # Accept a proposal
sculpt evolve --apply <id>       # Apply it (with auto-rollback on failure)
```

**Every failure is a chisel strike. Every fix reveals a better shape.** The OS sculpts itself — shaped by AI coding tools on every user's machine.

## Security

OpenSculpt is an **operating system** — it executes shell commands, writes files, makes HTTP requests, and manages Docker containers by design. This is equivalent to giving it `sudo` access.

**Before exposing to a network:**
- Set `SCULPT_DASHBOARD_API_KEY` to a strong random value
- Set `SCULPT_APPROVAL_MODE` to `confirm-dangerous` (default is `auto`)
- Do **not** expose port 8420 to the public internet without auth

**By design, the OS agent can:**
- Execute arbitrary shell commands and Python code
- Read/write any file on the filesystem
- Make HTTP requests to any URL
- Manage Docker containers via the Docker socket

This is intentional — it's an OS, not a sandboxed app. Treat it like SSH access to a server.

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -v          # 779+ tests
ruff check agos/ tests/   # lint
```

## License

Apache License 2.0. See [LICENSE](LICENSE).
