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)

التثبيت

pip install forge-cli-tools

للتطوير (يشمل pytest + httpx):

cd packages/forge-core
uv pip install -e ".[dev]"

البداية السريعة

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 بسيطة

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

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

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")

الاختبارات

cd packages/forge-core
pytest -v

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

البناء والنشر

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.