Metadata-Version: 2.4
Name: guideai
Version: 0.1.0
Summary: GuideAI developer tooling and task orchestration helpers
Author: GuideAI Team
License: Apache-2.0
Project-URL: Homepage, https://amprealize.ai
Project-URL: Documentation, https://amprealize.ai/docs
Project-URL: Source, https://github.com/SandRiseStudio/guideai
Project-URL: Bug Tracker, https://github.com/SandRiseStudio/guideai/issues
Project-URL: Changelog, https://github.com/SandRiseStudio/guideai/blob/main/BUILD_TIMELINE.md
Keywords: guideai,cli,developer-tools
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<1.0,>=0.110
Requires-Dist: uvicorn<1.0,>=0.30
Requires-Dist: httpx<0.29,>=0.27
Requires-Dist: click<9.0,>=8.1
Requires-Dist: keyring<25,>=24
Requires-Dist: python-multipart<1.0,>=0.0.6
Requires-Dist: pydantic<3.0,>=2.5
Requires-Dist: pydantic-settings<3.0,>=2.1
Requires-Dist: boto3<2.0,>=1.28
Requires-Dist: PyJWT<3.0,>=2.8
Requires-Dist: bcrypt<5.0,>=4.1
Requires-Dist: openai<2.0,>=1.0
Requires-Dist: anthropic<1.0,>=0.40
Requires-Dist: sqlalchemy<3.0,>=2.0
Requires-Dist: psycopg2-binary<3.0,>=2.9
Requires-Dist: redis<6.0,>=5.0
Requires-Dist: alembic<2.0,>=1.13
Requires-Dist: podman<6.0,>=5.0
Requires-Dist: pyyaml<7.0,>=6.0
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=7.4; extra == "dev"
Requires-Dist: pytest-cov<6.0,>=4.1; extra == "dev"
Requires-Dist: pytest-asyncio<1.0,>=0.21; extra == "dev"
Requires-Dist: pytest-xdist<4.0,>=3.5; extra == "dev"
Requires-Dist: pytest-timeout<3.0,>=2.2; extra == "dev"
Requires-Dist: pytest-mock<4.0,>=3.12; extra == "dev"
Requires-Dist: black<25.0,>=23.0; extra == "dev"
Requires-Dist: isort<6.0,>=5.12; extra == "dev"
Requires-Dist: flake8<8.0,>=6.0; extra == "dev"
Requires-Dist: mypy<2.0,>=1.5; extra == "dev"
Provides-Extra: telemetry
Requires-Dist: kafka-python<3.0,>=2.0; extra == "telemetry"
Requires-Dist: duckdb<2.0,>=1.1; extra == "telemetry"
Requires-Dist: pytz>=2023.3; extra == "telemetry"
Requires-Dist: psycopg2-binary<3.0,>=2.9; extra == "telemetry"
Provides-Extra: redis
Requires-Dist: redis<6.0,>=5.0; extra == "redis"
Provides-Extra: postgres
Requires-Dist: sqlalchemy<3.0,>=2.0; extra == "postgres"
Requires-Dist: psycopg2-binary<3.0,>=2.9; extra == "postgres"
Requires-Dist: prometheus_client<1.0,>=0.19; extra == "postgres"
Requires-Dist: alembic<2.0,>=1.13; extra == "postgres"
Provides-Extra: semantic
Requires-Dist: sentence-transformers<3.0,>=2.2.0; extra == "semantic"
Requires-Dist: faiss-cpu<2.0,>=1.7.0; extra == "semantic"
Provides-Extra: ml
Requires-Dist: sentence-transformers<3.0,>=2.2.0; extra == "ml"
Requires-Dist: faiss-cpu<2.0,>=1.7.0; extra == "ml"
Requires-Dist: torch<3.0,>=2.0; extra == "ml"
Requires-Dist: scipy<2.0,>=1.10; extra == "ml"
Provides-Extra: amprealize
Requires-Dist: amprealize[cli]>=0.1.0; extra == "amprealize"
Provides-Extra: enterprise
Requires-Dist: guideai-enterprise>=0.1.0; extra == "enterprise"
Dynamic: license-file

