Metadata-Version: 2.4
Name: forge-cli-tools
Version: 0.2.0
Requires-Python: >=3.10
Requires-Dist: forge-framework>=0.2.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# Forge

Python-first framework لبناء خدمات ووكلاء ذكاء اصطناعي (AI microservices & agents) بسهولة، مع خطة واضحة لتسريع الأجزاء الحرجة عبر Rust مستقبلاً.

## الميزات

- **Python-first**: كل الكود Python صرف، سهل القراءة والتعديل
- **FastAPI تحت الغطاء**: Swagger UI تلقائي على `/docs`، OpenAPI على `/openapi.json`
- **Decorators بسيطة**: `@app.service`, `@app.route`, `@app.agent`
- **Agents مع tools**: سجّل tools async واستدعها عبر `call_tool`
- **CLI جاهز**: `forge new` و `forge run`
- **Validation تلقائي**: عبر Pydantic models للـ request bodies
- **خطة تسريع بـ Rust**: مكوّنات حرجة فقط، عند الحاجة الفعلية (انظر `ROADMAP.md`)

## التثبيت
```bash
pip install forge-cli-tools
```

للتطوير (يشمل pytest + httpx):
```bash
cd packages/forge-core
uv pip install -e ".[dev]"
```

## البداية السريعة
```bash
forge new my-app
cd my-app
forge run
```

ثم افتح المتصفح:
- `http://localhost:8000/hello` — endpoint الذي ولّده الـ CLI
- `http://localhost:8000/docs` — Swagger UI تلقائي
- `http://localhost:8000/openapi.json` — مواصفات OpenAPI

## مثال: خدمة GET بسيطة
```python
import forge

app = forge.App("my-app")

@app.service(name="hello")
class HelloService:
    @app.route("GET", "/hello")
    async def hello(self) -> dict:
        return {"message": "Hello, Forge!"}

if __name__ == "__main__":
    app.serve()
```

## مثال: POST مع body validation
```python
import forge
from pydantic import BaseModel, Field

app = forge.App("api")

class SummarizeRequest(BaseModel):
    text: str = Field(..., min_length=1)
    max_words: int = Field(default=50, ge=1, le=500)

@app.service(name="summarizer")
class SummarizerService:
    @app.route("POST", "/summarize")
    async def summarize(self, body: SummarizeRequest) -> dict:
        words = body.text.split()
        return {"summary": " ".join(words[: body.max_words])}

if __name__ == "__main__":
    app.serve()
```

## مثال: Agent مع tools
```python
import forge

app = forge.App("agent-app")

class UpperAgent(forge.Agent):
    async def step(self, input):
        return await self.call_tool("upper", input)

@app.agent(name="upper")
class RegisteredUpperAgent(UpperAgent):
    def __init__(self):
        super().__init__()
        async def _upper(text: str) -> str:
            return text.upper()
        self.register_tool("upper", _upper)

# داخل أي route:
# agent = app.get_agent("upper")
# result = await agent.run("hello")
```

## الاختبارات
```bash
cd packages/forge-core
pytest -v
```

يغطّي 16 اختباراً: services, routes (GET + POST + validation),
agents (tools, state, registration, abstract class enforcement).

## البناء والنشر
```bash
cd packages/forge-core
uv build          # يُنتج dist/forge_framework-0.1.0-*.whl و .tar.gz
uv publish        # يحتاج UV_PUBLISH_TOKEN
```

## هيكل المستودع
```
forge/
├── pyproject.toml              # uv workspace root
├── README.md
├── LICENSE                     # MIT
├── ROADMAP.md                  # خطة المرحلة 2 و 3 (Rust)
├── .github/workflows/ci.yml    # GitHub Actions: pytest on push
├── examples/
│   └── quickstart/main.py
└── packages/
    ├── forge-core/             # الحزمة الأساسية المنشورة على PyPI
    │   ├── pyproject.toml
    │   ├── README.md
    │   ├── forge/
    │   │   ├── __init__.py
    │   │   ├── app.py          # App class (FastAPI wrapper)
    │   │   ├── agent.py        # Agent ABC + tools
    │   │   └── config.py       # ForgeSettings (pydantic-settings)
    │   └── tests/
    │       ├── test_app.py
    │       ├── test_agent.py
    │       └── test_routes_post.py
    └── forge-cli/              # CLI مستقل (forge new / forge run)
        ├── pyproject.toml
        └── forge_cli/main.py
```

## الرخصة
MIT — انظر ملف `LICENSE`.
