Metadata-Version: 2.4
Name: forgecraft
Version: 0.1.0a1
Summary: AI software delivery platform. Hire AI Professionals, not chatbots. Describe your goal and receive finished deliverables.
Author: Forge Framework Contributors
License: MIT
Project-URL: Homepage, https://github.com/umerfarooq771/forgeOS
Project-URL: Repository, https://github.com/umerfarooq771/forgeOS
Project-URL: Bug Tracker, https://github.com/umerfarooq771/forgeOS/issues
Project-URL: Documentation, https://github.com/umerfarooq771/forgeOS#readme
Keywords: ai,software-delivery,ai-professional,product-development,code-generation,llm,anthropic,openai,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40.0; extra == "anthropic"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: anthropic>=0.40.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# Forge

**Hire AI Professionals. Not chatbots.**

[![PyPI](https://img.shields.io/pypi/v/forgecraft?label=forgecraft&color=blue)](https://pypi.org/project/forgecraft/)
[![Python](https://img.shields.io/pypi/pyversions/forgecraft)](https://pypi.org/project/forgecraft/)
[![CI](https://github.com/umerfarooq771/forgeOS/actions/workflows/ci.yml/badge.svg)](https://github.com/umerfarooq771/forgeOS/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/umerfarooq771/forgeOS/blob/main/LICENSE)
[![Status](https://img.shields.io/badge/status-alpha-orange)](https://github.com/umerfarooq771/forgeOS)

---

Forge is an **AI software delivery platform**. You describe what you want. Forge assigns a senior AI Professional, conducts a discovery conversation, builds a team, and executes — returning finished deliverables while you focus on what matters.

- Build software products
- Validate architecture
- Review code and systems
- Generate technical documentation
- Research and analyse problems
- Execute complete engineering projects

---

## How it works

```
You
 │
 ▼
Talk to one AI Professional
 │  Solution Architect · Product Manager · Security Consultant · and more
 ▼
Discovery conversation
 │  Your Professional asks only what they need to know
 ▼
Understanding confirmed
 │  You correct anything that's wrong before planning begins
 ▼
Review the recommendation
 │  Team · Models · Estimated cost · Deliverables · Timeline
 ▼
You approve
 │  Nothing starts without your explicit sign-off
 ▼
Close your laptop
 │  Forge continues working autonomously
 ▼
Deliverables ready
    Requirements · Architecture · API Spec · Database Design
    UI Plan · Testing Strategy · Deployment Plan
```

---

## See it in action

```
$ forge

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    Forge

────────────────────────────────────────────────────────────

    What would you like to build?

    │  An AI-powered expense management platform for SMEs

    Thinking…

────────────────────────────────────────────────────────────

    AI Solution Architect

    Hello. I'll work with you to understand your project
    before recommending the best approach.

    What problem are you solving, and who experiences it most?

    ›  Finance teams waste hours on manual expense reconciliation
       with no real-time visibility for management.

    That's a real problem. One more question: are you building
    this for one company, or as a product to sell?

    ›  A product — targeting SMEs with 10–200 employees.

    HERE'S WHAT I UNDERSTOOD

    You want to build an AI-powered expense management platform
    for finance teams at SMEs.

    Did I understand this correctly?
    ›  yes

    HERE IS MY RECOMMENDATION

    YOUR PROJECT TEAM

    ✓  Product Owner
       Owns business priorities and ensures every decision
       serves your goals.

    ✓  Solution Architect
       Designs the overall solution and ensures it can scale.

    ✓  Backend Engineer
       Builds the APIs, services, and data layer.

    ✓  Frontend Engineer
       Builds the user-facing experience.

    ✓  QA Engineer
       Validates quality before delivery.

    YOUR EXECUTION PLAN

    Product Owner          Claude Haiku
                           Discovery and requirements — fast and cost-efficient.
                           Estimated: $0.18

    Solution Architect     Claude Sonnet
                           Architectural reasoning requires deeper analysis.
                           Estimated: $0.82

    Backend Engineer       Claude Sonnet
                           Reliable implementation across the full stack.
                           Estimated: $1.18

    Frontend Engineer      Claude Sonnet
                           UI implementation and component design.
                           Estimated: $0.94

    QA Engineer            Claude Haiku
                           Fast validation and test coverage analysis.
                           Estimated: $0.31

    ────────────────────────────────────────────────────────

    Estimated total                               $3.43
    Forge Credits                                 ~350 credits
    Timeline                                      2–3 weeks

    DELIVERABLES
    ✓  Requirements document
    ✓  System architecture
    ✓  API specification
    ✓  Database design
    ✓  UI design plan
    ✓  Testing strategy
    ✓  Deployment plan

    Type yes to approve, or no to adjust anything.
    ›  yes

    ✓  Project approved.

    Your team is beginning work.

    [10:15]  Requirements have been drafted.
    [10:16]  System architecture designed.
    [10:16]  API specification complete.
    [10:17]  All deliverables complete.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

    PROJECT COMPLETE

    Your team has completed the engagement.

    DELIVERABLES

    ✓  Requirements document
    ✓  System architecture
    ✓  API specification
    ✓  Database design
    ✓  UI design plan
    ✓  Testing strategy
    ✓  Deployment plan

    RECOMMENDED NEXT STEPS

    •  Review the requirements document with your team
    •  Validate the architecture with your technical lead
    •  Use the API specification to begin engineering planning
```

---

## Why Forge?

| | |
|---|---|
| **One Professional, not a chat window** | Forge assigns one specialist for your request — an AI Solution Architect, Product Manager, Marketing Strategist, or Security Consultant. One conversation. One point of contact. |
| **Specialists, not generalists** | Behind every project is a full team: a Product Owner who defines requirements, an Architect who designs the system, Engineers who implement, a QA Engineer who validates. Each one expert in their domain. |
| **The right model for every task** | Forge selects the best model for each phase — a fast, efficient model for discovery, a reasoning-capable model for architecture, a code-focused model for implementation. You benefit from the full market, automatically. |
| **Know the cost before work begins** | Before anything runs, Forge shows you the estimated cost per team member, per model, and in total. You approve the budget. Nothing starts without your sign-off. |
| **You stay in control** | Forge confirms understanding before planning. You approve the plan before execution. You review deliverables before the engagement closes. Approval gates at every step. |
| **Work continues while you sleep** | After you approve, the team executes autonomously. You come back to completed deliverables — not an unfinished conversation thread. |
| **Provider independent** | Forge works with Anthropic today. Designed from the ground up to work with OpenAI, Google, Mistral, Ollama, or any future provider — without changing your projects. |

---

## Install

Requires Python 3.12+.

```bash
pip install "forgecraft[anthropic]"
export ANTHROPIC_API_KEY=your-key
forge
```

**No API key?** Try the full demo instantly:

```bash
git clone https://github.com/umerfarooq771/forgeOS
cd forgeOS && pip install -e .
python examples/example_03_full_execution.py
```

---

## What Forge delivers

Seven professional project documents — the foundation your engineering team needs to build:

| Deliverable | What it contains |
|-------------|-----------------|
| **Requirements document** | User stories, acceptance criteria, prioritised feature list |
| **System architecture** | Component diagram, technology decisions, infrastructure overview |
| **API specification** | Endpoint definitions, request/response formats, authentication |
| **Database design** | Schema, relationships, indexes, migration strategy |
| **UI design plan** | Screen inventory, design system, accessibility requirements |
| **Testing strategy** | Test levels, critical scenarios, coverage targets |
| **Deployment plan** | CI/CD pipeline, environment strategy, rollback procedures |

---

## BYOK — Bring Your Own Keys

In Alpha, you connect your own AI provider API keys. Forge orchestrates across them.

```bash
# Anthropic (supported today)
export ANTHROPIC_API_KEY=sk-ant-...

# More providers coming in 0.2
# export OPENAI_API_KEY=sk-...
# export GOOGLE_API_KEY=...
```

You pay providers directly. Forge handles orchestration, model selection per phase, and prompt engineering — you never write a prompt or manage model routing.

---

## Forge Credits — coming soon

In a future release, Forge will offer **Forge Credits** — a unified balance that works across all providers.

- No API keys to manage
- No provider accounts to maintain
- Forge selects the best available model for every task automatically
- One bill, all providers
- Enterprise-ready from day one

Buy credits once. Forge does the rest.

---

## Roadmap

**Phase 1 — Bring Your Own Keys (current)**

Connect your own API keys for Claude, OpenAI, Gemini, OpenRouter, Azure OpenAI, AWS Bedrock, or Ollama. You pay providers directly. Forge orchestrates everything.

**Phase 2 — Forge Credits**

No more managing API keys or provider accounts. Buy Forge Credits. Forge automatically allocates the right models across providers, optimises cost, and returns a single bill.

---

**Release timeline**

| Version | Focus |
|---------|-------|
| **0.1 — Alpha** (now) | Core delivery: discovery, planning, execution, 7 deliverables |
| **0.2** | Real deliverables — model-generated content, streaming |
| **0.3** | Tool integrations — GitHub, Supabase, Browser |
| **0.4** | Persistent projects — resume, share, collaborate |
| **0.5** | Multi-provider — OpenAI, Gemini, Ollama, Bedrock |
| **1.0** | Production release — stable API, full documentation |

---

## Alpha status

Forge 0.1 is functional end-to-end. It is an alpha — not production-ready, and breaking changes will occur before 1.0.

| Capability | Status |
|------------|--------|
| Discovery conversation | ✓ Available |
| AI Professional assignment | ✓ Available |
| Vision confirmation | ✓ Available |
| Team recommendations | ✓ Available |
| Forge Credits estimation | ✓ Available |
| Project deliverables (7 documents) | ✓ Available |
| Approval gates | ✓ Available |
| Working code generation | 0.2 |
| Tool integrations (GitHub, Supabase) | 0.3 |
| Persistent projects | 0.4 |
| Multi-provider (OpenAI, Gemini) | 0.5 |
| Forge Credits unified billing | Future |

---

## Python API

```python
import asyncio, os
from forgecraft.alpha.runner import run_full
from forgecraft.platform.models.anthropic_adapter import AnthropicAdapter
from forgecraft.platform.audit.log import InMemoryAuditLog

async def main():
    audit_log = InMemoryAuditLog()
    model = AnthropicAdapter(
        api_key=os.environ["ANTHROPIC_API_KEY"],
        audit_log=audit_log,
    )
    alpha_result, exec_result = await run_full(
        user_input="Build a task management platform for remote teams",
        model=model,
        audit_log=audit_log,
    )
    if exec_result:
        for deliverable in exec_result.artifacts:
            print(deliverable.title)

asyncio.run(main())
```

---

## Documentation

**Getting started**
- [Quick Start](docs/QUICK_START.md) — install and run in five minutes
- [CLI Guide](docs/CLI_GUIDE.md) — every screen explained
- [FAQ](docs/FAQ.md) — common questions

**For developers**
- [Developer Guide](docs/DEVELOPER_GUIDE.md) — Python API, custom providers, extension points
- [Changelog](CHANGELOG.md) — what changed and when
- [Roadmap](ROADMAP.md) — what's coming

**For contributors**
- [Contributing](CONTRIBUTING.md) — how to contribute
- [Runtime Internals](docs/RUNTIME_INTERNALS.md) — scheduling, lifecycle, events
- [Architecture](docs/architecture/CORE_ARCHITECTURE.md) — engine design

---

## Examples

```bash
python examples/example_03_full_execution.py   # Full journey, no API key needed
python examples/example_01_quick_question.py   # Quick question
python examples/example_02_expert_review.py    # Expert review
python examples/example_04_python_api.py       # Python API (requires API key)
python examples/example_05_custom_provider.py  # Custom provider
```

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

---

## License

MIT — see [LICENSE](LICENSE).