# GuideAI — The Behavior Engine for AI Agents

[![CI](https://img.shields.io/badge/CI-passing-brightgreen)]()
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Platforms](https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)]()

**Turn your LLM chains-of-thought into a reusable procedural handbook — cut reasoning tokens by up to 46% while maintaining or improving quality.**

GuideAI captures recurring AI reasoning patterns as named **behaviors** and conditions agents to reuse them, inspired by [Meta AI's Metacognitive Reuse research](https://arxiv.org/pdf/2509.13237).

---

## Get Started in 30 Seconds

**Cloud** — zero install:
```
→ https://amprealize.ai (sign up and go)
```

**CLI** — for developers:
```bash
pipx install guideai
guideai init
```

**Desktop app:** not shipped from this repository yet; use the **cloud** console, **CLI**, **VS Code extension**, or **MCP** today. Watch [GitHub Releases](https://github.com/SandRiseStudio/guideai/releases) for future desktop builds.

---

## What Is GuideAI?

GuideAI is a **behavior-driven AI workflow platform** that extracts, stores, and retrieves procedural knowledge — reusable how-to strategies — from successful AI reasoning traces. Instead of re-deriving common patterns on every prompt, agents consult a behavior handbook and allocate their compute budget to novel subproblems.

The platform serves three roles:
- **Student** — consumes behaviors in-context for efficient task execution
- **Teacher** — validates behaviors, creates examples, and reviews quality
- **Metacognitive Strategist** — discovers patterns, proposes new behaviors, and curates the handbook

GuideAI works across multiple surfaces: **Web Console**, **CLI**, **VS Code Extension**, and **MCP Server** — with consistent behavior retrieval and execution tracking everywhere.

---

## Features

- **Behavior Engine** — extract, version, retrieve, and apply reusable reasoning patterns
- **MCP Server** — 220+ tools for behaviors, runs, compliance, actions, metrics, and more
- **Multi-Surface Parity** — CLI, REST API, MCP, Web UI, and VS Code extension share the same backend
- **Agent Orchestration** — run agents with behavior-conditioned inference (BCI) for token-efficient execution
- **Compliance & Audit** — full action logging, hash-chained audit trails, and policy enforcement
- **Structured Logging (Raze)** — centralized, queryable, context-enriched telemetry
- **Environment Management (Amprealize)** — blueprint-driven container orchestration with compliance hooks
- **Multi-Tenant** — org-scoped or personal projects with role-based access control
- **OAuth & Device Flow Auth** — GitHub, Google, Microsoft providers with token vault
- **Billing Tiers** — OSS → Starter → Pro → Team → Enterprise

---

## Architecture

```
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│  Web Console │  │  VS Code    │  │    CLI      │
│  (React)     │  │  Extension  │  │  (Click)    │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └─────────────────┴────────┬────────┘
                                  │
                         ┌────────▼────────┐
                         │   FastAPI + MCP  │
                         │   Server         │
                         └────────┬────────┘
                                  │
         ┌────────────────────────┼────────────────────────┐
         │                        │                        │
  ┌──────▼──────┐  ┌──────────────▼──────────────┐  ┌─────▼──────┐
  │  Behavior   │  │  RunService / ActionService  │  │  Raze      │
  │  Service    │  │  ComplianceService           │  │  Telemetry │
  └─────────────┘  └─────────────────────────────┘  └────────────┘
```

---

## Project Structure

```
guideai/
├── guideai/              # Core Python package
│   ├── mcp_tool_manifests/  # Bundled MCP tool JSON (sync from mcp/tools for releases)
│   ├── behaviors/        # Behavior engine
│   ├── mcp/              # MCP server (220+ tools)
│   ├── services/         # Run, Action, Compliance services
│   ├── auth/             # OAuth, device flow, token vault
│   ├── cli/              # CLI commands (Click)
│   ├── config/           # Configuration loader
│   └── storage/          # Storage adapters (SQLite, Postgres)
├── packages/
│   ├── raze/             # Structured logging (standalone)
│   ├── amprealize/       # Environment orchestration (standalone)
│   ├── midnighter/       # Background task scheduler
│   ├── notify/           # Notification service
│   ├── observability/    # Metrics pipeline
│   └── billing/          # Billing & tier management
├── web-console/          # React web UI
├── extension/            # VS Code extension
├── dashboard/            # Grafana metrics dashboard
├── docs/
│   ├── contracts/        # Service contract specs
│   ├── agents/           # Agent role documentation
│   └── research/         # Research papers & references
├── infra/                # Docker, deployment, CI/CD configs
├── tests/                # Test suite
├── scripts/              # Dev & CI scripts
├── mcp/                  # MCP tool JSON schemas
├── migrations/           # Alembic database migrations
└── schema/               # Database schema definitions
```

---

## Documentation

| Document | Description |
|----------|-------------|
| [AGENTS.md](AGENTS.md) | Behavior handbook — roles, behaviors, triggers, checklists |
| [MCP Client Setup](docs/MCP_CLIENT_SETUP.md) | Portable GuideAI MCP setup for VS Code, Cursor, Claude, and other clients |
| [Installation Plan](docs/INSTALLATION_AND_REPO_OPTIMIZATION_PLAN.md) | v3.1 plan with 6 tracks, 39 stories |
| [MCP Server Design](docs/contracts/MCP_SERVER_DESIGN.md) | MCP tool catalog and service contracts |
| [API Contracts](docs/contracts/) | ActionService, RunService, BehaviorService contracts |
| [Audit Log Storage](docs/contracts/AUDIT_LOG_STORAGE.md) | Hash-chained audit trail design |
| [Build Timeline](BUILD_TIMELINE.md) | Chronological build log |

---

## OSS install profiles

| Profile | What you need | Notes |
|--------|----------------|-------|
| **Minimal (solo / local)** | Python 3.10+, `pip install guideai` or `pipx install guideai`, optional `.env` | Use SQLite via `guideai init` and `guideai db migrate`. MCP tools ship in the wheel (`guideai mcp-server doctor` to verify). |
| **Full stack (Postgres, telemetry, etc.)** | Docker or Podman, Postgres, Redis, and the variables in [`.env.example`](.env.example) | See [infra/docker-compose.postgres.yml](infra/docker-compose.postgres.yml) for reference service layout. Heavy dependencies (e.g. Podman, DB clients) are installed with the default package; trim via optional extras only where the project already exposes them. |
| **Contributors (this monorepo)** | Git clone + editable install (below) | Canonical MCP tool JSON lives in `mcp/tools/`; run `python scripts/sync_mcp_tool_manifests.py` after changing manifests so `guideai/mcp_tool_manifests/` stays aligned (CI enforces this). |

## Development

```bash
# Clone and set up
git clone https://github.com/SandRiseStudio/guideai.git
cd guideai
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Install pre-commit hooks
./scripts/install_hooks.sh

# Run tests
pytest

# Generate local MCP configs for VS Code/Cursor/Claude/Codex and smoke-test them
guideai mcp-server init
guideai mcp-server doctor

# Keep GUIDEAI_* runtime settings in .env / .env.local / .env.mcp
# instead of embedding DSNs into editor MCP configs

# Start the server
uvicorn guideai.api:app --reload

# Run secret scan
bash scripts/scan_secrets.sh
```

---

## Contributing

See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for development setup, PR process, commit conventions, and the behavior handbook reference.

Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.

---

## Security

To report security vulnerabilities, please see [SECURITY.md](SECURITY.md). **Do NOT use GitHub Issues for security reports.**

---

## Canonical GitHub repository

Public source of truth: **[github.com/SandRiseStudio/guideai](https://github.com/SandRiseStudio/guideai)**.

**Maintainers (after org or repo moves):** point PyPI [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) at `SandRiseStudio/guideai`, confirm GitHub Actions secrets and environments still apply to this repository, and re-check branch protection and Dependabot on the default branch.

---

## License

[Apache License 2.0](LICENSE)

Copyright 2026 GuideAI Team
